# Balances

> Read your prepaid wallet balances programmatically — one row per currency, in the same ten-thousandths unit as charge.

Accounts are prepaid: every send places a hold, and a send your balance will not cover is
rejected outright — never half-delivered. A **balance** is what you hold in one currency;
the account carries one row per currency.

## The balance object

### Attributes

- **`id`** (`string (uuid)`)
  Balance row id.

- **`amount`** (`integer`)
  What you hold, in ten-thousandths of `currency` — the same unit as `charge`
  (`10000` == 1.00, so `1250000` == 125.00).

- **`currency`** (`string`)
  Currency of `amount`.

Rows may carry additional fields (`type`, `active`); treat anything beyond the three above
as informational.

```json [Balance]
{
  "id": "5b1c8f2e-3d47-4a09-9c6b-2e8f1a7d4c5e",
  "amount": 1250000,
  "currency": "USD"
}
```

## List balances

`GET /api/v1/accounts/{id}/balances`

Reads the account's balances, one row per currency, with the same API key as everything
else. Check it before a [bulk send](/api/sms#send-bulk-sms) rather than discovering
`422 insufficient balance` mid-launch.

This is the endpoint behind the hosted MCP server's `get_balance` tool — see
[AI agents](/guides/mcp).

### Path parameters

- **`id`** (`string (uuid)`, required)
  Your account id. It is on the [key create response](/api/api-tokens#create-an-api-key) as
  `account_id`, and on every row of the key listing as `AccountId`.

### Response

Enveloped: `data` is an array of [balance objects](#the-balance-object).

### Errors

| Status | When |
| --- | --- |
| `401` | Missing, malformed, or revoked API key. |

```bash [cURL]
curl https://api.sendai.co.zw/api/v1/accounts/2d6f4b8e-1a90-4e21-8b7d-3f1a5c2e9a0c/balances \
  -H "Authorization: Bearer $SENDAI_API_KEY"
```

```js [Node.js]
const accountId = '2d6f4b8e-1a90-4e21-8b7d-3f1a5c2e9a0c'

const res = await fetch(
  `https://api.sendai.co.zw/api/v1/accounts/${accountId}/balances`,
  { headers: { 'Authorization': `Bearer ${process.env.SENDAI_API_KEY}` } },
)

const { data: balances } = await res.json()
// amount is in ten-thousandths: 1250000 == 125.00
```

```python [Python]
import os
import requests

account_id = "2d6f4b8e-1a90-4e21-8b7d-3f1a5c2e9a0c"

res = requests.get(
    f"https://api.sendai.co.zw/api/v1/accounts/{account_id}/balances",
    headers={"Authorization": f"Bearer {os.environ['SENDAI_API_KEY']}"},
)

balances = res.json()["data"]
# amount is in ten-thousandths: 1250000 == 125.00
```

```json [200 OK]
{
  "status": "success",
  "message": "request successful",
  "data": [
    {
      "id": "5b1c8f2e-3d47-4a09-9c6b-2e8f1a7d4c5e",
      "amount": 1250000,
      "currency": "USD"
    }
  ]
}
```