The ordering inside a 402 already carries the answer, but an agent reading accepts[0] cannot see what the order was based on. This is that reasoning in the open: median headroom, how many settlements it is over, and whether the choice was a choice at all.
Headroom is the seconds an order had left before its deadline when it landed. unobserved: true means no rail had enough observations and the first accepted rail was taken.
Path Parameters
Response Body
application/json
application/json
curl -X GET "https://example.com/x402/resources/string/rail"{ "chain": "string", "reason": "string", "medianHeadroomSeconds": 0, "samples": 0, "failures": 0, "unobserved": true}Quote one invoice or link — or settle it
One endpoint, two answers, decided by the `PAYMENT-SIGNATURE` header. Without one: a `402` whose `PAYMENT-REQUIRED` header quotes the **full** outstanding amount — an authorization for less than what is owed is refused, and the remedy is a new `402` for the whole balance. With one: verify, settle, and answer `200` naming the payment intent the settlement created. A payable's price is held in a quote row for a short window together with the exact rails it offered, which is what the `409` and `410` are about.
The MCP server — free discovery, paid tools/call
An MCP server over the same rail, speaking JSON-RPC 2.0. `initialize` and `tools/list` are free; `tools/call` costs one authorization and answers `402` until it carries one. Discovery is free and answers are paid by design: an agent cannot decide a price is worth paying for a tool it has not been allowed to read the description of. Two tools. `rail_stats` reports samples, median headroom, and the worst and best observed per rail; `choose_rail` ranks them and returns the one to pay on. Three refusals never charge — arguments the tool will not accept (refused **before** the gate, since a response cannot be un-served), no settlements observed at all, and a tool that does not exist, which is a tool error rather than a JSON-RPC error so a model can tell 'the server said no' from 'the call never arrived'. Send the **same body** in both the request that receives the `402` and the retry carrying the signature; a different one is a different purchase settled against the first one's authorization. A JSON-RPC notification (no `id`) is answered `202` with no body.