What x402 is: HTTP 402 as a working payment exchange

x402 is an open standard for paying for a single HTTP request. A server answers an unpaid call with the price, the buyer’s wallet signs an authorisation, and a facilitator settles it on chain. Here is the whole exchange, including where it fails.

The status code nobody used

RFC 7231 gives the 402 status code one sentence: “The 402 (Payment Required) status code is reserved for future use.” That is the whole of its specification, and that is where it has stayed. The code says that payment is required and nothing else: no field for a price, no format for an authorisation, no step at which a payment is submitted, no instruction to a client about what to put in a retry. A server that wanted to charge for a request had to invent the entire exchange, and a client had no way to generalise across two servers that had invented it differently.

The gap was closed with something else. An API key with a monthly invoice behind it. A subscription. A credit balance topped up in advance. Each of these works, and each moves the moment of payment away from the moment of use: the key is a promise that this month’s calls will be billed next month, the subscription is a bet on volume, the balance is a deposit against work that has not happened. All three need an account, an agreement and a bill at the end.

None of that was an oversight. Charging per call needs a settlement rail able to carry the price of one call, and the rail was the hard part; the status code was never the obstacle. x402’s contribution is not that it discovered 402. It is that it defines what goes into the response, what the client sends back, who may submit the payment, and what a merchant should do when the submission is uncertain.

What changes when a machine can pay per call is the unit of billing. It becomes the request: not the month, not the tier, not the seat. A price can be attached to one operation — this query, this completion, this transaction build — and the caller can decide at the moment of the call whether the amount is worth paying. The buyer needs no relationship with the seller beyond a wallet that can sign, and the seller needs no billing system, because the payment arrives with the request that consumes it.

The cost of that is arithmetic: a paid call is not one request but at least two. The first carries no payment and is answered with a price; the second carries the payment and is answered with the work. Everything interesting about x402 lives in the gap between them.

The two-round handshake

The exchange has two rounds. The first is the request the client wanted to make, answered with a price. The second is the same request carrying a payment, answered with the work.

1. The client asks for the resource. An ordinary request to a paid route, with no payment header.
2. The server replies 402 with a price list. The PAYMENT-REQUIRED header carries a base64-encoded PaymentRequired object: the protocol version, a description of the resource, and accepts, the list of payment requirements the server will honour.
3. The client selects one requirement and builds a payload. One entry from accepts — one scheme, one network, one asset — and an authorisation signed for that entry’s amount and payee.
4. The client retries the same request with PAYMENT-SIGNATURE. The body is unchanged; the payment travels in a header, as base64-encoded JSON.
5. The server verifies. Locally, against the requirements it published, or by posting the payload and requirements to a facilitator’s /verify endpoint.
6. The verifier answers. Validity, the reason for invalidity if there is one, and the payer’s address.
7. The server does the work. Only after a positive verification.
8. The server settles. It submits the payment itself, or posts payload and requirements to the facilitator’s /settle endpoint.
9. The facilitator submits and waits. It puts the transaction on chain and waits for confirmation within a bounded time.
10. The server returns the work with the receipt. The response carries PAYMENT-RESPONSE, base64-encoded settlement details: the success flag, the transaction hash, the network and the payer.

Table 1 sets out the same sequence by role.

Table 1. The handshake, step by step. Source: docs.x402.org, facilitator and HTTP 402 pages, 30 October 2026.

Three details in that sequence matter more than the order.

The payment is in headers, not the body. PAYMENT-REQUIRED, PAYMENT-SIGNATURE and PAYMENT-RESPONSE are each a base64-encoded JSON object. The body of your request and the body of the answer are untouched, which is why an x402 payment can wrap an existing endpoint without changing its schema.

Verification and settlement are separate steps with the work between them. The server decides to trust an authorisation before anyone has executed it, then does the work, then settles. The protocol names this ordering: the default flow verifies before the handler runs and settles after it, and a seller may opt into an upfront flow that settles before serving. That choice is the merchant’s risk decision, and section 8 is what happens when the last step does not resolve cleanly.

The tenth step happens either way. PAYMENT-RESPONSE is present on success and on failure. On failure the status is 402 again, with the settlement error in the header. There is no case in which the client is left to infer the payment outcome from a status code alone.

What accepts contains

The 402’s header decodes to a PaymentRequired object: a protocol version, an optional error string, a description of the resource (its URL, MIME type, service name and tags), and accepts, an array of payment requirements. One array entry is one way to pay. A server taking USDC on seven chains and EURC on one lists eight entries for a fixed price; if it also offers metered pricing it lists a second set. Table 2 lists the fields of one entry, beside the values a live challenge returned.

Table 2. Fields in a payment requirement, with the values a live challenge returned. Source: x402 v2 specification §5.1.2; deepseek.x402.press/v1/chat/completions, 402 decoded on 30 October 2026.

