How to pay for one call

One handshake, and one rule about money.

The handshake is two requests. The first carries no payment and gets a 402 with the terms. The second is the identical request plus one header holding the payment, and it gets the answer plus a receipt header. Nothing on the way asks for an account, a key or a person.

The rule is the order of operations: the handler runs first, and the payment settles only after a response below 400 is ready. On x402, on MPP's evm method, on a Tempo charge, on a card and on credits, a 4xx or 5xx cancels settlement and nothing is charged; a 200 is charged only if its settlement then succeeds, and if it does not, the answer is withheld and you get a 402 instead of a result you paid for.

One exception is stated wherever it applies below: a Tempo push transfer is already on chain before the request arrives, so on that path an undelivered answer is a debt to you, recorded in the refund ledger and repaid after on-chain proof. /proof shows settled receipts next to their quotes.

x402: a stablecoin from your own wallet.

x402 is served on every paid route. This server settles it on twelve chains: USDC on Base, Solana, Polygon, Arbitrum, Monad, Celo, Avalanche, Sei, Optimism, Stellar and Algorand, plus USDG on Robinhood Chain. On the EVM chains the facilitator sponsors gas, so the wallet needs only the stablecoin; Solana, Stellar and Algorand each use their own wallet and their own scheme package.

What you need

A private key for a wallet that holds a little of the stablecoin on one chain from the table. The key never leaves your process: the client signs a transfer authorization for exactly the quoted amount, and the facilitator moves the funds wallet to wallet. 40 routes (the identity-bound ones such as memory, and the long-running report routes) take an EVM authorization only; /api/pricing lists each route's networks and its 402 offers only those.

See a quote, free

curl -i -X POST https://agent402.tools/api/hash \
  -H 'Content-Type: application/json' -d '{"text":"hello world"}'
# HTTP/2 402  (the same terms ride base64 in the PAYMENT-REQUIRED header)
# {"x402Version":2,"accepts":[{"scheme":"exact","network":"eip155:8453",
#   "amount":"1000","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
#   "payTo":"0x…","maxTimeoutSeconds":…}, … one entry per chain …]}

amount is in the asset's smallest unit (six decimals for USDC), so $0.001 reads as 1000. Every accept entry names its own network, asset and payTo; a client picks the one it can sign.

Pay it

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

const client = new x402Client();
client.setSpendControls?.(false); // keep your own ceiling in code instead
registerExactEvmScheme(client, { signer: privateKeyToAccount(process.env.AGENT_KEY) });
const payFetch = wrapFetchWithPayment(fetch, client);

const res = await payFetch("https://agent402.tools/api/extract", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ url: "https://example.com/article" }),
});
console.log(res.status, res.headers.get("payment-response"), await res.json());

That one wrapped fetch pays every route on the EVM chains at $0.010 for /api/extract and the catalog price elsewhere. For Solana, Stellar and Algorand, register that chain's exact scheme on the same client. The buyer SDK wraps the same thing with spend caps and a stable idempotency key per call:

import { Agent402 } from "agent402-client";

const a = new Agent402({ fetch: payFetch, maxPerCallUsd: 0.05, dailyLimitUsd: 2 });
const article = await a.call("extract", { url: "https://example.com/article" });

What the receipt looks like

HTTP/2 200
PAYMENT-RESPONSE: eyJzdWNjZXNzIjp0cnVlLCJ0cmFuc2FjdGlvbiI6IjB4…
# base64 JSON: {"success":true,"transaction":"0x…","network":"eip155:8453","payer":"0x…"}
{ "title": "…", "markdown": "…", "wordCount": 1180 }

transaction is the on-chain settlement, so you can check on the chain's explorer what was paid. A refused payment answers 402 again with a reason naming the field that differed from the offer; /x402-test lists every reason this server emits, and a refusal costs nothing.

MPP: the same handshake in HTTP auth headers.

MPP, the Machine Payments Protocol, carries the quote in WWW-Authenticate: Payment and the payment in Authorization: Payment, and the settled answer returns a Payment-Receipt. The same 402 carries both the x402 offer and the MPP challenges, so your client picks the dialect.

The 402 lists the methods in this order: tempo, then evm, then stripe. A stock mppx client takes the first one it holds a method for.

What you need

For the tempo method, a key funded with the stablecoin on Tempo. For evm, the same EVM key you would use for x402. For a card, a shared payment token from the card wallet your agent holds. The mppx client signs the challenge it can satisfy and retries for you.

import { Mppx, tempo, evm } from "mppx/client";
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(process.env.AGENT_KEY);
const mppx = Mppx.create({ methods: [tempo.charge({ account }), evm.charge({ account })] });

// $0.001 per call; the first request returns 402, mppx pays and retries.
const res = await mppx.fetch("https://agent402.tools/api/crypto-price?coins=BTC,ETH&currency=usd");
console.log(res.status, res.headers.get("payment-receipt"), await res.json());

What the receipt looks like

HTTP/2 200
Payment-Receipt: eyJtZXRob2QiOiJ0ZW1wbyIsInJlZmVyZW5jZSI6IjB4…
# base64url JSON: {"method":"tempo","reference":"0x…","status":"success","timestamp":"2026-…"}

reference is the settlement transaction on the method's chain (for the evm method it is the same transaction an x402 receipt would carry). Tempo settlements are listed with their explorer links on /revenue.

Charge and push. A Tempo charge credential is broadcast by this server only after the handler answers below 400, so a 4xx or 5xx on a Tempo charge is not charged. A Tempo push credential is a transfer your client already sent; the server finalizes it before the handler runs, and if the answer then fails or never reaches you, the amount is booked as owed to your wallet in the refund ledger.

