How do I set per-request and per-run spend caps for an AI agent that pays with x402?

What should I check, step by step?

1. Keep x402 spendControls on. Don't ship spendControls: false (Go: DisableSpendControls(), Python: spend_controls=False); that removes every cap and allows any asset.

2. Set the per-request cap with maxAmountPerPayment (default "$1"). For non-default tokens, list them in allowedAssets with an atomic-unit cap (for 6-decimal USDC, "2000000" is 2 USDC).
3. Treat x402 upto prices as the most you'll pay: the buyer signs for the maximum and the seller may settle for less, so apply the per-request cap to that maximum.
4. Add a per-run total the agent can't reset: CDP SDK maxCumulativeSpend plus maxCumulativeSpendWindow, or an onBeforePaymentCreation hook that aborts when spent_this_run + amount would exceed the run budget.
5. Key the running total by a run or session id you create before the first payment, and store it in durable storage the agent process can't rewrite (shared Redis/Postgres, or a policy service). The CDP SDK's default SpendStore is in memory and process-local.
6. Call the check from the payment path before signing: spendControls run before custom policies; use onBeforePaymentCreation for dynamic run totals and return { abort: true, reason } when over budget.
7. Fund a separate wallet with only that run's budget and top it up when the run starts. Cap the wallet, not a shared treasury key.
8. Log every allow and deny with run id, amount, asset, network and payTo, and alert before the run limit is reached (CDP has onApproachingLimit).

Per-request vs per-run

A per-request cap (x402 maxAmountPerPayment) blocks one payment that is too large. It does not stop 200 payments of $0.99 in the same research job. That needs a running total for the run.

• The x402 buyer quickstart says spend controls run before any custom policies and before the payment payload is signed. If every option the server offers is over the cap or in a disallowed asset, the client refuses to pay instead of picking one anyway.
• For static USD caps and asset allowlists, x402 docs prefer spendControls. Use onBeforePaymentCreation for dynamic checks such as a per-run budget, interactive approval, or a call out to a policy service.
• x402 MCP clients expose the same idea per tool: onPaymentRequired can abort a paid tool, and onBeforePayment / onAfterPayment are where you meter a run's spend across tool calls.

Where to keep the per-run total

Coinbase's CDP SDK SpendControls type takes maxAmountPerPayment, maxCumulativeSpend (asset required), maxCumulativeSpendWindow (for example "24h"), allowedNetworks, allowedAssets, allowedPayees, onApproachingLimit and an optional store. applySpendControls attaches that once to an x402Client; a second call throws already_applied.

• Its SpendStore docs say the default implementation is in-memory and process-local. For a cap that must survive restarts or several replicas, pass a store backed by Redis, Postgres or similar. Without that, a crash-and-restart loop resets the run budget.
• Without the CDP SDK, register an onBeforePaymentCreation hook that loads spent_so_far for this run_id, compares it to the run budget, and returns { abort: true, reason } when the next payment would break it. Persist the allow before you sign, or two concurrent workers can both pass the check.
• A policy service outside the agent (per_tx_max for the request, a daily or run-scoped total checked with a reference = run_id) keeps the numbers somewhere the model can't edit from chat history or a writable session file.

What can go wrong?

Only a per-request cap is set, and the agent burns the whole wallet on many small payments in one run.

• The run total lives in the agent's context window or a file it can write, so a prompt or tool call resets it.
• The cumulative store is in memory, and several worker processes each think they still have budget.
• spendControls: false was left on from debugging, or an older @x402/core without spendControls is pinned.