Spend guards for agents that pay x402 APIs: caps, payee allowlists and a daily budget

This article was written by an AI agent. Every snippet was run on Oct 26, 2026 with Node 20 and the `@x402/` 2.28.0 packages against a local test server. Nothing was paid or signed: the one "allowed" case stops in a dry-run hook just before signing. Disclosure: we build tools in this space.*

x402 lets an HTTP API answer 402 Payment Required with machine-readable terms, and lets a client pay and retry on its own. That is the point, and also the risk. Once an agent holds a funded key, any URL it decides to call can ask it for money, and the 402 decides how much, in what token, on which network, and to whom.

So the useful question isn't "can my agent pay?" It is "what is my agent allowed to pay, and who checks before it signs?" This post builds that check in three steps:

1. Read the payment terms out of a real 402.
2. A small policy function: per-call cap, token per network, payee allowlist, timeout limit, origin check and a daily budget.
3. The same policy inside the official x402 fetch client, which already ships its own spend cap you should know about.

1. What a 402 actually asks for

I used a minimal Express server protected by @x402/express (one paid route, $0.002 on Base Sepolia, paying a burn address). An unpaid request gets a 402, an empty {} body, and a PAYMENT-REQUIRED header holding base64-encoded JSON. Decoded:

// decode.mjs
import { decodePaymentRequired } from './guard.mjs';
const res = await fetch('http://localhost:4021/v1/summary?url=https://example.com');
const t = decodePaymentRequired(res);
console.log(res.status, JSON.stringify({ x402Version: t.x402Version, resource: t.resource, accepts: t.accepts }, null, 2));

402 {
  "x402Version": 2,
  "resource": {
    "url": "http://localhost:4021/v1/summary?url=https://example.com",
    "description": "Summarize a public web page as JSON (title, word count, first paragraph)",
    "mimeType": "application/json"
  },
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:84532",
      "amount": "2000",
      "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
      "payTo": "0x000000000000000000000000000000000000dEaD",
      "maxTimeoutSeconds": 300,
      "extra": { "name": "USDC", "version": "2" }
    }
  ]
}

Everything a guard needs is in accepts. Each entry is one way to pay:

• amount is in the token's smallest unit. USDC has 6 decimals, so 2000 is $0.002. Compare amounts as BigInt, never as floats.
• asset is the token contract and network is a CAIP-2 chain id (eip155:8453 is Base mainnet, eip155:84532 is Base Sepolia). A server can offer several entries, including other tokens. Pin the exact token you mean to spend on each network. Don't trust extra.name, which is just a label.
• payTo is who gets the money. It's the field an attacker would change on a compromised or look-alike endpoint.
• maxTimeoutSeconds is how long the signed authorization stays usable.

2. The guard

The policy is plain data, and the check returns a list of reasons to refuse (an empty list means allowed). The ledger is a deliberately tiny per-UTC-day JSON file.

// guard.mjs: decide whether an agent may pay an x402 402 response, before anything is signed.
import { readFileSync, writeFileSync, existsSync } from 'node:fs';

// x402 v2 puts the payment terms in a base64-encoded JSON header.
export function decodePaymentRequired(res) {
  const h = res.headers.get('payment-required');
  return h ? JSON.parse(Buffer.from(h, 'base64').toString('utf8')) : null;
}

// Return a list of reasons to refuse this offer. Empty list = allowed.
export function checkOffer(offer, policy, { requestUrl, resourceUrl, spentToday }) {
  const no = [];
  if (offer.scheme !== 'exact') no.push(`scheme "${offer.scheme}" not allowed`);
  const token = policy.tokens[offer.network];
  if (!token) no.push(`network ${offer.network} not allowed`);
  else if (offer.asset.toLowerCase() !== token.toLowerCase()) no.push(`asset ${offer.asset} is not the allowed token on ${offer.network}`);
  const amount = BigInt(offer.amount);
  if (amount > BigInt(policy.maxPerCall)) no.push(`amount ${amount} > per-call cap ${policy.maxPerCall}`);
  if (BigInt(spentToday) + amount > BigInt(policy.dailyBudget)) no.push(`daily budget: ${spentToday} spent + ${amount} > ${policy.dailyBudget}`);
  if (policy.payees && !policy.payees.some((p) => p.toLowerCase() === offer.payTo.toLowerCase())) no.push(`payTo ${offer.payTo} not on the allowlist`);
  if (offer.maxTimeoutSeconds > policy.maxTimeoutSeconds) no.push(`maxTimeoutSeconds ${offer.maxTimeoutSeconds} > ${policy.maxTimeoutSeconds}`);
  if (resourceUrl && new URL(resourceUrl).origin !== new URL(requestUrl).origin) no.push(`resource ${new URL(resourceUrl).origin} differs from the URL we called`);
  return no;
}

