Spend budgets

Agents can run up cost fast. Spend budgets cap it: set a limit per tenant or per agent, over a daily or monthly window, with throttle and kill thresholds enforced before each action runs.

How enforcement works

Each governed action charges a cost (DEFAULT_ACTION_COST_CENTS, see Deployment) against the matching budgets in an atomic check-and-charge:

• At the throttle threshold (default 85%), the action is slowed/flagged.
• At the kill threshold (default 95%), the next action is blocked with HTTP 429.

Budgets activate only when a per-action cost and a budget are configured.

Manage budgets

All routes are under /api/v1/cost (JWT; canManageBilling for writes).

Create a budget

curl -X POST https://your-host/api/v1/cost/budgets \
  -H "Authorization: Bearer <JWT>" -H "Content-Type: application/json" \
  -d '{
    "scope": "agent",
    "period": "daily",
    "actor": "did:nolixan:…",
    "environment_id": 1,
    "limit_cents": 5000,
    "throttle_pct": 85,
    "kill_pct": 95,
    "enabled": true
  }'

• scope — tenant (whole account) or agent (a specific actor/DID).
• period — daily or monthly.
• limit_cents — the budget in cents.

On top of hard limits, the governor runs z-score cost-anomaly detection over a rolling window to catch unusual spend even below the limit. This control maps to OWASP Agentic ASI-05 (runaway cost) — see Compliance.