How x402 works: a paid API call, header by header

HTTP has had a status code for payments since 1997. The HTTP/1.1 specification of that year listed 402 Payment Required and marked it "reserved for future use". It stayed reserved for almost thirty years.

x402 is the protocol that finally puts it to work. Coinbase published it in May 2025. Since April 2026 it is developed by the x402 Foundation under the Linux Foundation, whose members include Cloudflare, Google, Stripe, Visa and Mastercard. The idea fits in one sentence: the server names a price inside the HTTP response, and the client pays inside the next request.

This guide walks through one real paid request, field by field. It is written for developers who want to know what their agent is doing, and for the people who later have to book what it paid.

The short version

A paid x402 call takes two requests.

1. Your agent calls the endpoint without paying. The server answers 402 Payment Required and puts the price in a header.
2. Your agent signs a payment authorization with its wallet and sends the same request again, with the signature in a header.
3. The server checks the signature, does the work, settles the payment on chain and answers 200 OK with the data and a settlement result in a header.

No account, no API key, no invoice. Everything that matters travels in three headers.

All three hold Base64 encoded JSON. Version 1 of the protocol used X-PAYMENT and X-PAYMENT-RESPONSE instead, and some servers still answer that way.

Step 1: the unpaid request

We called CoinGecko's x402 price endpoint on October 31, 2026 at 19:27 UTC, without paying:

GET https://pro-api.coingecko.com/api/v3/x402/simple/price?ids=bitcoin&vs_currencies=usd

The server answered HTTP/1.1 402 Payment Required with a short JSON body ("error": "Payment required") and a PAYMENT-REQUIRED header. Decoded, the header reads like this. We kept the first of its three payment options and left out the discovery block:

{
  "x402Version": 2,
  "resource": {
    "url": "https://pro-api.coingecko.com/api/v3/x402/simple/price",
    "description": "Query prices & market data of coins listed on CoinGecko, by coin IDs, names, or symbols.",
    "mimeType": "application/json"
  },
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "amount": "5000",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "payTo": "0x110cdBba7FE6434Ec4CE3464CC523942ad6Fb784",
      "maxTimeoutSeconds": 60,
      "extra": { "name": "USD Coin", "version": "2" }
    }
  ]
}

Every field has a job.

The full answer also carried an extensions.bazaar block with example inputs and outputs. That block lets discovery services such as the Coinbase Bazaar index the endpoint, so agents can find it without reading any docs.

Step 2: the agent signs, nothing moves yet

The agent picks one option from accepts, usually the network where its wallet holds USDC, and compares the price with its budget. Then it signs.

For the exact scheme on an EVM chain like Base, the default is an EIP-3009 transferWithAuthorization. USDC supports this standard natively. The wallet signs a typed message that says: move this amount from me to this address, valid between these two points in time, with this one time nonce. Tokens without EIP-3009 support can use Permit2 instead.

Two details matter here. Signing costs nothing and moves nothing. And the signature can only ever move that exact amount to that exact payTo, once, before it expires. A server cannot use it to take more.

Step 3: the paid request

The agent repeats the request, now with a PAYMENT-SIGNATURE header that carries the chosen option and the signature.

On the server, the official x402 middleware then does three things in this order.

1. Verify. It checks the signature, the amount, the recipient, the time window and the payer's balance. Most servers hand this to a facilitator, a service with a verify and a settle endpoint, so the seller does not need its own chain infrastructure.
2. Do the work. Only a request with a valid payment reaches the actual handler.
3. Settle. If the handler succeeded, the facilitator submits the signed authorization to the chain. If the handler returned an error, the middleware does not settle, so the agent does not pay for a failed call.

The answer is 200 OK with the data and a PAYMENT-RESPONSE header. Decoded, it says whether settlement worked, on which network, which wallet paid, and the transaction hash.

What ends up on chain

This is where most people get confused the first time they open a block explorer.

The transaction was sent by the facilitator, not by your wallet. The facilitator calls transferWithAuthorization on the USDC contract and pays the gas. Inside that transaction sits the actual USDC transfer, from your wallet to the seller's payTo.

So on Basescan the "From" of the transaction is an address you have never seen, while the token transfer below it shows your wallet. Both are correct. For your books the token transfer is what counts: your wallet, the seller's wallet, the amount and the block time.

It also means your agent needs no ETH for gas. It only needs USDC.

What x402 does not do

x402 moves money and nothing else. Know the gaps before your agent spends real money.

Each of these can be solved, just not by the protocol. We wrote about checking who is behind a wallet, booking x402 payments and VAT on x402 payments.

Beyond the exact scheme

exact is by far the most common scheme today, and the protocol is open to more. The upto scheme lets a client authorize a maximum while the server settles only what was used, which suits metered work such as model tokens. The Machine Payments Protocol by Tempo and Stripe takes a similar route with sessions. How the protocols differ is in x402, MPP, AP2 and ACP compared.

See it yourself

You can read a 402 answer without spending anything. This prints the decoded PAYMENT-REQUIRED header of the endpoint above:

curl -si "https://pro-api.coingecko.com/api/v3/x402/simple/price?ids=bitcoin&vs_currencies=usd" | grep -i '^payment-required' | cut -d' ' -f2 | tr -d '\r' | base64 -d

Nothing is paid until a wallet signs. Our directory lists x402 services together with the wallets they pay to.