What is x402? A beginner's guide to x402

Way 1 · x402, no sign-up

Your agent pays for itself

The whole idea in four pictures.

1Needs something
Mid-task, your agent needs an image, a search or a voice.
2Finds it on TollNode
It picks the right tool. The price is shown up front.
3Pays a few cents
Its wallet pays for that one use. No sign-up.
4Gets the result
The result comes straight back. If it fails, it's free.

try it in Claude Code, Cursor or Codex

npx agentcash add https://tollnode.com

Way 2 · account + API key

Or prepay and use a key

For apps, servers and teams that would rather not run a wallet.

1Add funds
Make a free account and top up $5 to $50.
2Get an API key
One click on your account page.
3Use any tool
Each use comes off your balance. Same prices.

Create a free account

What's on offer

What your agent can do with TollNode

Every skill below works both ways. Filter by what you need, then open a step-by-step guide.

The fair part

You only pay when it works

Call works

You get the result, then the payment settles. That's the only time money moves.

Call fails · $0

Error, empty result or timeout: we never submit the payment, so nothing leaves your wallet. Nothing to refund.

Numbers

x402 on TollNode at a glance

$0.003
cheapest call
USDC
on Base, a dollar stablecoin
$0 gas
for the buyer
~2 s
to settle on chain
60
models and tools
0
sign-ups needed

Under the hood

What happens on the wire

Infographic of the four x402 steps: 1 request, the agent calls the API; 2 price, the server replies 402 with the price; 3 sign, the wallet signs a USDC payment; 4 result, the server runs the call, then collects

1. Request
A normal POST. No price known yet.
2. 402 + price
The PAYMENT-REQUIRED header says how much, in which token, to which address.
3. Signed retry
Same request plus PAYMENT-SIGNATURE. Signing is permission; nothing has moved.
4. Result + receipt
Work done, then settled. PAYMENT-RESPONSE holds the transaction hash.

The cast

Four parties, one request

Buyer
Your agent or app, with a wallet holding USDC.
Seller
The API (TollNode). Quotes the price, does the work.
Facilitator
Checks the signature, submits the transfer, pays the gas.
Base
The network where the USDC actually moves.

Get started

Pick your starting point

In your AI editor

Claude Code, Cursor or Codex. Creates a wallet and adds every node as a tool.

terminal

npx agentcash add https://tollnode.com

In your own code

Wrap fetch with an x402 client and cap what it may spend per call.

Show the JavaScript

javascript

// npm i @x402/fetch @x402/evm viem
import { wrapFetchWithPayment, x402Client } from "@x402/fetch";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";

const signer = privateKeyToAccount(process.env.AGENT_WALLET_KEY);
const client = registerExactEvmScheme(
  new x402Client().setSpendControls({ maxAmountPerPayment: "$0.50" }),
  { signer },
);
const pay = wrapFetchWithPayment(fetch, client);

const res = await pay("https://tollnode.com/api/v1/nodes/web-search", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ query: "x402 protocol" }),
});
console.log(res.status, await res.json());

Just look

See a real 402 price quote. Free, nothing is charged.

terminal

curl -i -X POST https://tollnode.com/api/v1/nodes/vin-decode \
  -H 'content-type: application/json' \
  -d '{"vin":"1HGCM82633A004352"}'

Funding tip: send USDC on the Base network, not Ethereum. Your address is the same on both, so a transfer on the wrong one still "arrives", just where the agent can't spend it. We learned that one the expensive way.

For the curious

The details

Why is it called 402?

HTTP has had a status code for Payment Required since the 1990s. It was marked "reserved for future use", and for about thirty years almost nothing used it, because there was no way to pay in the middle of a request. Cards need a checkout page and bank transfers take days.

Stablecoins on fast networks fixed that. A wallet signs in milliseconds and the transfer lands in a couple of seconds for a fraction of a cent. x402, created by Coinbase, is the agreement on how a server asks and how a client answers. The reference SDKs are open source as the @x402 packages on npm.

What is inside a 402 response?

The decoded PAYMENT-REQUIRED header from one of our endpoints, trimmed a little:

{
  "x402Version": 2,
  "resource": {
    "url": "https://tollnode.com/api/v1/nodes/image-instant",
    "method": "POST",
    "description": "Instant text-to-image. Charged only when the call succeeds."
  },
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "amount": "8000",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "payTo": "0x58F2…2fFac",
      "maxTimeoutSeconds": 300,
      "extra": { "name": "USD Coin", "version": "2" }
    }
  ]
}

amount is in the token's smallest unit: USDC has six decimals, so 8000 is $0.008. eip155:8453 means Base mainnet. asset is the USDC contract and payTo the seller's wallet. maxTimeoutSeconds is how long the signature stays valid, which gives the seller time to do the work before settling. A careful client checks all of it before signing.

Why USDC on Base?

USDC is meant to be worth exactly one dollar, so prices don't swing while you pay. Base is a network built on Ethereum where fees are a fraction of a cent and blocks arrive about every two seconds. That is what makes a half-cent purchase sensible; on Ethereum itself the fee would often cost more than the call. x402 also runs on other networks such as Solana, and each seller lists what it accepts in the 402.

Why does the buyer pay no gas?

The buyer signs an authorization (EIP-3009) instead of sending a transaction. The facilitator submits it on chain and pays the network fee, so a wallet that holds only USDC can pay.

V1 and V2 headers

Version 1 put the requirements in the 402's JSON body and used an X-PAYMENT request header. Version 2 moved everything into headers: PAYMENT-REQUIRED, PAYMENT-SIGNATURE and PAYMENT-RESPONSE. The official SDK speaks both, and TollNode accepts both.

I want to sell with x402. What did you learn?

You need a wallet address to receive payments, a facilitator account, and middleware that answers 402. A few lessons from building TollNode: verify before doing the work and settle after it, so a backend failure never needs a manual refund. Make payments idempotent, because clients retry the same signature. Quote a fixed price to requests without a body, since indexers probe endpoints bare. And publish /openapi.json, /llms.txt and /.well-known/x402, then register on x402scan so agents can find you.

FAQ

Quick answers

Is x402 a cryptocurrency?

No. x402 is a protocol, a set of HTTP headers and rules. The money it moves is usually USDC, a stablecoin worth one US dollar, on a fast network such as Base.

Do I need ETH to pay with x402?

No. The buyer only signs an authorization. The facilitator submits the transfer and pays the network fee, so a wallet holding only USDC on Base can pay.

What happens if the API fails after I paid?

It depends on the seller. Signing does not move money; settlement does. TollNode settles only after a usable result, so a failed or timed-out call is never charged.

Can a seller take more than the quoted price?

No. Your wallet signs an exact amount to an exact address with an expiry time. The signature cannot be reused for more, and a good client checks the amount before signing.

How much USDC should an agent wallet hold?

Only what you are happy for it to spend. A few dollars covers hundreds of cheap calls. Set a per-payment cap in your client as well.

Can I use x402 without a wallet?

Not directly. If you would rather not manage a wallet, TollNode also sells the same calls through a normal API key on a prepaid balance.

60 models, one price each, paid per call

Image, video, speech, music, web search and more. From $0.003 a call.

Browse the nodes Model guides