What is in an accepts entry?#
A 402 response is self-describing. It does not point at a pricing page; it contains the price, in a form a program can act on without being told anything in advance.
| Field | Type | What it means |
|---|---|---|
scheme | string | How payment is computed. exact is the common one |
network | string | Which chain, by its canonical name or CAIP-2 id |
maxAmountRequired | string | The price, in the asset's smallest unit |
asset | string | The token contract address |
payTo | string | The address that receives the funds |
resource | string | The URL this offer is for |
description | string | Human-readable, optional |
maxTimeoutSeconds | number | How long the server will hold the offer |
extra | object | Scheme-specific data, including the EIP-712 domain |
A server may list several entries. Listing two chains, or the same chain with two assets, lets a buyer pick whichever it can actually pay with rather than failing outright.
Which field causes the most bugs?#
maxAmountRequired, by a wide margin, and the bug is always the same.
The amount is in the asset's smallest unit, not in dollars. USDC has six decimals, so one cent is "10000" and one dollar is "1000000". A service that publishes a price of 0.01 in a catalogue and an amount of 10000 in its 402 is consistent. A system that reads the catalogue figure as if it were smallest units, or the 402 figure as if it were dollars, is wrong by a factor of a million.
Warning
This error is silent. A price read as dollars when it was smallest units produces a plausible-looking number, not a crash, and it propagates into every aggregate downstream. If you are ingesting prices from more than one source, normalise at the boundary and record which convention each source used.
The second most common is payTo. A catalogue entry and a live 402 can disagree, because a catalogue records what a publisher registered and a 402 records what the server will accept right now. The live 402 is the authority. Some well-known catalogues carry no payTo at all.
What does scheme mean?#
The scheme decides how the amount is determined and what the client signs.
exactis a fixed price, known before the work is done. The client signs for exactly that amount. This covers almost everything: a search query, a page of data, one inference call.uptois a ceiling, for work whose cost is only known afterwards. The client authorises a maximum and the server settles for the actual amount. This suits token-metered inference, where the price depends on output length.
Exact and upto compared goes into when each one is appropriate and what each one costs you in buyer trust.
How does a client choose between entries?#
The protocol does not say, which is deliberate and occasionally annoying. In practice a client filters then ranks.
Filtering is about capability: can I pay on this network, do I hold this asset, is the amount within my budget, is the scheme one I implement. Anything that fails these is not an option regardless of price.
Ranking is about preference. Most clients prefer the chain where their balance already sits, because bridging to save a tenth of a cent is never worth it. After that, the cheapest entry wins.
A seller should order the array by its own preference, since some clients take the first entry they can satisfy rather than evaluating all of them.
What does the server do with the payment it gets back?#
It checks that the authorisation matches the entry it advertised. All of it: the amount, the asset, the network, the payee and the resource. A payment that is valid in isolation but was signed for a different resource is not payment for this one, and a server that does not check the binding can be made to serve expensive endpoints for the price of cheap ones.
Then it calls a facilitator to verify, serves the resource, and settles. The order of those last two is a real decision with a real trade-off, covered in the anatomy of a payment.
Frequently asked questions#
Can the price change between the 402 and the retry?#
It should not within maxTimeoutSeconds. That field exists so a client knows how long it has to sign and resend. A server that reprices inside its own stated window will fail payments that were correct when they were signed.
What goes in extra?#
Scheme and chain specific data the client needs to build a valid signature. On EVM chains this is usually the EIP-712 domain: the contract name and version used in the domain separator. Getting it wrong produces a signature that verifies nowhere, and the domain name is not always the token's display name.
Must resource match the request URL exactly?#
Match it to the degree your binding requires. Query strings are the awkward case: if the price depends on parameters then the resource identity has to include them, and if it does not then it should not, or every distinct query becomes a separate unpayable resource.
Can I advertise free and paid paths on one API?#
Yes, and most do. Return 402 only on the priced paths. Keeping a free discovery path, a health check and a schema endpoint open is good practice, because a buyer that cannot read your interface without paying will usually not pay.
Is there a registry of networks I can use in the network field?#
The protocol accepts canonical chain names and CAIP-2 identifiers. Using CAIP-2 is safer for anything machine-read, because names are ambiguous across testnets and forks in a way that eip155:8453 is not.
Where to check this yourself#
Read a live 402 rather than a schema. The services directory lists endpoints that return real terms, and the x402 overview documents the response shape as Roundhouse's own facilitator implements it. For the price side specifically, /services shows the listed price distribution across the catalogue, which is a quick sanity check on whether a figure you are reading is in dollars or in smallest units.