Ask402

How does x402 work, step by step?

Short answer

The caller makes a normal request. The server replies 402 with a PAYMENT-REQUIRED header listing the price and payment options. The caller signs a payment for one option and repeats the request with a PAYMENT-SIGNATURE header. The server verifies and settles it, then returns the result with a PAYMENT-RESPONSE receipt.

The five steps

  1. Ask. The caller sends an ordinary HTTP request, with no payment.
  2. Get the price. The server answers 402 Payment Required. A PAYMENT-REQUIRED header carries the offers: how much, in which token, on which network, paid to which address.
  3. Sign. The caller picks one offer and signs a payment for exactly that amount. Nothing moves yet. The signature is permission for one specific transfer.
  4. Ask again, with payment. The caller repeats the same request and adds a PAYMENT-SIGNATURE header holding the signed payment.
  5. Get the result. The server checks the payment, has it settled on the blockchain, and replies 200 OK with the result and a PAYMENT-RESPONSE header that works as a receipt.

In practice a client library does steps 2 to 4 for you. Your code makes one call and gets one answer.

What the price looks like

The PAYMENT-REQUIRED header is JSON, encoded as base64. Decoded, the example from the specification reads:

{
  "x402Version": 2,
  "error": "PAYMENT-SIGNATURE header is required",
  "resource": {
    "url": "https://api.example.com/premium-data",
    "description": "Access to premium market data",
    "mimeType": "application/json"
  },
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:84532",
      "amount": "10000",
      "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
      "payTo": "0x209693Bc6afc0C5328bA36FaF03C514EF312287C",
      "maxTimeoutSeconds": 60,
      "extra": { "name": "USDC", "version": "2" }
    }
  ]
}

Read it as: pay exactly 10000 units of the token at that address (USDC, which has six decimal places, so $0.01) on network eip155:84532 (Base Sepolia, a test network) to the payTo address, within 60 seconds.

accepts is a list. A server can offer several networks or tokens, and the caller chooses one. The headers and fields reference explains every field.

Who checks the payment

The server can verify and settle payments itself, but most hand the job to a facilitator: a service that checks the signature and submits the transfer to the blockchain. The facilitator never holds the money and cannot change the amount or the recipient.

The status codes

StatusMeaning in x402
402Payment is required, or the payment that was sent failed
400The payment was malformed
200Paid and delivered
500Something went wrong on the server

A failed payment also comes back as 402, with an error code that says why. See x402 error codes.

See it for yourself

Run this in a terminal. It makes an unpaid request and prints the 402 reply:

curl -i "https://agent402.tools/api/search?q=test"

Or paste an address into the 402 checker, which decodes the header for you.

Sources

Facts checked against these sources on . Protocols change, so the official specification wins if it disagrees with this page. Read this page as Markdown.

Who writes this. Ask402 is published by Havok Holdings LLC, which also runs Agent402, one of the x402 services covered here. Agent402 is labelled wherever it appears. Everything else is described from each project’s own documentation, and nobody pays to be listed.