amount is the field that most often goes wrong. It is an integer in the token’s smallest unit, not a decimal string and not dollars. USDC has six decimals, so 10000 is $0.01 and 7000 is $0.007. A client that reads 7000 as $7,000 is wrong by a factor of a million, and nothing in the response will warn it.

The amount is also uninterpretable on its own. The same completion was quoted 2000 on Avalanche and 3000000 on Ethereum in the challenge we decoded; only the pairing of amount with network and asset tells you that those are $0.002 and $3.00. Two consequences follow. Read the triple, never the number. And expect the same operation to be quoted at wildly different amounts on different chains, because what is being priced is partly the cost of settling there.

maxTimeoutSeconds bounds the payment’s completion: 300 seconds in every challenge we decoded. extra carries what a client needs to build the transfer, and its contents differ by scheme: the fixed-price entries in our challenge carried the token’s EIP-712 domain, while the metered entries added assetTransferMethod: permit2 and the facilitator’s address.

Schemes

The scheme is the semantics of the payment, and the list is short.

exact is a fixed price. The buyer authorises exactly the amount advertised — not a maximum, not a range. The requirement’s amount is the price and the signed value must equal it, which is why the specification defines a specific errorReason for a value that does not match. The buyer knows the cost before signing, and the seller knows the amount that will arrive. This is the scheme to use when the work has a price per call.

upto is a ceiling, not a price. The buyer signs once for the maximum; the server measures the work and settles an amount at or below that maximum. The seller chooses the final figure, and the buyer has agreed in advance that it may be anything up to the ceiling. That is the trade: with exact the buyer knows the price, and with upto the buyer knows only the bound and must trust the seller’s measurement.

Read the ceiling, not the wording. On our own routes the two numbers in a challenge are not the same: the DeepSeek chat route quoted 7000 fixed and 9550 metered on Base, a ceiling 36 per cent above the fixed price. On the Qwen route the ceiling equalled the fixed price exactly (8750 for both), so the metered entry bought no headroom at all. We also changed max_tokens from 16 to 1,000 and the ceiling did not move on either route. The practical rule is to read the ceiling out of the challenge you actually received, and to treat it as the maximum you have authorised for that call, whatever your token budget was meant to imply.

batch-settlement is for volume. The buyer deposits into an on-chain escrow once, then signs a cumulative off-chain voucher with each request; the seller verifies vouchers without waiting for a transfer and redeems them on chain in batches. It is the only one of the three in which value sits somewhere other than the buyer’s wallet between the request and the redemption — in an escrow contract, not with the facilitator. It is worth the machinery only where settling each call individually would dominate the price of the call. Our facilitator does not offer it: its supported list registers exact and upto only.

Table 3 sets the three side by side against what the buyer actually authorises.

Table 3. The three schemes against the buyer’s authorisation. Source: docs.x402.org scheme pages, 30 October 2026.

The facilitator

A facilitator is a service that verifies payment payloads and settles them on chain. It is optional and recommended — a combination that is deliberate, because a resource server can verify and submit by itself. A client cannot tell the difference: it sees the same three headers either way.

The service has three jobs. It verifies that a payload meets the requirements the server declared. It settles an accepted payment by submitting it and waiting for confirmation. And it returns both results to the server, which decides whether to serve the request. It does not hold funds and is not a custodian: it holds no balance of anyone’s and submits transactions from signed payloads that clients created.

What the server keeps is everything that is not mechanics: the price it quotes, the work it performs, the decision to serve, and the record of what it settled. What it gives up is chain connectivity and verification logic, which is the whole reason to use a facilitator at all. Table 4 sets out the four ways to obtain one.

Table 4. The four deployment paths. Source: docs.x402.org, facilitator page, 30 October 2026.

The warning attached to the first row is not a formality. The public facilitator is intended for development and testnet workflows, and the documentation is explicit that it should not be assumed to be the default path for production mainnet routes. A merchant who leaves it in place has chosen a shared, non-production dependency for money movement.

A facilitator deployed behind a platform deadline — a serverless function, a gateway with a request timeout — has a specific configuration duty: bound its receipt wait below that deadline. Default receipt waits are generous. The TypeScript signer waits 180,000 ms for a confirmation and the Python signer 120 seconds; the resource server’s HTTP client gives the facilitator 90 seconds per request by default. Each is a reasonable default, and each can outlast the deadline of the platform a facilitator sits behind, which is the problem section 8 describes.

When settlement goes wrong

The normal case is silent. A payment is verified, submitted, confirmed, and the settlement response carries a transaction hash nobody looks at. Five other outcomes deserve attention, and none of them is an edge case: a payload rejected before broadcast, a transaction broadcast but unconfirmed, a submission that arrives twice, a facilitator killed mid-wait, and a call that times out with the outcome unknown.

