How payment works
Every TollNode node is one HTTP POST with one price. Agents pay per call with x402, an open standard built on HTTP 402 Payment Required, in USDC on Base. There are no accounts or API keys.
The flow
- 1. Send a POST with a JSON body to the node URL. Without payment you get HTTP 402 with the exact price in USDC on Base (PAYMENT-REQUIRED header, plus a JSON body for older x402 clients). Where an option such as resolution or quality changes the price, the 402 quotes the price for the option in your body; omit it and you get (and pay for) the default.
- 2. Sign the payment with any x402 client and retry with the PAYMENT-SIGNATURE header (legacy X-PAYMENT also works).
- 3. TollNode checks the payment, runs the node, and settles only if the result is usable. Failed, empty or timed-out calls are never charged, so there is nothing to refund.
- 4. No account, no API key, no subscription.
see a 402 quote
curl -i -X POST https://tollnode.com/api/v1/nodes/vin-decode \
-H 'content-type: application/json' \
-d '{"vin":"1HGCM82633A004352"}'Why a failed call costs nothing
An x402 payment is a signed authorization, not a transfer. TollNode verifies the signature, runs the node, and only submits the payment when the node returns a usable result. If the node errors, times out or returns nothing, the authorization is simply never used. Your USDC never moves, so there is nothing to refund.
Status codes
- 200
- Success. The payment settled; the PAYMENT-RESPONSE header carries the transaction.
- 400
- The body failed the node's input schema. Not charged.
- 402
- Payment required, or the payment could not be verified. Not charged.
- 403
- This wallet is blocked after an earlier unpaid call. Not charged.
- 404 / 503
- Unknown or paused node. Not charged.
- 409
- That payment was already used. Not charged again.
- 502 / 504
- The node failed, returned nothing, or timed out. Not charged.
Machine files
- /llms.txtShort index for LLMs: every node, its price and endpoint.
- /llms-full.txtFull contract with input schemas and example responses.
- /openapi.jsonOpenAPI 3.1 with x402 payment info on every paid operation.
- /.well-known/x402x402 manifest that indexers such as x402scan read.
- /.well-known/mcp.jsonEvery node described as an MCP tool.
Wallets
Any x402 client works. The quickest path for Claude Code, Cursor and Codex is AgentCash. See Agents & MCP.
shell
npx agentcash add https://tollnode.com