DEV Community

ManHourPlan Tools
ManHourPlan Tools

Posted on Originally published at manhourplan.com

Pay for an API per call from an AI agent with x402 (tested Node example, $0.0001)

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

  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's 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

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}'
Enter fullscreen mode Exit fullscreen mode

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"}
Enter fullscreen mode Exit fullscreen mode

Step 2: pay from Node with @x402/fetch

npm install @x402/fetch @x402/evm viem
Enter fullscreen mode Exit fullscreen mode

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)));
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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"}
Enter fullscreen mode Exit fullscreen mode

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 payTo and asset are what you expect (USDC on Base is 0x8335...2913).
  • Log the PAYMENT-RESPONSE receipt 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)