Spend governance
Key budgets, daily caps, per-call limits, and gateway enforcement.
View as Markdown →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:
- Exceeds per-call max →
per_call_limit_exceeded(402) - Exceeds lifetime budget →
insufficient_budget(402) - Exceeds daily cap →
daily_cap_exceeded(402) - 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.