An agent that hits a paywall can't fill in a signup form or a card field. x402 solves that with plain HTTP: the server answers 402 Payment Required with machine-readable terms, the client signs a USDC payment and retries, and the response comes back with a settlement receipt.
This post walks through one real call end to end. I ran the code on 21 November 2026 against a live endpoint that costs $0.0001. Disclosure: the endpoint is Wallet Doctor, a small API I run; any x402 endpoint works the same way.
How one paid call works
- The agent sends a normal
GET. No key, no account. - The server returns
402plus aPAYMENT-REQUIREDheader: base64 JSON listing each accepted network, the amount in atomic units, the token contract and thepayToaddress. - The client picks a network and signs. On Base that's an EIP-3009
transferWithAuthorizationfor USDC, signed off-chain. - The client repeats the request with a
PAYMENT-SIGNATUREheader. The server asks a facilitator (here PayAI) to verify and settle it. The facilitator submits the transfer, so the paying wallet needs USDC but no ETH. - The server returns
200with the data and aPAYMENT-RESPONSEheader describing the settlement.
Step 1: read the price before paying
curl -s -D - -o /dev/null "https://manhourplan.com/wallet-doctor/v1/balance?wallet=YOUR_SOLANA_WALLET" \
| grep -i '^payment-required:' | cut -d' ' -f2 | tr -d '\r' | base64 -d \
| jq -c '.accepts[] | {network, amount, asset, payTo}'
Output I got (Base first, Solana as an alternative; 100 atomic units of a 6-decimal token = $0.0001):
{"network":"eip155:8453","amount":"100","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","payTo":"0x7Dc83a4a626459e0ACB309C86dC0fEE0cC5052FC"}
{"network":"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp","amount":"100","asset":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","payTo":"5ukK2Z4qF2MwNSCQpnBDCXuuiFatAC9wn9cWz41famqg"}
Step 2: pay from Node with @x402/fetch
npm install @x402/fetch @x402/evm viem
Save as pay-per-call.mjs (Node 18+):
// pay-per-call.mjs: call an x402 API from Node and pay in USDC on Base,
// with a hard price cap checked BEFORE anything is signed.
import { wrapFetchWithPaymentFromConfig } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm";
import { privateKeyToAccount } from "viem/accounts";
const MAX_ATOMIC = 1000n; // 1000 = $0.001 (USDC has 6 decimals)
const url = "https://manhourplan.com/wallet-doctor/v1/balance?wallet=" + process.argv[2];
// 1) Ask without paying and read the terms from the PAYMENT-REQUIRED header.
const unpaid = await fetch(url);
if (unpaid.status !== 402) throw new Error("expected 402, got " + unpaid.status);
const terms = JSON.parse(atob(unpaid.headers.get("payment-required")));
const base = terms.accepts.find(a => a.network === "eip155:8453");
console.log("price:", base.amount, "atomic USDC to", base.payTo);
if (BigInt(base.amount) > MAX_ATOMIC) throw new Error("over budget, not paying");
// 2) Pay and retry. The wrapper signs an EIP-3009 USDC authorization;
// the facilitator submits it, so the wallet needs USDC on Base but no ETH.
const account = privateKeyToAccount(process.env.AGENT_WALLET_KEY);
const payFetch = wrapFetchWithPaymentFromConfig(fetch, {
schemes: [{ network: "eip155:8453", client: new ExactEvmScheme(account) }],
});
const res = await payFetch(url);
console.log(res.status, await res.text());
const receipt = res.headers.get("payment-response");
if (receipt) console.log("settlement:", JSON.parse(atob(receipt)));
Run it with a key for a dedicated hot wallet holding a few cents of USDC on Base:
AGENT_WALLET_KEY=0x... node pay-per-call.mjs YOUR_SOLANA_WALLET
With a funded wallet you get 200 and JSON like this (values illustrative):
{"ok": true, "wallet": "YOUR_SOLANA_WALLET", "sol": 0.0049, "usdc": 0, "slot": 472142843, "network": "solana-mainnet", "source": "solana-rpc"}
What I verified: with a throwaway, unfunded key the script reads the terms, signs, and the facilitator rejects the payment with invalid_exact_evm_insufficient_balance, so nothing is charged. A funded wallet completed the same flow on Base the same day.
Step 3: keep the agent on a budget
The script refuses to sign when the quoted amount is above MAX_ATOMIC. Keep that check in any agent that pays on its own, and also:
- Fund the agent's wallet with only what it may spend. A leaked key then costs cents, not savings.
- Check that
payToandassetare what you expect (USDC on Base is0x8335...2913). - Log the
PAYMENT-RESPONSEreceipt next to the result so every spend can be audited. - Never put the key in a prompt, a repo or a client-side bundle.
Errors you'll see
| Response | Meaning |
|---|---|
402, invalid_exact_evm_insufficient_balance
|
Not enough USDC on Base. Nothing was paid. |
| 402 again after signing, other reason | Wrong network, expired authorization or an unverifiable signature. Nothing was paid. |
| 400 | Bad input, e.g. a wallet that isn't base58. |
| 502 | Upstream data source failed. This endpoint doesn't settle in that case. |
Try it without code
If you'd rather click than code, the try page runs the same flow from MetaMask, Coinbase Wallet or Phantom and shows the live price before you sign. The full endpoint list and the x402 catalog are on the original post.
Top comments (0)