Card over MPP. On routes priced $0.50 or more the same 402 carries a stripe challenge. Your agent presents a shared payment token from its card wallet in Authorization: Payment; the card is captured only after the handler has answered with a 200, and a 4xx or 5xx on the card path leaves nothing captured. A person can also buy a finished report by card at /reports with no agent at all.

Prepaid credits: a key instead of a wallet.

New credits are not on sale. A key already issued (a402_...) keeps working exactly as described here; a new buyer pays per call with a wallet over x402 or MPP, or uses the free tier below.

How a key pays

curl -X POST https://agent402.tools/api/extract \
  -H "Authorization: Bearer a402_YOUR_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://example.com/article"}'
# 200 with the answer, and X-Credits-Balance: <what is left>

curl -H "Authorization: Bearer a402_YOUR_KEY" https://agent402.tools/api/credits/balance

The gate authorizes before the handler runs (the balance must cover the route's list price), holds that amount, and debits it only on a final 200; a 4xx or 5xx on credits releases the hold. The X-Credits-Balance header on every answer carries what is left, and a refused call answers 402 with the balance and nothing debited. Credits never expire.

Credits are refused on the identity-bound routes (memory, usage, attest, feedback), where the signed payer address is the identity; those take a wallet. The buyer SDK sends the key for you: pass it as creditsKey to new Agent402() and every wallet-only call carries the header.

No wallet: pay the pure-CPU tools with proof-of-work.

170 tools (hashing, encoding, JSON, dates, text, finance math and more) also accept a solved sha256 puzzle instead of money: about 65,536 sha256 hashes on average, a fraction of a second of CPU on a laptop at the current difficulty of 16 bits. No money and no model are involved on these tools. Each one is marked computePayable: true on /api/pricing, and the 402 of an eligible route names its challenge URL in X-Pow-Challenge.

curl -s "https://agent402.tools/api/pow/challenge?slug=hash"
# { "challenge": "…", "difficulty": 16, "token": "…", "ttlSeconds": … }

# find an integer nonce so sha256("<challenge>:<nonce>") has at least
# <difficulty> leading zero bits, then send the TOKEN (not the challenge):
curl -X POST https://agent402.tools/api/hash \
  -H 'Content-Type: application/json' \
  -H "X-Pow-Solution: <token>:<nonce>" \
  -d '{"text":"hello world"}'

import { createHash } from "node:crypto";
const lz = (b) => { let t = 0; for (const x of b) { if (!x) { t += 8; continue; } t += Math.clz32(x) - 24; break; } return t; };
const c = await (await fetch("https://agent402.tools/api/pow/challenge?slug=hash")).json();
let n = 0;
while (lz(createHash("sha256").update(c.challenge + ":" + n).digest()) < c.difficulty) n++;
const res = await fetch("https://agent402.tools/api/hash", {
  method: "POST",
  headers: { "Content-Type": "application/json", "X-Pow-Solution": c.token + ":" + n },
  body: JSON.stringify({ text: "hello world" }),
});

A solved call answers 200 with X-Pow-Accepted: true; a wrong or reused solution answers 402 with X-Pow-Error naming why. A challenge is single-use, scoped to one tool, and expires. The free tier is rate-limited per client (20/min, 120/hour per client); a limited call says so in X-Pow-Limits. The buyer SDK solves the puzzle for you: new Agent402() with no fetch pays every eligible tool this way.

From an MCP host, the payment rides underneath.

The hosted connector at https://agent402.tools/mcp serves the free tier with no install and no wallet, and makes the wallet-only tools payable over MPP from an mppx-aware MCP client. The npm server pays over x402 from a key you give it, with spend caps checked before any payment is signed.

# hosted, no wallet: the proof-of-work tools
claude mcp add --transport http agent402 https://agent402.tools/mcp

# npm server with a funded EVM key: every paid tool over x402
claude mcp add agent402 -s user -e AGENT_KEY=0xYOUR_FUNDED_KEY -- npx -y agent402-mcp@latest

# a credits key already issued works there too
claude mcp add agent402 -s user -e AGENT402_CREDITS_KEY=a402_YOUR_KEY -- npx -y agent402-mcp@latest

Every host's verified config block is in the agent-hosts guide; /quickstart has the same first call for curl, JavaScript and the model gateway.

What happens to the money, rail by rail.

The hang-up budget is bounded on purpose. A buyer whose connection closes before the first response byte is not settled while the service holds a forgiveness ticket for that request, priced at what it would have charged, against a per-wallet, per-IP and service-wide budget that a paid success never refills. The budget never refuses service: once it is spent, the call is settled as it would be without the rule, and the charge is booked as owed and repaid from the refund ledger after on-chain proof. Routes whose effect outlives the answer (memory writes, attestations, purchases from outside sellers) never take a ticket.

Retries. Send an Idempotency-Key header (or the x402 payment-identifier extension) and a repeat of the same credential, route and body within 10 minutes replays the settled 200 without a second settlement. On the x402 wallet path the key is bound to the exact signed authorization: a fresh signature is a fresh payment, so keep the signed request and resend it yourself, or use a credits key for the calls you retry.

Refunds. A charged-but-undelivered call is recorded as a debt with its settlement transaction as evidence and repaid from a separate, capped job after review; the server never holds a spending key. A refused payment is free to get wrong: /x402-test decodes each refusal.

Read it yourself before you pay.

• /api/pricing: every route, its price, its networks, and computePayable on the free ones.
• /.well-known/x402: the machine-readable manifest, with the chains and MPP methods this instance takes.
• /x402-test: point any client at a real paid route and read why it was refused.
• /proof: settled receipts next to the quotes they were paid against.
• /status: the paid path measured from outside, continuously.
• /revenue: every settlement on these rails, read from the chains.