An agent that hits a paywall cannot fill in a signup form or a card field. x402 fixes 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 page walks through one real call end to end, with code we ran on 21 November 2026, against a live endpoint that costs $0.0001.
GET. No key, no account.402 plus a PAYMENT-REQUIRED header: base64 JSON listing each accepted network, the amount in atomic units, the token contract and the payTo address.transferWithAuthorization for USDC, signed off-chain.PAYMENT-SIGNATURE header. 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.200 with the data and a PAYMENT-RESPONSE header describing the settlement.Any HTTP client can see the terms. This decodes the header for Wallet Doctor's balance endpoint:
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 we 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"}
Install the official client packages (we used 2.32.0) and viem:
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 that holds 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 we verified: with a throwaway, unfunded key the script reads the terms, signs, and PayAI 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.
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:
payTo and asset are the addresses you expect (USDC on Base is 0x8335…2913).PAYMENT-RESPONSE receipt next to the result, so every spend can be audited.| Response | Meaning |
|---|---|
402, invalid_exact_evm_insufficient_balance | The wallet has less USDC on Base than the price. Nothing was paid. |
| 402 again after signing, other reason | Wrong network, expired authorization or a signature the facilitator could not verify. Nothing was paid. |
| 400 | Bad input, for example a wallet that is not base58. Fix it before paying. |
| 502 | The upstream data source failed. Wallet Doctor does not settle in that case. |
| Endpoint | Input | Price |
|---|---|---|
/wallet-doctor/v1/balance | wallet | $0.0001 |
/wallet-doctor/v1/txtrace | signature | $0.0005 |
/wallet-doctor/v1/approvals | wallet | $0.0005 |
/wallet-doctor/v1/token_safety | mint | $0.0010 |
/wallet-doctor/v1/drain_forensics | wallet | $0.0025 |
All on https://manhourplan.com, USDC on Base or Solana. Machine-readable: x402 catalog · OpenAPI. Read-only Solana data, not financial advice.