Budgets for AI agents
In short: a spending limit only holds if the agent cannot reach it. Put the limit in a process the agent talks to over HTTP, not in the prompt and not in the agent’s own code, and make it answer five questions: how much per call, how much per day or month, to whom, what happens at the limit, and what record is left. With spendctl that is one YAML file and a sidecar.
The five questions
Section titled “The five questions”| Question | Policy key | Example |
|---|---|---|
| How much may one call cost? | budget.perRequest |
"0.05" |
| How much in a window? | budget.hourly / daily / weekly / monthly |
daily: "5.00" |
| Whom may the agent pay? | allow, deny, payTo |
one host, one recipient address |
| What happens at the limit? | onBudgetExceeded, requireApprovalAbove |
refuse, or hold for a human |
| What record is left? | the ledger | a row for every attempt, paid or refused |
A cap on a single payment answers only the first. The others are where agents lose money in practice: many small payments, a seller the task never needed, a retry that pays twice, a price that creeps up.
A complete policy
Section titled “A complete policy”npx spendctl init writes this file (comments shortened). Everything in it is enforced by the sidecar, in a separate process from the agent:
version: 1signer: type: mock # mock money; `spendctl init --signer cdp` for a real wallet
approvals: timeout: 10m # an unanswered approval is denied hold: true # keep the agent's request open while a human decides
defaults: networks: ["eip155:84532"] # Base Sepolia only assets: ["USDC"] priceJumpFactor: 3 # a price more than 3x the last one paid needs a human firstPaymentMax: "0.05" # a first payment to a new recipient above this needs a human
agents: researcher: budget: perRequest: "0.05" daily: "0.03" monthly: "20.00" onBudgetExceeded: approve # deny | approve requireApprovalAbove: "0.50" allow: - "localhost:4021" # the mock weather API - "localhost:4022" # the mock search APIAmounts are USD strings. Windows are rolling (1 hour, 24 hours, 7 days, 30 days) and count what is reserved, settled and not yet confirmed, so two requests in flight cannot both spend the last cent. Every key is on the Policy reference.
Run it
Section titled “Run it”npx spendctl initnpx spendctl mock # terminal 1: a mock facilitator and two paid APIsnpx spendctl start # terminal 2: the sidecar on 127.0.0.1:8402The agent sends requests through the sidecar. From any language that is a URL prefix and one header:
curl -H "X-Spendctl-Agent: researcher" "http://127.0.0.1:8402/http://localhost:4021/weather?city=Tokyo"A paid call comes back as the seller’s own response, with three headers added:
HTTP/1.1 200 OKx-spendctl-amount: $0.01x-spendctl-attempt: pay_mwefbsts9e649hx-spendctl-decision: settled
{"city":"Tokyo","condition":"sunny","temperatureC":18}TypeScript, Python and MCP clients are on Integrations.
What the agent sees at the limit
Section titled “What the agent sees at the limit”A refusal is a 402 with a sentence the model can read and a reason code your code can branch on. A host that is not on the allowlist:
{ "error": "spendctl_denied", "message": "spendctl refused a payment to localhost:4022/search: localhost:4022 is not on the allowlist for agent researcher.", "attempt": "pay_mwefc8mvqwn3d4", "decision": "deny", "reasons": [ { "code": "domain_not_allowed", "message": "localhost:4022 is not on the allowlist for agent researcher." } ]}With onBudgetExceeded: approve, a call that would cross the daily budget is not refused. It is held for a human, and nothing is signed while it waits. In retry mode (approvals.hold: false) the agent gets the approval id at once:
{ "error": "spendctl_approval_required", "message": "spendctl needs a human to approve $0.01 to localhost:4021/weather: $0.01 would exceed the daily budget of $0.02 for agent researcher ($0.02 already spent).", "decision": "approve", "amount": "$0.01", "reasons": [{ "code": "daily_exceeded", "message": "…" }], "approval": "apr_mwefc8s25ehf4t", "approvalExpiresAt": "2026-11-13T03:45:36.818Z", "hint": "Ask a human to run `spendctl approve apr_mwefc8s25ehf4t`, then retry with header X-Spendctl-Approval: apr_mwefc8s25ehf4t."}A human decides with spendctl approve, the dashboard, or a link sent to Slack or Discord by webhook. The agent cannot: every decision needs an admin token the agent never sees. Approvals has the details.
A budget per seller
Section titled “A budget per seller”An agent budget says how much the agent may spend in total. endpointBudget says how much of that one seller may take, which catches a price that rises a little at a time:
agents: researcher: budget: { perRequest: "0.05", daily: "5.00" } endpointBudget: "api.weather.dev": { daily: "1.00" } "api.search.dev/v1/*": { hourly: "0.50", daily: "2.00" } onBudgetExceeded: approvePin the recipient
Section titled “Pin the recipient”The 402 names who gets paid. Pin it, and a seller, or anyone who can answer in its place, cannot swap the address, the chain or the token:
payTo: "api.weather.dev": addresses: ["0x209693Bc6afc0C5328bA36FaF03C514EF312287C"] networks: ["eip155:8453"] assets: ["USDC"]Start in dry-run
Section titled “Start in dry-run”Set mode: dry-run on an agent, or start the sidecar with spendctl start --dry-run, and point real traffic at it. Nothing is signed; the ledger shows what would have been paid and what would have been refused. Tighten the policy until the refusals are the ones you want, then switch to enforce.
Caps exist elsewhere. What they leave open
Section titled “Caps exist elsewhere. What they leave open”Use the limits your tools already have. Each one covers a part:
@x402/core’sspendControlscaps a single payment (default$1), inside the agent’s process.- The CDP SDK’s x402 spend controls add rolling caps, also in-process, with an in-memory store by default.
- Wallet policy engines see the keys they hold; hosted agent-payment platforms govern the wallet they hold.
What is left is one policy, one approval flow and one ledger in front of whichever wallet and protocol the agent meets, in a place the agent cannot edit. Where spend controls can live puts them side by side.
- Quickstart: the same policy, run end to end in five minutes.
- Policy reference: every key, and the order they are evaluated in.
- Ledger and reconciliation: what each row means and how to export it.