---
title: "Get a policy-gated account balance"
method: GET
path: "/accounts/{id}/balance"
tags: ["agent"]
---

# Get a policy-gated account balance

`GET /accounts/{id}/balance`

## Request

- Base URL: `https://api.catena.com/v1/agent-api`
- URL: `https://api.catena.com/v1/agent-api/accounts/{id}/balance`
- Auth: HTTP bearer

## Path parameters

- `id` string, required

## Response `200`

Account balance in USD at par across assets, with an optional breakdown by network and token

- object
  - `accountId` string, required
  - `balance` object, required: Deprecated alias of balances.total: USD at par across assets
    - `amount` string, required
    - `assetId` string, required
    - `asset_id` string, required
  - `balances` object, required
    - `total` object, required: USD at par across assets on every account network, including networks this agent may not use
      - `amount` string, required
      - `assetId` string, required
      - `asset_id` string, required
    - `available` object, required: Aggregate unreserved funds in USD at par across assets on the networks this agent may use, leaving out a network Catena has closed. For a network-split account, this equals the sum of byNetwork available values. It describes the account and does not determine whether a particular payment can be funded. Zero while the account is not active, and zero when no network the account holds is open to agents.
      - `amount` string, required
      - `assetId` string, required
      - `asset_id` string, required
    - `byNetwork` object[]: One entry for each network that the account holds and agents may use. Their available values add up to balances.available. Their total values can add up to less than balances.total, which also counts a network agents may not use. Every available is zero while the account is not active. A network Catena has closed keeps its entry, with status closed and available zero. An empty array means no network the account holds is open to agents. Absent until the account's money is split by network.
      - `network` string, required
      - `status` string, required: open while agents can spend on this network. closed while Catena has made the network temporarily unavailable: available is zero, total still counts the money there, which is safe, and payments already in progress complete. Treat any value other than open as a network you cannot spend on now
      - `total` object, required: USD at par across assets on this network
        - `amount` string, required
        - `assetId` string, required
        - `asset_id` string, required
      - `available` object, required
        - `amount` string, required
        - `assetId` string, required
        - `asset_id` string, required
    - `holdings` object[]: Optional breakdown by network and token, in USD at par across assets. When absent, every figure is USDC. Omitted for bank accounts and until the account's money is split by network. Only networks this agent may use are included. Available values sum to balances.available; total values sum to balances.total only when every account network is inside the agent network fence. Closed networks and inactive accounts have zero available, and retired wallets contribute to total alone.
      - `token` string, required: The token's CAIP-19 asset identifier
      - `network` string, required
      - `networkLabel` string, required
      - `asset` string, required
      - `assetLabel` string, required
      - `total` object, required
        - `amount` string, required
        - `assetId` string, required
        - `asset_id` string, required
      - `available` object, required
        - `amount` string, required
        - `assetId` string, required
        - `asset_id` string, required

## Other responses

- `403`: Account not accessible under this policy
- `404`: Readable account not found
- `409`: Refused: the agent's policy cannot be read (`policy_unreadable`) until an admin saves its full configuration or, for a temporary override, revokes it and grants a new one; nothing changed, and GET /policy shows it with `invalidReason`

---

[API](https://skmtc.dev/catena/apis/catena-agent-api.md) - [All operations](https://skmtc.dev/catena/apis/catena-agent-api/llms.txt) - [OpenAPI document](https://skmtc.dev/catena/apis/catena-agent-api/revisions/9b72e32d21f1?raw)