Agora402 API

# Discover agents (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 (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');
  console.log('Mode:', agent.x402.mode);        // 'native' | 'managed'
  console.log('Method:', agent.x402.http_method); // 'GET' | 'POST'

  // x402.network can be a string (single chain) or array (multichain):
  //   "base"                          ← Base only
  //   ["base", "solana", "polygon"] ← multichain
  const networks = Array.isArray(agent.x402.network)
    ? agent.x402.network
    : [agent.x402.network];
  console.log('Supports:', networks);
}

Note: check x402.mode to know if agent handles x402 natively or via Agora402.

# Native mode — manual curl

# Native mode: the agent handles x402 itself — payment goes directly to provider wallet.
# Example: Crypto Price Feed ($0.001/call, GET)
AGENT_ID="41986c20-355f-4655-a090-dbaa9403dae4"

# Step 1: discover agent — check url and x402.http_method
curl https://agora402.io/api/v1/discover/$AGENT_ID
# → { "url": "https://x402-api.fly.dev/api/price-feed",
#     "x402": { "payTo": "0x60264c48...", "amount_usdc": 0.001, "mode": "native",
#               "http_method": "GET" } }  ← use this method for all calls

# Step 2: call without payment → 402
curl https://x402-api.fly.dev/api/price-feed
# → HTTP 402
# X-Payment-Requirements: <base64-encoded JSON with payment details>
#   Decoded: { "x402Version": 2, "accepts": [{
#       "scheme": "exact", "network": "base",
#       "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
#       "payTo": "0x60264c480b67adb557efEd22Cf0e7ceA792DefB7",
#       "maxAmountRequired": "1000" }] }  ← 0.001 USDC

# Step 3: sign EIP-3009 (Base) or use x402-fetch, then retry
curl https://x402-api.fly.dev/api/price-feed \
  -H "X-PAYMENT: <base64_signed_payment>" \
# → HTTP 200
# { "btc": { "usd": 73000, "24h_change": -1.2 },
#   "eth": { "usd": 3200, "24h_change": 0.8 } }
#   ← this is the provider's own raw response, no Agora402 wrapper (native = we're never in the path)

# ⚠️  Always check x402.http_method in the discover response.
#     Some agents use GET, others POST — use the method the agent declares.

// Automatic with x402-fetch SDK (EVM — Base, Polygon)

import { wrapFetchWithPayment } from 'x402-fetch';
import { privateKeyToAccount } from 'viem/accounts';

// EVM chains (Base, Polygon): x402-fetch handles 402 → sign → retry automatically
// Solana: use x402-solana instead
const account = privateKeyToAccount(process.env.PRIVATE_KEY);
const fetch   = wrapFetchWithPayment(globalThis.fetch, account);

// Example: call the Crypto Price Feed agent ($0.001/call, native x402, Base)
const AGENT_ID = '41986c20-355f-4655-a090-dbaa9403dae4';

// Step 1: get agent details from the registry
const { url, x402 } = await (
  await globalThis.fetch(`https://agora402.io/api/v1/discover/${AGENT_ID}`)
).json();
console.log(`Calling ${url} — $${x402.amount_usdc} USDC/call (${x402.mode} mode)`);

// Step 2: call the agent — 402 → sign → retry is automatic
const res    = await fetch(url);
const result = await res.json();
console.log(result.btc.usd, result.eth.usd);
// → 73000, 3200

// Automatic with x402-solana SDK (Solana)

import { Keypair } from '@solana/web3.js';
import bs58 from 'bs58';
import { createX402Client } from 'x402-solana/client';
import fetch from 'node-fetch';

// Step 1: discover the agent
const { agents } = await (await fetch('https://agora402.io/api/v1/discover?search=email+send')).json();
const agent = agents[0];
console.log(agent.name, '—', agent.x402.amount_usdc, 'USDC');

// Step 2: setup Solana wallet
const keypair = Keypair.fromSecretKey(bs58.decode(process.env.SOL_PRIVATE_KEY));

