# Spend governance

Spend governance is Ozma's **trust layer for autonomous agents**. Each API key can carry independent caps stored in Postgres and enforced synchronously on the gateway **before** upstream calls or billing.

## Cap fields

| Field | Purpose |
|-------|---------|
| `budget_cents` | Lifetime spend ceiling |
| `daily_cap_cents` | Maximum spend per UTC calendar day |
| `per_call_max_cents` | Block individual calls above a price |
| `spent_cents` / `daily_spent_cents` | Running totals (updated on success) |

Unset caps mean unlimited for that dimension. The gateway SpendCounter Durable Object is authoritative for daily enforcement; counters rotate at UTC midnight.

## Enforcement behavior

On each proxy call the gateway reserves spend, calls upstream, then commits or refunds:

1. Exceeds per-call max → `per_call_limit_exceeded` (402)
2. Exceeds lifetime budget → `insufficient_budget` (402)
3. Exceeds daily cap → `daily_cap_exceeded` (402)
4. Upstream failure → reservation refunded; **no charge**

Metering to Stripe runs asynchronously after success.

## Surfaces

Set caps via dashboard, `PATCH /v1/keys/:id`, CLI `ozma budget set` (flags: `--budget`, `--daily-cap`, `--per-call-max`), or MCP `set_budget`.

`approval_mode` is accepted by API/CLI but **not enforced** yet — do not rely on it until implemented.

## Why it matters

Delegating an API key to an agent without caps exposes your full org wallet. Per-key budgets let you run autonomous loops with predictable maximum loss — complementary to org-level billing limits and free-tier catalog APIs.

## Learn more

- [Keys & budgets guide](/docs/guides/keys-and-budgets)
- [Troubleshooting daily cap vs budget](/docs/guides/troubleshooting)