Rejected before broadcast. Verification fails for reasons that never reach a chain: insufficient funds, a signature that does not match the requirement, a value that is not the amount asked for, an authorisation whose window has closed before it was presented. The server returns a 402 carrying an errorReason, and no payment exists. These are the cheapest failures and the only ones the client can fix on its own — the payload is rebuilt from a fresh challenge and sent again.

Broadcast but unconfirmed. When a transaction has gone out but its confirmation cannot be established — an RPC error, a timeout waiting for the receipt — the facilitator returns settlement_pending. This is explicitly a non-terminal result: the transaction may still confirm. A settlement response carrying that reason must include a non-empty transaction hash and the network, so the caller can reconcile on chain instead of guessing.

The resource server then retries settlement exactly once. On the retry, the facilitator checks a PendingSettlementStore for the broadcast hash and, finding it, reconciles against the transaction already in flight rather than verifying and submitting a second one. That is what prevents a double spend from what looks like a failed settlement.

The store is an interface, not a fixed implementation. The default is in-memory, and an in-memory default only works when the retry lands on the same process — a detail that matters the moment a facilitator runs as several replicas with no session affinity, where the retry can arrive anywhere. A deployment of that shape needs a shared, network-backed store.

Unknown because the process died. A facilitator that waits for a receipt beyond its own platform deadline is killed mid-wait, and the caller receives a 5xx with no transaction hash at all. That is worse than settlement_pending, because there is nothing to reconcile against. Bounding the receipt wait below the deadline is the mitigation, and it is the operator’s job, not the protocol’s.

Submitted twice on Solana. A signed payment can reach /settle more than once before the first submission confirms. Solana’s RPC returns success for a duplicate, because the network deduplicates at consensus, so a facilitator can report a successful settlement for each call and a malicious client can obtain several resources for one payment. The SVM mechanism packages ship a SettlementCache that rejects duplicate attempts for the same payload, evicting entries after 120 seconds — roughly twice a Solana blockhash lifetime. A merchant that settles Solana payments directly, without a facilitator, must implement equivalent detection.

Indeterminate because the call timed out. A timeout during settle does not mean the payment failed. It means the resource server did not hear back, and the facilitator may have settled. This is the one failure that punishes the wrong reflex: authorising a second payment to cover a first that may already have succeeded pays twice. The documented discipline is to treat the outcome as unknown, reconcile with the transaction hash and network when you have them, and only consider a new payment once the original is conclusively unsuccessful.

Table 5 collects these failures, what each looks like from the client’s side, and what each calls for.

Table 5. Failure modes and the correct response. Source: docs.x402.org, facilitator and client/server pages; x402 v2 specification §9, 30 October 2026.

Two habits make the difference between a working integration and an expensive one. Decode PAYMENT-RESPONSE on success and on failure; the header is the only place the payment outcome is stated. And branch on errorReason codes rather than message text, because the messages are free-form and change between facilitators and releases while the codes are the contract.

What the buyer’s wallet authorises

The signed payload is where the trust boundary actually sits, so it is worth reading in full. PAYMENT-SIGNATURE decodes to a payment payload carrying the requirement the client accepted and a payload object with two parts: a signature, and an authorisation.

The authorisation names the payer’s address, the recipient’s address, the value in atomic units, a start time, an expiry time and a 32-byte nonce. The signature is an EIP-712 signature over those fields. Read as a sentence, it says: transfer this exact value, from this address, to that address, once, between these two moments.

Everything else follows from that sentence.

The buyer’s key signs, and nothing moves until it does. An unpaid call returns a price. No funds are committed, no allowance is granted, no authority is delegated by asking.

The server never holds the buyer’s funds. There is no balance at the server to be lost, borrowed against or frozen. The asset stays in the buyer’s wallet until settlement executes, and what the server receives is a signed instruction, not money.

The facilitator never custodies it either. Its role is to submit a transaction the buyer has already signed. It cannot widen the value or redirect the recipient, because both are inside the signature; a facilitator that tried would fail verification and fail again at the token contract. It moves the payment without ever owning it.

What remains trusted is worth naming precisely. The chain must execute and confirm. The token contract must behave as specified. The facilitator must submit what it verified and report the result truthfully, which you can check against the chain. The seller must do the work it priced. x402 does not remove those dependencies; it moves them, and it moves the ones a buyer cares about most — who holds the money, and who decides to spend it — to the holder of the key.

One scheme widens the boundary, and it is worth being blunt about it. Under upto the signed value is the ceiling, and the amount actually settled is chosen by the seller somewhere at or below it. The signature therefore grants discretion, not a price. That is an acceptable trade for work whose size is unknown in advance, and it is a poor one for anything whose price is knowable, where exact gives the buyer the number before the key is touched.

