---
title: "Read the current permission's remaining token and native limits"
method: GET
path: "/wallets/{address}/budget"
tags: ["Wallets"]
---

# Read the current permission's remaining token and native limits

`GET /wallets/{address}/budget`

## Request

- Base URL: `https://api.avaprotocol.org/api/v1`
- URL: `https://api.avaprotocol.org/api/v1/wallets/{address}/budget`
- Auth: HTTP bearer

User JWT only; partner assertions are refused. Works for workflow-sized
permissions too. Pending deferred installs report stored totals with
status pending. Active limits are read on chain; a failed remainder read
is 503, never a stored-value fallback. Retirement read failures appear
as unverified entries in an otherwise successful response.

## Path parameters

- `address` string, required: Lowercase or checksummed hex EOA / contract address.

## Query parameters

- `chainId` integer

## Response `200`

Current limits and retirement health

- WalletBudget
  - `chainId` integer, required: Numeric chain ID (e.g. 11155111 for Sepolia, 8453 for Base). On chain-aware trigger/node configs this is required and must be a configured chain; on query/filter params it is optional.
  - `policyId` string, required: ULID identifier (26-char Crockford base32).
  - `status` 'pending' | 'active', required
  - `sizing` 'workflow' | 'budget', required
  - `validUntil` integer, required
  - `startedAt` integer
  - `erc20` BudgetTokenRow[], required
    - `token` string, required: Lowercase or checksummed hex EOA / contract address.
    - `amount` string, required
    - `remaining` string, required
    - `used` string, required
    - `unlimited` boolean, required
  - `native` BudgetNativeRow
    - `amount` string, required
    - `remaining` string, required
    - `used` string, required
    - `unlimited` boolean, required
    - `gasWei` string: Recorded gas reserve inside amount. Omitted when the stored breakdown is unknown; never reconstructed.
  - `unmeteredPermissions` UnmeteredPermission[], required
    - `kind` 'aave_withdraw' | 'aave_borrow' | 'wrapped_native' | 'other', required
    - `target` string, required: Lowercase or checksummed hex EOA / contract address.
    - `selectors` string[], required
    - `token` string: Lowercase or checksummed hex EOA / contract address.
    - `added` boolean, required
  - `retirements` BudgetRetirement[]
    - `entityId` integer, required
    - `policyId` string: ULID identifier (26-char Crockford base32).
    - `state` 'registered' | 'residual' | 'unverified', required
    - `erc20` Erc20SpendCap[]: Remaining limits of an entity confirmed registered; absent otherwise.
      - `token` string, required: Lowercase or checksummed hex EOA / contract address.
      - `amount` string, required: Total cap in the token's smallest unit (decimal string, no reset).
    - `native` NativeSpendCap
      - `amount` string, required: Cumulative native-token cap in wei (decimal string, no reset). Enforced on-chain by NativeTokenLimitModule. Self-funded UserOps also decrement this cap by gas; sponsored UserOps decrement only the ETH value sent. When the chain does not sponsor gas, prepare sizes headroom for those UserOps into this amount: the steady-op ceiling times a per-chain fee assumption, plus one install. That headroom can also be sent as value to the allowed recipients.
  - `liveApprovals` LiveApproval[]: Reserved for approval discovery; omitted in this slice, not an assertion that no approvals exist.
    - `token` string, required: Lowercase or checksummed hex EOA / contract address.
    - `spender` string, required: Lowercase or checksummed hex EOA / contract address.
    - `amount` string, required
  - `pendingChange` object: Latest durable budget change. A rejected or reset-unverified change explains why runs remain paused.
    - `preparationId` string: ULID identifier (26-char Crockford base32).
    - `policyId` string, required: ULID identifier (26-char Crockford base32).
    - `state` 'prepared' | 'submitting' | 'submitted' | 'reverted' | 'rejected' | 'unsent' | 'superseded', required
    - `reason` string
  - `readAt` integer, required

## Other responses

- `400`: Request validation failed.
- `401`: Missing or invalid bearer token.
- `403`: Authenticated but not permitted.
- `404`: No current permission for this wallet and chain
- `409`: More than one current permission; authority is ambiguous
- `503`: BUDGET_READ_UNAVAILABLE — a remainder could not be read

## Changes

- **2026-11-04** `6b505ebcf3f7`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/avaprotocol/apis/ava-protocol-avs-api/changes/wallets/:address/budget/get.md)

---

[API](https://skmtc.dev/avaprotocol/apis/ava-protocol-avs-api.md) - [All operations](https://skmtc.dev/avaprotocol/apis/ava-protocol-avs-api/llms.txt) - [OpenAPI document](https://skmtc.dev/avaprotocol/apis/ava-protocol-avs-api/revisions/6b505ebcf3f7?raw)