For agent builders
Agent spending safeguards
An agent that can pay can overpay: a mispriced 402, a hostile seller, or a loop that calls the same paid endpoint a thousand times. x402 leaves the limits to the buyer, and the @x402 client packages give you the tools. This page stacks them in five layers, from the wallet out, with a daily-budget sample we ran against our live API on 11/20/2026.
Five layers, outermost first
1.A dedicated wallet with a small balance
The hardest limit is money that is not there. Give each agent its own wallet, fund it with what it may spend this week, and top it up rather than pointing it at a treasury. The payer needs only USDC: the facilitator pays the gas, and an EIP-3009 authorization moves only the exact amount signed. Keep the private key in an environment variable or a secrets manager, never in code, a prompt or a repository.
2.A cap on every single payment
spendControls.maxAmountPerPayment makes the client refuse any payment above the cap before it signs. If you omit spendControls, @x402/core 2.28 still applies a default cap of $1.00; passing spendControls: false removes every cap, so never do it. Our MCP server ships with a $2.00 per-call cap, set with MAX_USDC_PER_CALL.
A static cap goes stale when the seller's prices change. An earlier example on our own agents page capped payments at $0.60, set when our dearest call was $0.50; when we added a $2.00 product, that example refused it. Set the cap to the dearest call you mean to buy, and re-check it when prices change.
3.Only the networks and assets you pay with
Network scoping is scheme registration: register eip155:8453 (Base mainnet) and the client cannot pay on any other chain; eip155:* accepts every EVM chain. Network names follow CAIP-2. By default the client pays only in the package's recognized default assets, such as USDC; leave allowedAssets unset unless you need another token.
const client = x402Client.fromConfig({ // Register only the networks you mean to pay on. Network scoping is scheme registration: // "eip155:8453" is Base mainnet only; "eip155:*" would accept any EVM chain. schemes: [{ network: "eip155:8453", client: new ExactEvmScheme(account) }], spendControls: { maxAmountPerPayment: 2.0, // dollars; the client refuses any single payment above this // allowedAssets omitted: only the package's recognized default assets (such as USDC) are payable }, }); // Never pass spendControls: false. It removes every cap and lets any asset through.4.A daily budget and a seller allowlist
The packages have no built-in daily or per-seller limit, but an onBeforePaymentCreation hook runs before anything is signed, and returning { abort: true, reason } stops the payment. The script below keeps a running daily total in USDC's six-decimal units and refuses any seller whose payout wallet is not on your list. It counts a payment when it is signed, so a refused payment still counts: it errs on the safe side. For an agent that restarts, keep the total in a file or database instead of memory. More on the idea: budget management.
// budget.mjs (Node 20+, run: AGENT_PRIVATE_KEY=0x... DAILY_BUDGET_USD=5 node budget.mjs) import { privateKeyToAccount } from "viem/accounts"; import { wrapFetchWithPayment, x402Client } from "@x402/fetch"; import { ExactEvmScheme } from "@x402/evm/exact/client"; const account = privateKeyToAccount(process.env.AGENT_PRIVATE_KEY); const DAILY_BUDGET_USD = Number(process.env.DAILY_BUDGET_USD ?? "5"); // Sellers this agent may pay: the payTo wallets you have checked. Leave empty to allow any seller. const ALLOWED_PAY_TO = (process.env.ALLOWED_PAY_TO ?? "").split(",").filter(Boolean).map((a) => a.toLowerCase()); let day = new Date().toISOString().slice(0, 10); let spentAtomic = 0n; // USDC has 6 decimals: 1000000 = $1.00 const client = x402Client.fromConfig({ schemes: [{ network: "eip155:8453", client: new ExactEvmScheme(account) }], spendControls: { maxAmountPerPayment: 2.0 }, }); client.onBeforePaymentCreation(async ({ selectedRequirements: r }) => { const today = new Date().toISOString().slice(0, 10); if (today !== day) { day = today; spentAtomic = 0n; } if (ALLOWED_PAY_TO.length && !ALLOWED_PAY_TO.includes(r.payTo.toLowerCase())) { return { abort: true, reason: `seller ${r.payTo} is not on the allowlist` }; } const next = spentAtomic + BigInt(r.amount); if (next > BigInt(Math.round(DAILY_BUDGET_USD * 1e6))) { return { abort: true, reason: `daily budget $${DAILY_BUDGET_USD.toFixed(2)} would be exceeded` }; } spentAtomic = next; // counted when signed, so a refused payment still counts: errs on the safe side }); const payFetch = wrapFetchWithPayment(fetch, client); try { const res = await payFetch("https://www.blockchainiq.co/api/x402/v1/event-risk?days=7"); console.log(res.status); } catch (e) { console.log("stopped:", e instanceof Error ? e.message : e); }What we checked on 11/20/2026, each run with a new, empty wallet so no money could move: a $0.00 budget stopped the payment before signing; a $5.00 budget let it sign, and our API refused it for lack of funds; an allowlist without our payout wallet stopped it.
5.Read the price first, keep every receipt
The first, unpaid request is free and returns the price in the PAYMENT-REQUIRED header, so an agent can decide before it pays. Check a seller's 402 with the 402 Inspector before you add it to the allowlist. After each paid call, log the PAYMENT-RESPONSE header (the settlement response: payer, network, transaction hash) so the wallet's history can be reconciled.
curl -s -D - -o /dev/null "https://www.blockchainiq.co/api/x402/v1/event-risk?days=7" | grep -i payment-required # payment-required: eyJ4NDAyVmVyc2lvbiI6Mi... (base64 JSON: amount, asset, network, payTo)
Checklist
- Use a dedicated wallet for the agent and fund it with only what it may spend; top it up, never point it at a treasury.
- Keep the private key in an environment variable or a secrets manager, never in code, prompts or a repository.
- Set spendControls.maxAmountPerPayment to the dearest call you mean to buy, and re-check it when the seller's prices change.
- Register only the networks you pay on, and leave allowedAssets alone unless you need a token other than the defaults.
- Add a daily budget and a seller allowlist in onBeforePaymentCreation; both run before anything is signed.
- Read the price in the free 402 before you buy, and log every receipt (the PAYMENT-RESPONSE header) for reconciliation.
Go further
- A complete buyer script: x402 quickstart.
- The protocol step by step: How x402 works.
- Our paid calls and prices (up to $2.00 a call, USDC on Base and Solana): Blockchain IQ for agents.
- Package docs: coinbase/x402 on GitHub.
General education, not investment, legal or tax advice. Samples tested 11/20/2026 with @x402 packages 2.28; check the package docs if a newer version changes an API.