What x402 does not solve

Refunds and disputes. None of the three schemes above reverses a settled transfer. If the work fails after settlement, the protocol offers neither side a mechanism to unwind it: the seller would have to send funds back as a separate transfer, at its own discretion, and the buyer would have to trust that it will. There is no chargeback, no adjudicator, and no escrow in the request-to-settlement path of exact or upto. Choose counterparties accordingly.

Privacy. The payment is a public transaction. The payer’s address, the recipient, the amount and the time are visible to anyone who can read the chain, permanently. A stable payTo links every call a buyer makes to the same counterparty, and a wallet used for anything else links those activities together. If a buying pattern is sensitive — which vendor, how often, at what price — x402 does not hide it.

Price discovery. A 402 tells you what this seller charges for this call. It does not tell you whether that is a fair price, what the same work costs elsewhere, or whether a cheaper chain would do. There is no order book, no quote comparison and no negotiation inside the protocol: the server names a number and the client takes it or leaves. Comparing sellers is the job of a catalogue and of the reader of one.

Service quality. Payment and delivery are one exchange and nothing more. No service-level agreement is carried by the protocol, no warranty, no reputation, no history. A seller that returns a worse answer than its description promised has been paid, and the protocol has no view on it.

Custody risk in the asset. You are paying in a token on a chain, and both are outside the protocol. The token contract, whatever backs the token, the liveness of the chain and the route by which you obtained the asset are all risks that survive a perfectly executed x402 payment. Settlement in the protocol’s terms says nothing about whether the asset will still be worth what you paid.

Retries, which are yours to get right. A paid call can fail after the buyer has signed, and an HTTP timeout proves nothing: the server may have received and settled the payment that timed out. After PAYMENT-SIGNATURE has been sent, the outcome is unknown until it is reconciled, and a second authorisation is not the safe default. This is the part of x402 that costs money when it is done carelessly, and it is entirely the client’s responsibility.

Where our catalogue sits

Our own catalogue prices every operation on seven chains, and the settlement chain is often the larger variable of the two. Nineteen services and ninety-two paid operations, each priced separately on all seven. Table 6 holds two operations constant and varies only the chain.

Table 6. Two operations, same work on each chain, priced per settlement chain. Source: https://x402.press/catalog.json, fetched 30 October 2026.

The cheapest call in the catalogue is $0.00175 on Avalanche and the dearest is $3.75 on Ethereum mainnet, but those two figures are different operations. The more useful comparison holds the work constant: for the same call, Base costs 3.5 times the Avalanche price and Ethereum 1,500 times it, at 428 times the Base price. The three chat providers in the catalogue quote identically on each chain at entry tier, so on those routes the chain moves the price and the model does not.

Payment runs through our own facilitator at https://facilitator.x402.press, whose supported list is published at /supported. It registers exact on all seven chains and upto on six — Avalanche carries fixed price only. Every challenge we decoded offered both schemes where the network supported them, and each carried maxTimeoutSeconds of 300.

One caution when reading any catalogue, ours included: the listed price is a listing, and the 402 is the quote. On a size-dependent route the two can differ — the DeepSeek chat route quoted 7000 atomic units ($0.007) for a one-word prompt against a listed $0.00875. Read the challenge you receive before you sign for it.

Related

• The service reviews on this site: DeepSeek, Qwen, HyperFusion, SpiralStake, and Wolfram Alpha (in build).
• The catalogue, with every operation priced per chain: https://x402.press/catalog.json
• Facilitator support, per network and scheme: https://facilitator.x402.press/supported
• Protocol documentation: https://docs.x402.org

Method note

Everything in this article is drawn from three sources, all read on 30 October 2026: the protocol documentation at docs.x402.org (HTTP 402, client/server, facilitator, schemes and their pages); the v2 specification and its HTTP transport document in the x402-foundation/x402 repository, which is where the field names and error codes come from; and our own measurements — catalog.json, the facilitator’s /supported list, and 402 challenges decoded from deepseek.x402.press and qwen.x402.press.

The challenge behind Table 2 came from POST /v1/chat/completions with a one-line prompt, returned 15 accepted payments — eight exact (seven chains, Base twice for USDC and EURC) and seven upto — in x402Version 2. The metered ceiling was read at max_tokens 16 and again at 1,000 and did not change. Table 6 prices are the catalogue’s own, not the live challenges; the two agree on the Qwen route and differ on the DeepSeek route by the amount quoted above.

We have measured no latency, no throughput and no cost per settlement, and no figure of that kind appears here. Where the documentation states a default, we quote the default rather than a measurement of it.

Filed under Foundations · Tags: x402, protocol, payments, settlement

All seven reviews: the services reviewed

Running it: the float, the ceilings and the record