# Get a balance

> Get a policy-gated account balance.

`GET /v1/agent-api/accounts/{id}/balance`

## Path parameters

| Field | Type   | Required | Description |
| ----- | ------ | -------- | ----------- |
| `id`  | string | Yes      |             |

## Responses

| Status | Description                                                                                  |
| ------ | -------------------------------------------------------------------------------------------- |
| `200`  | Account balance in USD at par across assets, with an optional breakdown by network and token |
| `403`  | Account not accessible under this policy                                                     |
| `404`  | Readable account not found                                                                   |

## Response fields

| Field                | Type            | Required | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| -------------------- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `accountId`          | string          | Yes      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `balance`            | money           | Yes      | Deprecated alias of balances.total: USD at par across assets                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `balances`           | object          | Yes      |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `balances.total`     | money           | Yes      | USD at par across assets on every account network, including networks this agent may not use                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `balances.available` | money           | Yes      | 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.                                                                                           |
| `balances.byNetwork` | array of 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. |
| `balances.holdings`  | array of 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.              |

## Example

### SDK

```ts
import { createCatenaClient } from "@catena/sdk"

// Reads CATENA_SECRET_KEY
const client = createCatenaClient()

const balance = await client.getAccountBalance(
  "acct_01JC2Y6ZQ8R4M7N9P3S5T6V8WX",
)
```

### CLI

```sh
catena accounts balance acct_01JC2Y6ZQ8R4M7N9P3S5T6V8WX
```

### Response `200`

```json
{
  "accountId": "acct_01JC2Y6ZQ8R4M7N9P3S5T6V8WX",
  "balance": {
    "amount": "15025.500000",
    "assetId": "USD",
    "asset_id": "USD"
  },
  "balances": {
    "total": {
      "amount": "15025.500000",
      "assetId": "USD",
      "asset_id": "USD"
    },
    "available": {
      "amount": "11025.500000",
      "assetId": "USD",
      "asset_id": "USD"
    },
    "byNetwork": [
      {
        "network": "base",
        "status": "open",
        "total": {
          "amount": "15000.000000",
          "assetId": "USD",
          "asset_id": "USD"
        },
        "available": {
          "amount": "11000.000000",
          "assetId": "USD",
          "asset_id": "USD"
        }
      },
      {
        "network": "arc",
        "status": "open",
        "total": {
          "amount": "25.500000",
          "assetId": "USD",
          "asset_id": "USD"
        },
        "available": {
          "amount": "25.500000",
          "assetId": "USD",
          "asset_id": "USD"
        }
      }
    ]
  }
}
```