> ## 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.

# Set Budget

> Set, adjust, or clear the agent's spend budget

Upserts the agent's budget. Takes effect on the next paid call.

Every field is **tri-state**: an absent key leaves the stored value alone, an explicit `null` clears it, a value sets it. A partial update — "just raise my daily" — never wipes the caps it didn't mention. For `alert_at` and `pause_at`, which always have a value, `null` resets to the default (`0.8` / `1.0`).

## Authentication

`X-Agent-ID` plus a signed `x-agent-proof` with `scope: "write"` — **required**. See [Spend Budgets](/api-reference/budgets/overview#authentication).

<Note>
  You rarely call this directly. Pass `budgets` when constructing the SDK client and it syncs once, before the first paid call — including for a brand-new wallet that has never made a call (the endpoint registers it). If that sync fails, the SDK refuses the paid call (`BudgetSyncError`) rather than run without the guardrail.
</Note>

## Body

<ParamField body="daily" type="number | null">Max USDC per UTC day. Must be `> 0`, or `null` to clear.</ParamField>
<ParamField body="per_transaction" type="number | null">Max USDC for any single call. Must be `> 0`, or `null` to clear.</ParamField>
<ParamField body="alert_at" type="number | null" default="0.8">Fraction of `daily` in `(0, 1]` that fires a `budget_warning` notification. `null` resets to `0.8`.</ParamField>
<ParamField body="pause_at" type="number | null" default="1.0">Fraction of `daily` in `(0, 1]` at which paid calls are rejected with `403 budget_exceeded`. `null` resets to `1.0`.</ParamField>
<ParamField body="alert_email" type="string | null">Email for budget alerts, in addition to in-app notifications. `null` to clear.</ParamField>

Strings that are only numeric by prefix (`"5oops"`) are rejected with `400 invalid_budget`.

<RequestExample>
  ```bash cURL theme={null}
  curl -X PUT "https://win.oneshotagent.com/v1/agents/me/budgets" \
    -H "X-Agent-ID: 0xYourWalletAddress" \
    -H "x-agent-proof: <base64 signed proof, scope=write>" \
    -H "Content-Type: application/json" \
    -d '{"daily": 50, "per_transaction": 5, "alert_at": 0.8, "alert_email": "you@example.com"}'
  ```

  ```typescript TypeScript theme={null}
  const agent = await OneShot.create({
    cdp: true,
    budgets: { daily: 50, perTransaction: 5, alertAt: 0.8, pauseAt: 1.0 },
    alerts: { email: "you@example.com" },
  });
  ```

  ```python Python theme={null}
  client = OneShotClient(
      "0x...",
      budgets={"daily": 50, "per_transaction": 5, "alert_at": 0.8},
      alert_email="you@example.com",
  )
  ```

  ```bash Clear the daily cap theme={null}
  curl -X PUT "https://win.oneshotagent.com/v1/agents/me/budgets" \
    -H "X-Agent-ID: 0x..." -H "x-agent-proof: <proof>" \
    -H "Content-Type: application/json" \
    -d '{"daily": null}'
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "data": {
      "daily_usdc": 50,
      "per_transaction_usdc": 5,
      "alert_at": 0.8,
      "pause_at": 1
    }
  }
  ```
</ResponseExample>

## Errors

| Status | `error`                     | Meaning                                                  |
| ------ | --------------------------- | -------------------------------------------------------- |
| `400`  | `invalid_budget`            | A field is out of range or not numeric                   |
| `401`  | `proof_required`            | Missing or invalid `x-agent-proof`                       |
| `500`  | `alert_email_update_failed` | Budget row saved, but `alert_email` could not be — retry |