How x402 payments work

x402 is an HTTP payment protocol designed for AI agents. It requires no subscriptions, no API keys, and no human interaction.

The flow

1. Agent sends query — POST a GraphQL query with no payment header
2. Server returns 402 — HTTP 402 Payment Required with a PAYMENT-REQUIRED header describing the cost and payment requirements
3. Agent signs authorization — Create a Permit2 gasless USDC authorization (no gas fee required)
4. Agent retries with payment — Retry the request with the PAYMENT-SIGNATURE header containing the base64-encoded signed payload
5. Facilitator verifies and settles — Coinbase's facilitator at x402.org verifies the signature cryptographically and settles the USDC transfer
6. API returns data — Query executes and returns your results

Why gasless

The payment uses EIP-2612 Permit2 signatures, which means your agent authorizes the transfer cryptographically without broadcasting a separate on-chain transaction. The Coinbase facilitator handles settlement in the background. You pay no ETH gas — only USDC for the data.

The 402 response

When you send a query without payment, the response looks like:

json
{
  "error": "Payment required",
  "details": {
    "amount": "0.000360",
    "currency": "USDC",
    "network": "eip155:8453",
    "recipient": "0xa6E47b07c42bcD68c3D8C97A6161bC831daD8D17",
    "queryCostUnits": 18,
    "costPerUnit": 0.00002
  }
}

The PAYMENT-REQUIRED response header contains a base64-encoded JSON object with the full Permit2 requirements your agent needs to construct the signature.

Replay protection

Each payment signature can only be used once. The facilitator tracks used signatures and rejects any that have already been settled, preventing double-spending.

The payment signature format

The PAYMENT-SIGNATURE header must be a base64-encoded JSON payload:

json
{
  "signature": "0x...",
  "permit": { ... },
  "payer": "0xYourWalletAddress"
}

The exact structure depends on your wallet SDK. Coinbase AgentKit and x402-client construct this automatically.

Testing without payment

• Use the Playground to inspect query costs and test queries without paying. The playground uses a server-side bypass for free exploration.
• Use a developer API key for credit-based access during development.