x402 overview

x402 turns 402 Payment Required — reserved and unused since 1997 — into a working payment handshake. A server that wants paying answers 402 with machine-readable terms. A client that agrees signs a payment and retries. The server verifies, settles on-chain, and returns the resource.

That is the whole idea. What makes it useful for agents is what it does not require: no account, no API key issued in advance, no card on file, no human in the loop, no invoice reconciled later. A client that has never seen a server before can pay it in one round trip.

The four roles#

        ┌─────────┐   1. GET /resource         ┌──────────────────┐
        │ Client  │ ─────────────────────────► │ Resource server  │
        │ (agent) │ ◄───────────────────────── │  (the merchant)  │
        └─────────┘   2. 402 + requirements    └──────────────────┘
             │                                        │
             │ 3. sign authorization                  │ 4. verify + settle
             │                                        ▼
             │                                 ┌──────────────┐
             └──── 5. retry with X-PAYMENT ──► │ Facilitator  │
                                               └──────┬───────┘
                                                      │ 6. broadcast
                                                      ▼
                                                  the chain

• Client. Wants a resource, holds funds, can sign. Usually an agent.
• Resource server. Owns the resource and sets the price. Speaks 402.
• Facilitator. Verifies a signed payment and broadcasts it, paying the gas. Stateless with respect to your funds — it cannot redirect a payment, because the recipient and the amount are inside what the client signed.
• Chain. Where settlement actually happens, and the only party whose record is authoritative.

The facilitator is the piece that makes this practical. Without it, a client needs the chain's native gas token as well as the asset it is paying in, which for an agent means two funding problems instead of one.

The exchange, concretely#

The unpaid request gets terms back:

HTTP/1.1 402 Payment Required
content-type: application/json

{
  "x402Version": 1,
  "error": "payment required",
  "accepts": [
    {
      "scheme": "exact",
      "network": "base",
      "maxAmountRequired": "10000",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "payTo": "0x…",
      "resource": "https://example.com/resource",
      "description": "One weather forecast",
      "maxTimeoutSeconds": 60
    }
  ]
}

accepts is a list because a server may take several assets or chains. The client picks one it recognises, signs for it, and retries with the payload base64-encoded in a header:

GET /resource HTTP/1.1
X-PAYMENT: eyJ4NDAyVmVyc2lvbiI6MSwic2NoZW1lIjoiZXhhY3QiLCJuZXR3b3JrIjoi…

On success the resource comes back with a receipt:

HTTP/1.1 200 OK
X-PAYMENT-RESPONSE: eyJzdWNjZXNzIjp0cnVlLCJ0eEhhc2giOiIweGFiYzEyMyIsIm5l…

X-PAYMENT-RESPONSE decodes to the settlement result, transaction hash included. Keep it. It is your proof of payment, and the only thing that ties your request to an on-chain fact.

Field by field: anatomy of a payment.

What x402 does not define#

Knowing the edges saves you looking for features that are not there.

• No refunds, no disputes, no escrow. Settlement is final. If a server takes payment and returns nothing, that is a reputation problem, not a protocol one — which is precisely the gap ERC-8004 and the settlement record fill.
• No identity. The protocol knows a payer address, not who it belongs to. Identity is a separate layer.
• No price discovery. A server quotes; it does not negotiate. Finding out what a fair price is means looking at what others have paid.
• No subscriptions or metering. Each call is priced and paid on its own. Recurring access is something you build on top — the API key that the test drive mints is exactly that pattern.
• No chain or asset mandate. In practice today: USDC, on Base. See schemes and networks.

Why it suits agents specifically#

An agent's problem is not that payments are expensive. It is that every existing payment rail assumes a legal person who can be onboarded, who has a billing relationship, and who will notice next month if something was wrong. An agent has none of that, needs to transact in seconds, and may never call the same service twice.

x402 gives it a rail where the credential is the signature, the relationship is one request long, and the settlement is verifiable by anyone. That last property is what makes an index like Roundhouse possible at all — and, in turn, what gives an agent something to check before it pays a stranger.

Next steps#

• Anatomy of a payment — every field, in order
• Schemes and networks — what is actually supported
• Facilitators — what they do and how to pick one
• Your first x402 payment — do it for a cent