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

# Get Budget

> The agent's spend budget and live utilization for the current UTC day

Returns the configured caps plus what has been spent so far today. Spend is **wallet outflow**: gross receipt totals net of any credits applied, with failed settlements excluded. `spent_today_usdc` is reported even for agents with no budget, so a dashboard can show utilization either way.

## Authentication

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

<RequestExample>
  ```bash cURL theme={null}
  # x-agent-proof is an EIP-712 signature by the X-Agent-ID wallet —
  # the SDKs produce it for you; see /sdk/overview#read-authentication
  curl "https://win.oneshotagent.com/v1/agents/me/budgets" \
    -H "X-Agent-ID: 0xYourWalletAddress" \
    -H "x-agent-proof: <base64 signed proof, scope=read>"
  ```

  ```typescript TypeScript theme={null}
  const status = await agent.budgets();
  console.log(`${status.spent_today_usdc} of ${status.daily_usdc} spent, resets ${status.resets_at}`);
  ```

  ```python Python theme={null}
  status = client.get_budgets()
  print(f"{status['spent_today_usdc']} of {status['daily_usdc']} spent")
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "data": {
      "daily_usdc": 50,
      "per_transaction_usdc": 5,
      "alert_at": 0.8,
      "pause_at": 1,
      "spent_today_usdc": "41.200000",
      "remaining_usdc": "8.800000",
      "pct_used": 0.824,
      "resets_at": "2026-08-24T00:00:00.000Z"
    }
  }
  ```
</ResponseExample>

## Response

<ResponseField name="data.daily_usdc" type="number | null">Daily cap in USDC. `null` = unlimited.</ResponseField>
<ResponseField name="data.per_transaction_usdc" type="number | null">Per-call cap in USDC. `null` = unlimited.</ResponseField>
<ResponseField name="data.alert_at" type="number | null">Fraction of `daily_usdc` that triggers a `budget_warning`.</ResponseField>
<ResponseField name="data.pause_at" type="number | null">Fraction of `daily_usdc` at which paid calls are rejected.</ResponseField>
<ResponseField name="data.spent_today_usdc" type="string">Wallet outflow so far this UTC day.</ResponseField>
<ResponseField name="data.remaining_usdc" type="string | null">`daily_usdc × pause_at − spent`. `null` when there is no daily cap.</ResponseField>
<ResponseField name="data.pct_used" type="number | null">`spent / daily_usdc`. `null` when there is no daily cap.</ResponseField>
<ResponseField name="data.resets_at" type="string">ISO timestamp of the next UTC midnight, when the daily window resets.</ResponseField>