# Budgets for AI agents

> Give an AI agent a budget it cannot raise. Per-request caps, daily and monthly windows, per-seller budgets, an allowlist and a human approval above a threshold, in one policy file enforced outside the agent.

Source: https://spendctl.dev/docs/agent-budgets/ (spendctl documentation; index of all pages at https://spendctl.dev/llms.txt)

**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

| 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

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

```yaml
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](https://spendctl.dev/docs/policy/).

## Run it

```bash
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:

```bash
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](https://spendctl.dev/docs/integrations/).

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

```json
{
  "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:

```json
{
  "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](https://spendctl.dev/docs/approvals/) has the details.

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

```yaml
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
```

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

```yaml
payTo:
  "api.weather.dev":
    addresses: ["0x209693Bc6afc0C5328bA36FaF03C514EF312287C"]
    networks: ["eip155:8453"]
    assets: ["USDC"]
```

## 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

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](https://spendctl.dev/docs/spend-controls-compared/) puts them side by side.

## Next

- [Quickstart](https://spendctl.dev/docs/quickstart/): the same policy, run end to end in five minutes.
- [Policy reference](https://spendctl.dev/docs/policy/): every key, and the order they are evaluated in.
- [Ledger and reconciliation](https://spendctl.dev/docs/ledger/): what each row means and how to export it.
