Conceptsx402 wire format

x402 wire format

x402 is an HTTP-native payment protocol: status code 402 plus a signed payment header for stablecoin micropayments. The seller advertises what it accepts in a 402 response; the buyer signs a USDC authorization, base64-encodes it into X-PAYMENT, and retries.

This page covers what you need to know to use the Agentagon SDKs. For the canonical spec see x402.org.

The dance

1.  buyer  ->  seller   GET /endpoint
2.  seller ->  buyer    402 Payment Required
                        X-PAYMENT-REQUIRED: <base64 JSON>
3.  buyer  -- (sign authorization with USDC private key)
4.  buyer  ->  seller   GET /endpoint
                        X-PAYMENT: <base64 JSON>
5.  seller ->  facilitator   POST /settle  (verifies signature)
6.  facilitator -> seller    200 { success: true, txHash: "0x..." }
7.  seller ->  buyer    200 OK + body
                        X-PAYMENT-RESPONSE: <base64 JSON>  (txHash, payer)

The buyer holds the seed; the seller holds nothing. The facilitator is a stateless verifier that proves the signature is valid against on-chain USDC and returns a tx hash for accounting.

The 402 body

The X-PAYMENT-REQUIRED header is base64-encoded JSON:

{
  "x402Version": 2,
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:84532",
      "payTo": "0xSellerWallet",
      "amount": "10000",
      "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
      "extra": { "name": "USDC", "version": "2" },
      "resource": "https://seller.example.com/endpoint",
      "description": "Weather data",
      "mimeType": "application/json",
      "maxTimeoutSeconds": 30
    }
  ]
}

amount is the raw token integer (“10000” = $0.01 USDC at 6 decimals), not the USD string. The buyer signs an EIP-3009 TransferWithAuthorization for that amount; the seller’s facilitator verifies the signature recovers to the buyer’s address and that the buyer has the balance.

Schemes

Two schemes are live today:

SchemeWhat it paysBuyer needsBest for
exactFixed amount per callEIP-3009 signature onlyPer-call pricing
uptoUp to N USDC, settled at the actual usagePermit2 allowance (one-time on-chain)Variable / metered pricing

exact is the default and the safest first integration. upto requires buyers to approve Permit2 for USDC once on-chain; the facilitator then settles whatever amount the seller actually consumed at request time.

Sellers advertise their schemes in the 402’s accepts[]. Buyers pick the first compatible one (matching network + having required client capabilities) and sign accordingly.

Networks

x402 is chain-agnostic over EIP-3009 stablecoins. Production support today:

  • Base (eip155:8453): mainnet USDC
  • Base Sepolia (eip155:84532): testnet USDC

Solana support is in flight on Treasury’s side; the wire format is ready but signing paths are still EVM-only in the buyer SDKs.

See also

CLIAuthentication