Pay for an API per call from an AI agent with x402

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.

1. See the 4022. Pay from Node3. Budget guardOr pay from a wallet app

How one paid call works

  1. The agent sends a normal GET. No key, no account.
  2. The server returns 402 plus a PAYMENT-REQUIRED header: base64 JSON listing each accepted network, the amount in atomic units, the token contract and the payTo address.
  3. The client picks a network and signs. On Base that is an EIP-3009 transferWithAuthorization for USDC, signed off-chain.
  4. The client repeats the request with a 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.
  5. The server returns 200 with the data and a PAYMENT-RESPONSE header describing the settlement.

Step 1: read the price before paying

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"}

Step 2: pay from Node with @x402/fetch

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.

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:

Errors you will see

ResponseMeaning
402, invalid_exact_evm_insufficient_balanceThe wallet has less USDC on Base than the price. Nothing was paid.
402 again after signing, other reasonWrong network, expired authorization or a signature the facilitator could not verify. Nothing was paid.
400Bad input, for example a wallet that is not base58. Fix it before paying.
502The upstream data source failed. Wallet Doctor does not settle in that case.

Endpoints you can call this way

EndpointInputPrice
/wallet-doctor/v1/balancewallet$0.0001
/wallet-doctor/v1/txtracesignature$0.0005
/wallet-doctor/v1/approvalswallet$0.0005
/wallet-doctor/v1/token_safetymint$0.0010
/wallet-doctor/v1/drain_forensicswallet$0.0025

All on https://manhourplan.com, USDC on Base or Solana. Machine-readable: x402 catalog · OpenAPI. Read-only Solana data, not financial advice.

Don't want to write code? The try page runs the same flow from MetaMask, Coinbase Wallet or Phantom: it shows the live price, you sign, and the result appears on the page.