How do I set a spending cap for an AI agent that pays with x402?

What should I check, step by step?

1. Keep the x402 client's spend controls on. Don't pass spendControls: false (Go: DisableSpendControls(), Python: spend_controls=False). That turns off every cap and allows any asset.

2. Set the per-payment cap you mean: maxAmountPerPayment ("$1" by default) for USD-pegged assets, and an allowedAssets list with an atomic-unit cap for any other token (for 6-decimal USDC, "2000000" is 2 USDC).
3. Add a cap over time. The base client checks each payment on its own. Use the CDP SDK's maxCumulativeSpend and maxCumulativeSpendWindow, or a registered policy or onBeforePaymentCreation hook that keeps a running total.
4. Keep that running total in persistent storage. The CDP SDK's default spend store is in memory and resets when the process restarts.
5. Limit where the agent can pay: allowed networks (for example only eip155:8453 for Base mainnet), allowed assets and, in your own policy, allowed payTo addresses or domains.
6. Treat upto prices as the most you'll pay: the buyer signs for the maximum and the seller settles for the actual amount, so cap the maximum, not the expected charge.
7. Fund a separate agent wallet with only the budget and top it up on a schedule. If you use CDP Server Wallets, add a Policy Engine reject rule at the signing layer as well.
8. Log every payment and every refusal with amount, asset, network and payTo, and alert before the limit is reached (the CDP SDK has an onApproachingLimit callback).

What the x402 client caps by default

The x402 buyer quickstart says that by default the client only pays recognized USD-pegged assets (e.g. USDC) and caps each payment at $1. maxAmountPerPayment changes the USD cap; allowedAssets opts into other tokens with an optional per-payment cap in atomic units; spendControls: false disables all of it.

• Spend controls run before any custom policies and before the payment is signed. If every payment option the server offers is over the cap or in an asset you didn't allow, the client refuses to pay and throws an error instead of picking one anyway.
• In the x402 TypeScript source, spendControls arrived in @x402/core 2.25.0. If your agent pins an older version, there is no default cap. Check the installed version.
• For the upto scheme the amount in the 402 response is the maximum. The buyer signs once for it and the seller may settle for less, so a per-payment cap applies to that maximum.

Caps over a day or a session

A per-payment cap doesn't stop 1,000 payments of $0.99. You need a running total.

• The CDP SDK's x402 client (CdpX402Client) takes spendControls with maxAmountPerPayment, maxCumulativeSpend, maxCumulativeSpendWindow (for example "24h"), allowedNetworks and an onApproachingLimit callback, and raises a SpendControlError when a payment would break a limit. applySpendControls(client, controls) adds the same checks to any @x402/core client.
• Its docs say the default SpendStore is in memory and process-local. Give it a persistent store if the total must survive restarts, or a crash-and-restart loop resets the budget.
• Without the CDP SDK, register a policy on the x402 client or an onBeforePaymentCreation hook. The hook can return { abort: true, reason } to stop a payment, and the x402 lifecycle-hooks docs show a spending-limit example. The x402 MCP client takes the same policies and an onPaymentRequested hook for paid MCP tools.

Why the wallet is the real ceiling

Every cap above is code in the agent's own process. A bug, an old version, or a different client using the same key can skip it. The amount a key can spend is what its wallet holds, so keep the agent's wallet small and refill it on a schedule rather than pointing it at a treasury.

• Approvals are not budgets. When a payment uses Permit2, the x402 SDK's helper approves the maximum uint256 to the Permit2 contract (its source says it always approves MaxUint256 regardless of the payment amount), so that token allowance doesn't limit anything; each payment is still signed separately.
• With CDP Server Wallets, the Policy Engine evaluates accept and reject rules before signing (reject wins) and can be scoped to the project or one account. Rules can cover operations such as signEvmTransaction and signEvmTypedData, so a limit there applies even if the agent's own code is wrong.

What can go wrong?

Someone sets spendControls: false while debugging and ships it.

• The cap is in dollars, but the seller asks for a token you allowed through allowedAssets with a cap in the wrong atomic units (USDC has 6 decimals, so "2000000" is 2 USDC, not 2,000,000).
• The running total lives in memory and resets on every restart or across several worker processes.
• The agent's key is also used by another script that has no caps at all.