Skip to content

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.

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.

npx spendctl init writes this file (comments shortened). Everything in it is enforced by the sidecar, in a separate process from the agent:

version: 1
signer:
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 API

Amounts 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.

Terminal window
npx spendctl init
npx spendctl mock # terminal 1: a mock facilitator and two paid APIs
npx spendctl start # terminal 2: the sidecar on 127.0.0.1:8402

The agent sends requests through the sidecar. From any language that is a URL prefix and one header:

Terminal window
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 OK
x-spendctl-amount: $0.01
x-spendctl-attempt: pay_mwefbsts9e649h
x-spendctl-decision: settled
{"city":"Tokyo","condition":"sunny","temperatureC":18}

TypeScript, Python and MCP clients are on Integrations.

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.

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: approve

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"]

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’s spendControls caps 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.