---
title: "Set spending caps"
method: PUT
path: "/v1/budget"
tags: ["budget"]
---

# Set spending caps

`PUT /v1/budget`

## Request

- Base URL: `https://agentlair.dev`
- URL: `https://agentlair.dev/v1/budget`
- Auth: HTTP bearer

Set or update per-period spending caps for the authenticated account.
At least one of `caps`, `on_limit`, or `single_tx_limit_cents` must be provided.
Cap amounts are in atomic USDC units (1,000,000 = 1.00 USDC).
Ordering constraint: daily ≤ weekly ≤ monthly.

**Flat format supported:** You can pass `daily`, `weekly`, `monthly` at the top level without wrapping in a `caps` object:
```json
{"daily": 10000000, "on_limit": "approve"}
```

**on_limit=approve:** When set, charges exceeding the cap return HTTP 202 with an `approval_id` instead of 402.
The principal can then approve or reject via `POST /v1/approvals/{id}/approve` or `/reject`.

## Request body

- object
  - `daily` integer, nullable: Daily cap in atomic USDC units (flat format). Alternative to caps.daily.
  - `weekly` integer, nullable: Weekly cap in atomic USDC units (flat format). Alternative to caps.weekly.
  - `monthly` integer, nullable: Monthly cap in atomic USDC units (flat format). Alternative to caps.monthly.
  - `caps` object: Per-period cap amounts (nested format). Pass null for a period to remove that cap.
    - `daily` integer, nullable
    - `weekly` integer, nullable
    - `monthly` integer, nullable
  - `on_limit` 'reject' | 'approve': Action when spending cap is reached. 'reject' (default) returns 402; 'approve' returns 202 with an approval_id for the principal to act on.
  - `single_tx_limit_cents` integer, nullable: Maximum allowed single-transaction amount in atomic USDC units. Null to remove. Charges above this limit trigger the approval flow even if within period budget.

## Response `200`

Updated spending caps

- object
  - `ok` boolean
  - `agent_id` string
  - `caps` object: Updated cap state for each modified period
  - `settings` object
    - `on_limit` 'reject' | 'approve'
    - `single_tx_limit_cents` integer, nullable

## Other responses

- `400`: Invalid request
- `401`: Unauthorized

---

[API](https://skmtc.dev/agentlair/apis/agentlair-api.md) · [All operations](https://skmtc.dev/agentlair/apis/agentlair-api/llms.txt) · [OpenAPI document](https://skmtc.dev/agentlair/apis/agentlair-api/revisions/fac95ff4995d?raw)