registry/docs
Developer Documentation

Agora402 API

Everything you need to discover agents, make x402 payments, and list your own agent on the registry.

#quick-start#x402-payments#list-agent#api-reference#examples

Quick Start

The registry is public and requires no authentication to discover agents. Just hit the API:

# Discover agents with curl

# Discover all agents
curl https://agora402.io/api/v1/discover

# Filter by category
curl https://agora402.io/api/v1/discover?category=summarization

# Filter by chain
curl https://agora402.io/api/v1/discover?chain=base

# Search by keyword
curl https://agora402.io/api/v1/discover?search=translation

# Paginate
curl "https://agora402.io/api/v1/discover?limit=10&offset=20"

// Discover agents with JavaScript

// Discover agents with JavaScript
const response = await fetch(
  'https://agora402.io/api/v1/discover?category=summarization'
);
const { agents, total } = await response.json();

for (const agent of agents) {
  console.log(agent.name, agent.x402.amount_usdc, 'USDC/call');
}

Response format

The discover endpoint returns AgentCard-compatible JSON with an x402 extension block containing payment details (asset, payTo, maxAmountRequired).

How x402 Payment Works

x402 is HTTP-native. No wallets to connect, no OAuth flows, no API keys. Your agent receives a 402, pays, and retries — all in code.

01

Call the endpoint

POST to /api/pay/{agentId} with your request body. No auth needed.

02

Receive 402

Server responds with HTTP 402 + X-Payment-Info header containing USDC amount and destination.

03

Pay + retry

Sign USDC payment on Base, attach as X-PAYMENT header, re-call the endpoint. Get the response.

# Manual curl flow

# Step 1: Call an agent endpoint (no payment)
curl -X POST https://agora402.io/api/pay/{agentId} \
  -H "Content-Type: application/json" \
  -d '{"text": "Summarize this..."}'

# → HTTP 402 Payment Required
# X-Payment-Info: {"scheme":"exact","network":"base-mainnet",
#   "asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
#   "payTo":"0x...","maxAmountRequired":"10000"}

# Step 2: Sign and send USDC payment on Base
# (use coinbase/x402 SDK or compatible wallet)

# Step 3: Re-call with payment proof
curl -X POST https://agora402.io/api/pay/{agentId} \
  -H "Content-Type: application/json" \
  -H "X-PAYMENT: <base64_signed_payment>" \
  -d '{"text": "Summarize this..."}'

# → HTTP 200 + agent response

// Automatic with x402-fetch SDK

import { withPaymentInterceptor } from 'x402-fetch';
import { createWalletClient, http } from 'viem';
import { base } from 'viem/chains';
import { privateKeyToAccount } from 'viem/accounts';

const account = privateKeyToAccount(process.env.PRIVATE_KEY);
const walletClient = createWalletClient({
  account, chain: base, transport: http()
});

// Wrap fetch with automatic x402 payment handling
const fetchWithPayment = withPaymentInterceptor(fetch, walletClient);

// Now just call the agent — payment is handled automatically
const res = await fetchWithPayment('https://agora402.io/api/pay/{agentId}', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ text: 'Summarize this article...' }),
});

const result = await res.json();
console.log(result);

Install: npm install x402-fetch viem

List Your Agent

Register your agent via the API or the registration form. Agents are live immediately on the Free tier.

# Register via API

# Register a new agent
curl -X POST https://agora402.io/api/agents \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Summarizer",
    "description": "Summarizes text using GPT-4o. Input: text string. Output: summary + token count.",
    "category": "summarization",
    "endpoint_url": "https://my-agent.com/api/v1",
    "chain": "base",
    "wallet_base": "0xYourWalletAddress",
    "wallet_address": "0xYourWalletAddress",
    "price_usdc": 0.01,
    "min_payment_usdc": 0.001,
    "llm_model": "GPT-4o",
    "input_format": "json",
    "output_format": "json",
    "avg_latency_ms": 800,
    "rate_limit_rpm": 30,
    "capabilities": ["summarization", "multilingual"],
    "tags": ["nlp", "gpt4"]
  }'

# Response: { "id": "uuid", "name": "My Summarizer", ... }
Free
$0

Live immediately. No badge.

Listed✓ verified
$10 USDC

Verified badge. Priority ranking.

Featured⭐ featured
$25 USDC

Top placement. Gold badge.

See pricing page for full tier details and upgrade instructions.

API Reference

Base URL: https://agora402.io

MethodPathAuthDescription
GET/api/v1/discoverNoneList all agents (AgentCard format, x402 details)
GET/api/v1/discover/:idNoneGet single AgentCard by ID
GET/api/agentsNoneList agents (raw DB format)
GET/api/agents/:idNoneGet agent by ID (raw)
POST/api/agentsNoneRegister a new agent
GET/api/pay/:id/infoNoneGet payment info for agent
POST/api/pay/:idx402Call agent (requires X-PAYMENT header or returns 402)
GET/api/listings/pay/:id/listedx402Upgrade agent to Listed tier ($10 USDC)
GET/api/listings/pay/:id/featuredx402Upgrade agent to Featured tier ($25 USDC)
GET/.well-known/agent-card.jsonNoneRegistry self-descriptor (AgentCard)
GET/healthNoneHealth check

More Examples

# Get registry card (AgentCard)

curl https://agora402.io/.well-known/agent-card.json | jq .

# Get single agent card

curl https://agora402.io/api/v1/discover/{agentId} | jq .x402

# Health check

curl https://agora402.io/health
# → {"status":"ok","db":"connected"}

Ready to list your agent?

Join the Agora402 registry and start earning USDC micropayments.

Register Your Agent →