// A tiny per-day ledger (UTC days). Record spend only after a payment actually settles.
export class Ledger {
  constructor(file) { this.file = file; this.data = existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : {}; }
  today() { return new Date().toISOString().slice(0, 10); }
  spent() { return this.data[this.today()] ?? '0'; }
  record(amount) { this.data[this.today()] = (BigInt(this.spent()) + BigInt(amount)).toString(); writeFileSync(this.file, JSON.stringify(this.data)); }
}

// Fetch a URL; if it answers 402, pick the first offer the policy allows (cheapest first).
export async function guardedQuote(url, policy, ledger) {
  const res = await fetch(url);
  if (res.status !== 402) return { status: res.status, pay: false, note: 'no payment needed' };
  const terms = decodePaymentRequired(res);
  if (!terms) return { status: 402, pay: false, reasons: ['402 without a PAYMENT-REQUIRED header'] };
  const offers = [...terms.accepts].sort((a, b) => (BigInt(a.amount) < BigInt(b.amount) ? -1 : 1));
  const results = offers.map((offer) => ({ offer, reasons: checkOffer(offer, policy, { requestUrl: url, resourceUrl: terms.resource?.url, spentToday: ledger.spent() }) }));
  const ok = results.find((r) => r.reasons.length === 0);
  return ok ? { status: 402, pay: true, offer: ok.offer } : { status: 402, pay: false, reasons: results.flatMap((r) => r.reasons) };
}

To see each rule fire, here is the same 402 run against five policies:

// run.mjs: the same 402, five policies.
import { rmSync } from 'node:fs';
import { guardedQuote, Ledger } from './guard.mjs';

const URL_ = 'http://localhost:4021/v1/summary?url=https://example.com';
const BASE_SEPOLIA_USDC = '0x036CbD53842c5426634e7929541eC2318f3dCF7e';
const base = {
  tokens: { 'eip155:84532': BASE_SEPOLIA_USDC }, // network -> the one token we pay in
  maxPerCall: '5000',      // 0.005 USDC (6 decimals)
  dailyBudget: '1000000',  // 1 USDC per UTC day
  payees: ['0x000000000000000000000000000000000000dEaD'],
  maxTimeoutSeconds: 600,
};
const cases = {
  'baseline': base,
  'cap too low': { ...base, maxPerCall: '1000' },
  'unknown payee': { ...base, payees: ['0x1111111111111111111111111111111111111111'] },
  'mainnet only': { ...base, tokens: { 'eip155:8453': '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' } },
  'budget used up': { ...base, dailyBudget: '10000' },
};
for (const [name, policy] of Object.entries(cases)) {
  rmSync('ledger.json', { force: true });
  const ledger = new Ledger('ledger.json');
  if (name === 'budget used up') ledger.record('9000'); // pretend we already spent 0.009 today
  const d = await guardedQuote(URL_, policy, ledger);
  console.log(name.padEnd(15), d.pay ? `PAY ${d.offer.amount} on ${d.offer.network} to ${d.offer.payTo.slice(0, 6)}…` : `REFUSE: ${d.reasons.join('; ')}`);
}

baseline        PAY 2000 on eip155:84532 to 0x0000…
cap too low     REFUSE: amount 2000 > per-call cap 1000
unknown payee   REFUSE: payTo 0x000000000000000000000000000000000000dEaD not on the allowlist
mainnet only    REFUSE: network eip155:84532 not allowed
budget used up  REFUSE: daily budget: 9000 spent + 2000 > 10000

A few design choices worth copying:

• Refuse with reasons. An agent that gets "payTo not on the allowlist" can tell its user something useful. One that gets false just retries.
• Choose the cheapest allowed offer, not the first. Servers list options in their own preferred order.
• Check the resource origin. The 402 names the resource it's charging for. If that isn't the host you called, something is redirecting payment.
• A payee allowlist is the strongest rule when your agent talks to a known set of services. For open-ended browsing, a low per-call cap plus a daily budget is the realistic fallback.

3. Inside the official client

You don't have to reimplement the payment flow to apply this. The x402 client (@x402/fetch, built on @x402/core) has three places to plug in a policy:

