x402 Protocol

The payment router for AI agents

Non-custodial x402 router and index. Your agent hits a 402, we quote and route the signed payment on-chain. We never hold funds — just searchable receipts and transparent fees.

View API Docs How It Works

agent.py

resp = http_get(url)

if resp.status == 402:
    payment_req = resp.headers["PAYMENT-REQUIRED"]

    # Get a quote from Agent First API
    quote = router.post("/quote", {
        "paymentRequired": payment_req,
    })

    # Sign and fulfill the payment
    signed = wallet.sign_x402(quote)
    receipt = router.post("/x402/fulfill", {
        "signedPayment": signed,
    })

    # Retry with payment signature
    resp = http_get(url, headers={
        "PAYMENT-SIGNATURE": receipt["signature"]
    })

How It Works

Four steps. No custody.

Your agent encounters a 402, we handle the rest. Funds move directly from agent wallet to merchant wallet on-chain.

Agent hits 402

Your agent makes an HTTP request. The endpoint responds with 402 Payment Required and a payment blob in the header.

Quote the cost

Send the payment blob to POST /quote. Get back merchant amount, router fee (0.25%), total, network, and token.

Sign and fulfill

Agent wallet signs the payment. Send to POST /x402/fulfill. We verify, route to the facilitator, and settle on-chain.

Get the resource

Retry the original request with the payment signature. The endpoint verifies and returns the resource with a 200 OK.

Core Features

Built for agents, not humans

Everything your autonomous agent needs to pay for API access without a human in the loop.

Non-Custodial

We never hold funds. Payments route directly from agent wallet to merchant wallet on-chain via signed authorizations.

Smart Routing

Pick the optimal facilitator and rail per payment. Route by cost, latency, success rate, and agent policy constraints.

Searchable Receipts

Every payment indexed with tx hash, amounts, wallets, resource URL, and metadata. Query by agent, merchant, time, or status.

Discovery Index

Public catalog of x402-enabled endpoints. Search by category, chain, token, price, and SLA. Machine-readable API schemas.

Micro-Payment Friendly

0.25% flat fee with no minimum. A $0.001 API call costs $0.0010025. Sub-cent payments stay economical.

Multi-Chain

Base, Ethereum, Solana, Polygon, Arbitrum — any chain that supports x402. USDC as the default stablecoin rail.

API Reference

Two endpoints. That's it.

A quote endpoint and a fulfill endpoint. The SDK wraps both into a single function call.

POST /quote

Submit a 402 payment blob. Returns a structured quote with merchant amount, router fee, total, network, and token.

{
  "merchantAmount": "0.001000",
  "routerFeeAmount": "0.0000025",
  "routerFeeRate": 0.0025,
  "totalAmount": "0.0010025",
  "network": "base-mainnet",
  "token": "USDC"
}

POST /x402/fulfill

Submit the quote and signed payment. We verify, route on-chain, and return a receipt with tx hash and explorer URL.

{
  "paymentId": "pay_01HV4ZP7...",
  "txHash": "0xabc123...",
  "status": "confirmed",
  "network": "base-mainnet",
  "explorerUrl": "https://..."
}

On-chain receipts as source of truth

Every payment settles on-chain. The tx hash on the blockchain is the canonical reference. We index off-chain metadata for analytics and debugging — never for custody.

Payment ID, tx hash, network, token, amount
Agent wallet, merchant wallet, resource URL
Facilitator, status, timestamp
Custom metadata (invoice ID, x402 payment ID)

GET /payments/{paymentId}

{
  "paymentId": "pay_01HV4ZP7QK8M5S0ZP2YZ9QK4B8",
  "txHash": "0xabc123...",
  "network": "base-mainnet",
  "token": "USDC",
  "amount": "0.0010025",
  "merchantAmount": "0.001000",
  "routerFeeAmount": "0.0000025",
  "from": "0xAgentWallet",
  "to": "0xMerchantWallet",
  "resource": "https://api.example.com/v1/search",
  "status": "confirmed",
  "explorerUrl": "https://explorer.base.org/tx/..."
}

Transparent Fees

0.25%, no minimums

Every quote and receipt shows the exact breakdown. Micro-payments stay micro.

0.25% flat routing fee per payment

$0 minimum fee — sub-cent payments work

On a $0.001 API call, the router fee is $0.0000025. The agent pays $0.0010025 total. The merchant receives $0.001. Every field is explicit in both the quote and receipt JSON.

Gas costs are paid by the agent or sponsored via a paymaster. Network gas is separate from the router fee and varies by chain.

Stripe

2.9% + $0.30

PayPal

2.59% + $0.49

Agent First

0.25%

Discovery API

Find what's payable

A public, read-only index of every x402-enabled endpoint. Search by category, chain, token, or price.

GET /discovery/resources

Browse the full catalog of x402 endpoints. Filter by category, chain, token, max price, and full-text search.

// GET /discovery/resources?category=search&token=USDC

[{
  "id": "res_abc123",
  "resource": "https://api.example.com/v1/search",
  "metadata": {
    "name": "Example Search API",
    "category": "search",
    "indicativePrice": "0.001"
  }
}]

GET /payments

Query the payments index. Filter by agent ID, merchant, resource, network, token, time range, or status.

// GET /payments?agentId=agent_123&status=confirmed

[{
  "paymentId": "pay_01HV4...",
  "amount": "0.0010025",
  "resource": "https://api.example.com/v1/search",
  "status": "confirmed"
}]

Start routing payments

Drop in the SDK, point your agent at any x402 endpoint, and let Agent First handle the rest. Non-custodial. Transparent fees. Searchable receipts.

Join the Waitlist Read x402 Spec