> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oneshotagent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Spend Budgets

> Per-agent daily and per-call spend caps, enforced server-side before any payment is signed

A **spend budget** caps what an agent can spend so a runaway loop can't drain the wallet overnight. It is enforced **server-side against the receipt ledger**, so the cap is a true per-agent total across every process, restart, and serverless invocation using the same wallet — not a per-instance counter.

```
daily            max USDC per UTC day
per_transaction  max USDC for any single call
alert_at         fraction of daily that fires a budget_warning notification   (default 0.8)
pause_at         fraction of daily at which paid calls are rejected           (default 1.0)
```

An agent with **no budget configured is unlimited** — nothing changes until you opt in.

## How it differs from `maxCost`

|                         | `maxCost` / `X-Max-Cost-USDC` | Spend budget                             |
| ----------------------- | ----------------------------- | ---------------------------------------- |
| Scope                   | One call                      | Cumulative, per UTC day (+ per-call cap) |
| Where it lives          | Request header / SDK option   | Stored per agent, enforced by the API    |
| Survives restarts       | No                            | Yes                                      |
| Shared across processes | No                            | Yes                                      |
| Rejection               | `400 exceeds_caller_budget`   | `403 budget_exceeded`                    |

Use both: `maxCost` is a per-call sanity check; the budget is the guardrail.

## Enforcement

Every paid route checks the budget **before** any payment is signed or settled:

* **Quote-based routes** (email, voice, SMS, build, browser, commerce, compute) reject at quote time — you get the `403` instead of the `402` quote, so nothing is signed.
* **Fixed-price routes** reject in the payment middleware, before settlement.
* Concurrent calls are safe: on the paid leg the check and the in-flight reservation are one atomic Redis operation, so two parallel calls can't both squeeze under the cap. The reservation is released once the receipt lands. If Redis is unavailable the guard degrades to a best-effort ledger check (fails open) rather than blocking payments.
* Calls fully covered by credits don't consume budget. Failed settlements don't count as spend.

The rejection is a **403, not a 402**, because retrying cannot succeed until the window resets or the budget is raised:

```json theme={null}
{
  "error": "budget_exceeded",
  "message": "Charge $0.500000 would take today's spend to $50.200000, over the daily budget of $50.00. Budget resets at 2026-08-24T00:00:00.000Z.",
  "budget": {
    "reason": "daily",
    "cap": "50.000000",
    "spent": "49.700000",
    "in_flight": "0.000000",
    "charge": "0.500000",
    "resets_at": "2026-08-24T00:00:00.000Z"
  }
}
```

`reason` is `daily` or `per_transaction`. The SDKs raise a typed `BudgetExceededError` carrying these fields.

## Alerts

At `alert_at` the agent gets a `budget_warning` notification; when a call is blocked it gets `budget_exceeded`. Both land in [notifications](/api-reference/notifications/list) — the agent itself can read them — and, if an `alert_email` is set, by email. Each fires at most once per UTC day.

## Authentication

Both budget endpoints identify the agent by `X-Agent-ID` **and require** a signed `x-agent-proof` ([read proof](/sdk/overview#read-authentication)) — `scope: "read"` for `GET`, `scope: "write"` for `PUT`. Unlike the inbox and notification reads, this is not log-only: a budget write under a spoofed public wallet address could halt another agent's paid calls, so unsigned requests are rejected outright.

The SDKs sign this automatically (TypeScript ≥ 0.27.0, Python ≥ 0.20.0) and sync a `budgets` config once, before the first paid call.

## Endpoints

| Method | Path                    | Description                                                  |
| ------ | ----------------------- | ------------------------------------------------------------ |
| `GET`  | `/v1/agents/me/budgets` | [Budget and today's utilization](/api-reference/budgets/get) |
| `PUT`  | `/v1/agents/me/budgets` | [Set or clear the budget](/api-reference/budgets/set)        |