When a paid call is charged
Before an agent spends, it should know what happens when a call goes wrong. This is the contract every paid Tanod route and MCP tool follows. The price itself is in each route's 402 response, in /openapi.json and on /pricing/.
Charged: an answer
A payment is settled only after the call returns HTTP 200, which is an answer. That includes answers that say something was not found when the route treats that as an answer: for example, an unknown or still-pending transaction hash on the chain routes returns 200 with status: not_found, and is charged.
Not charged: everything else
- Our side or upstream failed: any 5xx, or an error code such as
busy,timeout,rpc_unavailableorresponse_too_large. The payment is not settled, and a free daily use spent on the call is given back. - Rate limited (429), or our connection to an upstream failed: not settled.
- Bad input: a 4xx such as 422 (invalid or blocked input), 413 (too large) or 415 (unsupported format) is never charged, and a free use spent on it is given back too.
Retries and double charges
A call that was not charged can be retried at once; the payment you signed for it never settled, so no money moved. Each signed x402 payment can settle at most once, so resending the same signed payment cannot charge you twice. A 402 that says your input would be refused (it names the problem) means: fix the input before paying, because a paid retry with the same input gets the 4xx and is not used.
Receipts
A settled call returns the x402 receipt in the PAYMENT-RESPONSE (and X-PAYMENT-RESPONSE) header: the network, the payer and the on-chain transaction hash. That hash is the evidence for any question about a charge.
Test a payment for USD 0.001 first
To check that your client pays and that we deliver after payment before you spend more, call POST /v1/x402/pay-test with an empty body ({}). It costs USD 0.001 and returns a signed receipt with the payer, network, amount, facilitator, transaction hash and verify and settle times. The signing key is at /.well-known/tanod-receipt-key, and POST /v1/x402/pay-test/verify checks a receipt for free. A payment that fails is never settled, and its 402 names the reason (wrong network, amount below the price, expired authorisation, wrong payTo or bad signature) where it can be told.
Questions about a charge
Email [email protected] with the route or tool, the time in UTC and the transaction hash. Results are automated and heuristic; see the terms.