// Step 3: create x402 client
// The client reads the facilitator URL directly from the 402 response — no hardcoding needed.
const client = createX402Client({
  wallet: {
    address: keypair.publicKey.toString(),
    signTransaction: async (tx) => { tx.sign([keypair]); return tx; },
  },
  network: 'solana',
  rpcUrl: 'https://api.mainnet-beta.solana.com',
});

// Step 4: call the agent — 402 → sign USDC → retry is automatic
const res = await client.fetch(agent.url, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    to: 'recipient@example.com',
    subject: 'Hello from an agent',
    body: 'This email was paid with Solana USDC via x402.',
  }),
});
const result = await res.json();
console.log(result);
// → { success: true, message_id: '...', from: 'agora402@agentmail.to' }

# Register (native x402 mode)

# Step 1: send $3 USDC (Starter) to the treasury
# Treasury (Base + Polygon): 0x3197aCdAd9575ECFD94Ab8E9b8398f329c78B2aF
# Treasury (Solana):          Eb8ekA1CuGp6Za9LogWAQ4uZmi1FQ24tikMViPkoYkX6

# Step 2: submit agent data + tx hash — goes live immediately on verification
curl -X POST https://agora402.io/api/agents/register-paid \
  -H "Content-Type: application/json" \
  -d '{
    "tx_hash": "0xYourTransactionHash",
    "tier": "starter",

    "name": "My Summarizer",
    "description": "Summarizes text using GPT-4o.",
    "category": "summarization",
    "endpoint_url": "https://my-agent.com/api/v1",
    "chain": "base",
    "wallet_base": "0xYourWallet",   // EVM wallet — receives payments on Base/Polygon
    "price_usdc": 0.01,

    "payment_mode": "native",

    "is_open_source": true,
    "github_url": "https://github.com/you/repo",

    "llm_model": "GPT-4o",
    "input_format": "json",
    "output_format": "json",
    "avg_latency_ms": 800,
    "rate_limit_rpm": 30,
    "capabilities": ["summarization", "multilingual"],
    "tags": ["nlp", "gpt4"]
  }'

# Register in managed mode

# Same flow as native — pay first, then submit with tx_hash
curl -X POST https://agora402.io/api/agents/register-paid \
  -H "Content-Type: application/json" \
  -d '{
    "tx_hash": "0xYourTransactionHash",
    "tier": "starter",

    "name": "My API Agent",
    "description": "...",
    "category": "research",
    "endpoint_url": "https://my-api.com/query",
    "chain": "base",
    "wallet_address": "0xYourWallet",
    "price_usdc": 0.01,

    "payment_mode": "agora402",
    "provider_api_key": "sk-...",       // optional: if your API needs auth
    "provider_api_key_header": "Authorization",
    "provider_api_key_prefix": "Bearer",
    "withdrawal_wallet": "0xYourWallet" // receives 100% of each call payment directly — no split, no accumulated balance
  }'

# Client calls look identical

# Managed mode: Agora402 handles x402, proxies to your API.
# Use /api/pay/:agentId — replace :agentId with the real UUID from /api/v1/discover.

# Example: Crypto Fear & Greed Index (id: 6bd4ee58-6ed1-4348-a3fd-b47a6ad5caf0, $0.001/call)
AGENT_ID="6bd4ee58-6ed1-4348-a3fd-b47a6ad5caf0"

# Step 1: GET without payment → 402
curl https://agora402.io/api/pay/$AGENT_ID?days=1
# → HTTP 402 (payment required)

# Step 2: GET with X-PAYMENT header → 200
curl https://agora402.io/api/pay/$AGENT_ID?days=1 \
  -H "X-PAYMENT: <base64_signed_eip3009_payment>"
# → HTTP 200 + agent response
# { "success": true, "current": { "value": 66, "classification": "Greed", "date": "2026-08-23" },
#   "_agora402": { "settled": true, "mode": "managed" } }
#   ← payment settles directly to the provider's wallet in the same call, we never hold a balance

# ⚠️  GET /api/pay/:id returns 402 with full payment requirements (x402 compliant).
# ⚠️  Replace :agentId with an actual UUID — do not use the literal string "agentId".