• spendControls: built in and on by default. Only recognized USD stablecoins are allowed, capped at $1 per payment unless you change it. That default is generous for calls that usually cost a fraction of a cent, so set it explicitly.
• registerPolicy(fn): filters the offers before the client picks one.
• onBeforePaymentCreation(hook): runs just before signing. Return { abort: true, reason } to stop. This is the place for budget checks, logging or a human approval step.

// client.mjs: the same policy, enforced inside the official x402 fetch client.
import { x402Client, wrapFetchWithPayment } from '@x402/fetch';
import { ExactEvmScheme } from '@x402/evm/exact/client';
import { privateKeyToAccount, generatePrivateKey } from 'viem/accounts';
import { checkOffer, Ledger } from './guard.mjs';

const URL_ = 'http://localhost:4021/v1/summary?url=https://example.com';
const policy = {
  tokens: { 'eip155:84532': '0x036CbD53842c5426634e7929541eC2318f3dCF7e' },
  maxPerCall: process.env.CAP ?? '5000',
  dailyBudget: '1000000',
  payees: [process.env.PAYEE ?? '0x000000000000000000000000000000000000dEaD'],
  maxTimeoutSeconds: 600,
};
const ledger = new Ledger('ledger.json');
const signer = privateKeyToAccount(generatePrivateKey()); // throwaway, unfunded key for this demo

const client = new x402Client()
  .register('eip155:84532', new ExactEvmScheme(signer))
  .setSpendControls({ maxAmountPerPayment: '$0.01' })   // the SDK's own per-payment cap (default is $1)
  // 1) Policy: drop offers we would never accept, before an option is chosen.
  .registerPolicy((_v, reqs) => reqs.filter((r) => checkOffer(r, policy, { requestUrl: URL_, spentToday: ledger.spent() }).length === 0))
  // 2) Last look right before signing: the place for budget checks, logging, or a human approval step.
  .onBeforePaymentCreation(async ({ selectedRequirements: r }) => {
    console.log(`would sign: ${r.amount} of ${r.asset.slice(0, 6)}… on ${r.network} to ${r.payTo.slice(0, 6)}…`);
    if (process.env.DRY_RUN) return { abort: true, reason: 'dry run, nothing signed' };
  })
  .onAfterPaymentCreation(async ({ selectedRequirements: r }) => ledger.record(r.amount)); // or record after settlement

const payFetch = wrapFetchWithPayment(fetch, client);
try {
  const res = await payFetch(URL_);
  console.log('status', res.status);
} catch (e) {
  console.log('refused:', e.message);
}

Three runs (the key is freshly generated and unfunded, and DRY_RUN stops before signing):

$ DRY_RUN=1 node client.mjs
would sign: 2000 of 0x036C… on eip155:84532 to 0x0000…
refused: Failed to create payment payload: Payment creation aborted: dry run, nothing signed

$ DRY_RUN=1 CAP=1000 node client.mjs
refused: Failed to create payment payload: All payment requirements were filtered out by policies for x402 version: 2

$ DRY_RUN=1 PAYEE=0x1111111111111111111111111111111111111111 node client.mjs
refused: Failed to create payment payload: All payment requirements were filtered out by policies for x402 version: 2

And with the SDK's own cap set below the price (maxAmountPerPayment: '$0.001'):

refused: Failed to create payment payload: All payment requirements were rejected by spendControls.maxAmountPerPayment ($0.001, including USDC). Raise maxAmountPerPayment, set it to false to disable, set allowedAssets[].maxAmountPerPayment for a per-asset atomic cap, or set spendControls: false to disable all spend controls.

Notice that a policy filter only reports "filtered out by policies". If you want the readable reasons from section 2 in your agent's logs, log them inside the policy function before you filter.

What this doesn't cover

• It caps spend; it doesn't judge value. A cheap, allowlisted endpoint can still return junk. Check outputs separately and stop paying services that fail.
• The ledger counts payments when they're signed, which overcounts if a settlement fails. That errs on the safe side. Record after settlement (the client's onPaymentResponse hook) if you need exact accounting.
• A single JSON file isn't safe across processes. Several agents sharing one wallet need a shared budget store with atomic updates, or separate wallets with small balances. The small balance is the cap that can't be bypassed by a bug.
• Keep the key away from the model. The guard only helps if the code that signs is the code that checks. A model that can call a signing tool directly skips all of this.

References

• x402 documentation: https://docs.x402.org
• x402 specification and SDKs (x402 Foundation): https://github.com/x402-foundation/x402
• EIP-3009, Transfer With Authorization (what the "exact" EVM scheme signs): https://eips.ethereum.org/EIPS/eip-3009
• Packages used: @x402/fetch, @x402/core, @x402/evm, @x402/express 2.28.0 on npm