What x402 is
what HTTP 402 actually does
x402 is a convention for charging for one HTTP request. Instead of turning an unpaid request away, the server answers 402 Payment Required with a machine-readable price. The client pays exactly that amount and sends the same request again. There is no account, no API key, and no invoice — the payment is the credential, and it is good for that one request.
01GET /report HTTP/20203HTTP/2 40204PAYMENT-REQUIRED: <base64 JSON: how much, in what, to whom>0506GET /report HTTP/207PAYMENT-SIGNATURE: <base64 JSON: a signature for exactly that>0809HTTP/2 20010PAYMENT-RESPONSE: <base64 JSON: the settlement transaction>The problem it solves
Selling something small over HTTP has always cost more than the thing is worth. Consider an API call worth two tenths of a cent. To sell it you need a sign-up form, an email confirmation, an API key the buyer has to store and rotate, and a card on file. Card processing has a floor: standard published US card pricing is a percentage plus a flat per-transaction fee of about thirty cents — Stripe lists 2.9% + $0.30 per successful charge — so charging $0.002 is not merely unprofitable, it is arithmetically impossible. The flat component is the part that matters; it does not shrink with the price.
The industry works around this by rounding up. Free tiers, monthly subscriptions, prepaid credit bundles, enterprise contracts. All of them move the transaction away from the request and toward a relationship. The consequence is quiet but large: anything that cannot justify a monthly subscription does not get sold at all. A single lookup, one page of an archive, one frame of a rendering job — the machinery to charge for it costs more than the thing.
Software that makes requests on its own behalf makes this sharper. A program that needs one page each from forty different services cannot fill in forty sign-up forms, hold forty API keys, and put a card on file forty times. Every step in that flow assumes a human at a form, with an identity, a billing address, and the patience to wait for an approval email.
The mechanism, in one paragraph
A client requests a resource. The server answers 402 with a PAYMENT-REQUIRED header holding base64-encoded JSON: a list of acceptable payments, each naming a scheme, a chain, a token, an amount in that token's smallest unit, and the address to pay. The client picks one, signs an authorization to transfer exactly that amount to exactly that address, base64-encodes the payload into a PAYMENT-SIGNATURE header, and repeats the identical request. The server hands the payload to a facilitator, which verifies the signature, the balance and the amount, and answers valid or not. Only on valid does the server do the work; only if the work succeeds does the facilitator submit the transfer on chain. The server then returns 200 with a PAYMENT-RESPONSE header naming the settlement transaction. Money moves after delivery, not before.
The handshake, step by step
- client → server
Ask, without paying
An ordinary request. No key, no account, no prior relationship.
- server → client
Get a price instead of a refusal
402, with the quote in a header as base64 JSON. Each entry in accepts[] is one way to pay: a scheme, a chain, a token, an amount in atomic units, and the address that receives it.
- client → server
Sign the exact amount and ask again
The client copies the chosen entry verbatim, signs an authorization to move exactly that amount to exactly that address, and repeats the identical request with the payload attached. On EVM this is an EIP-3009 signature: a signed message, not a submitted transaction, so the payer spends no gas.
- server ↔ facilitator → client
Verify, deliver, then settle
The server asks a facilitator whether the signed authorization is good. Only if it is does the server do the work. Only if the work succeeds does the facilitator put the transfer on chain. The transaction hash comes back in a response header.
That is the version 2 flow. Version 1 puts the quote in the response body instead of a header and uses X-PAYMENT where version 2 uses PAYMENT-SIGNATURE. Both are in active use; see the FAQ.
Why HTTP 402 sat unused for nearly thirty years
The status code is not new. RFC 2068 defined 402 Payment Required in HTTP/1.1 in January 1997 and marked it "reserved for future use". RFC 9110, the current HTTP semantics specification, still says the same thing. Twenty-five years of revisions left the sentence untouched.
Two specific gaps kept it that way, and both were closed at once.
There was no challenge format. Compare it with 401 Unauthorized, which is useful precisely because WWW-Authenticate tells the client exactly what to do next: which scheme, which realm, which parameters. 402 had no equivalent. A server could return the number and had no standard way to say how much, in what unit, to whom, or by when. A client receiving one could do nothing with it except show a human an error.
There was no payment instrument a program could use unattended. Even with a perfect challenge format, paying meant a card, and a card means a human, an account, a billing address, a settlement delay measured in days, and a minimum viable charge far above the price of a single request.
So the code became a status with no client behaviour behind it. Browsers do nothing special with it. Where it is used at all, it usually means something narrower — several APIs, Stripe's among them, return 402 to say that a card already on file was declined. A perfectly good status code sat there because nothing could act on it.
What changed
None of it was the status code. Three things arrived at roughly the same time.
- A settlement layer where a fraction of a cent is a legal amount. Dollar-denominated stablecoins on chains where a transfer costs well under a cent and confirms in seconds. That moves the floor from "about thirty cents, per transaction" to below the median price actually being quoted through x402 today — see the numbers.
- A signature that authorizes a pull instead of pushing a payment.EIP-3009's
transferWithAuthorizationlets a payer sign an off-chain message that someone else submits and pays gas for. The gas is the least interesting part. What matters is the ordering it makes possible: the server can check that a payment is good before doing the work, and submit it only after the work succeeded. A request that fails costs the payer nothing and leaves the authorization unspent and reusable. - Someone wrote the format down. Three headers, one JSON shape for the quote, and a three-endpoint facilitator API (
/verify,/settle,/supported). That is the difference between a protocol and one company's checkout page: any client can act on a 402 from any server it has never seen before.
The demand side arrived at the same time. Programs that browse, research and buy on their own behalf are exactly the customer that could never fill in the sign-up form.
Who is involved
- Payera client, a script, an agent
- Reads the quote, decides whether the price is worth it, signs an authorization for that exact amount. Holds its own keys and its own funds.
- Resource serverthe thing being sold
- States a price, checks the payment before doing work, does the work, then asks for settlement. Never holds the buyer's funds and never needs the buyer's identity.
- Facilitatora third-party service
- Answers two questions over HTTP: is this signed authorization valid, and please submit it on chain. It exists so a resource server does not have to run chain infrastructure to take a payment.
The facilitator is the only new kind of participant, and it is the one worth understanding before you deploy anything. It sees the payment payload and decides whether to submit it. It does not need to receive the money —payTo in the quote is the seller's own address — but it is a dependency, and which one you use is a real choice. The ecosystem map lists the ones we could verify.
What x402 is not
- Not a blockchain or a token. It is a header format and a small HTTP API. Which chain settles a given payment is chosen per offer, by the seller, and appears as a field in the quote.
- Not a new status code. 402 has been in HTTP since 1997. x402 supplies the challenge format that was missing.
- Not custodial by design. The seller's own address is in the quote. A facilitator that only verifies and submits never holds the money. Whether a particular facilitator does more than that is a question worth asking it directly.
- Not a subscription, metering or billing system. One request, one price, settled once. Anything resembling an account balance is built on top, not inside.
- Not reversible. There are no chargebacks. That removes fraud loss for the seller and removes recourse for the buyer. It is a real trade, not a free win.
What to be skeptical about
Where to go next
- The numbers — what is listed, what it costs, and what has actually been settled on chain, with every source named.
- The ecosystem map — who runs what, what we verified about each, and what we could not.
- The FAQ — twenty questions people actually ask, including the uncomfortable ones.
- The specification — the source of truth. Everything here is a reading of it.