# Get Accounts Balances

It answers each address from what is stored, as of the newest marked tick or later:

_Source: https://taostats.io/docs/new/accounts/get-accounts-balances_

_Last reviewed: 2026-11-06_

```http
GET https://api.taostats.io/v1/accounts/balances
```

Requires an API key in the `Authorization` header.

It answers each address from what is stored, as of the newest marked tick
or later:

1. the address's newest `account_latest_v1` row, when it is at or after the
   newest marked tick ([`latest_balances_sql`]);
2. for an address with none, or only an older one, the newest tick
   `accounts-v1` has marked complete is read once, and then
   - an ordinary address is looked up again (the marker is read first, as
     in [`unseen_account_detail`], so a tick that landed in between cannot
     produce a false zero) and, still with no row at or after that tick,
     gets the zero row at that tick (#1304, #1885);
   - a protocol account is read from `account_protocol_tick_v1` at that
     tick (#1336, #1802), and left out of `data` when the tick does not
     hold it — where `/v1/accounts/{address}` answers 404.

The marker is read only when some address has no row, and the protocol
table only when one of those is a protocol account.

A balance is up to one snapshot interval (five minutes) plus the 300 s
response cache old; the response description says so, because generated
SDK docs read only that.

## Try it

Try this request in the browser on the HTML version of this page, or use the code samples below.

### Code samples

**cURL**

```bash
curl -H "Authorization: <YOUR_API_KEY>" \
  "https://api.taostats.io/v1/accounts/balances"
```

**JavaScript**

```js
const response = await fetch('https://api.taostats.io/v1/accounts/balances', {
  headers: {
    Authorization: '<YOUR_API_KEY>',
  },
});
const data = await response.json();
```

**Python**

```python
import requests

response = requests.get(
    "https://api.taostats.io/v1/accounts/balances",
    headers={"Authorization": "<YOUR_API_KEY>"},
)
data = response.json()
```

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `address` | query | `string` | Yes | One account address or a comma-separated list of up to 200 (required), each SS58 or `0x`-prefixed 32-byte hex. Whitespace around an item is ignored. An empty list or item, an invalid address, more than 200 addresses, or one address given twice (in either spelling) is rejected with a 400. `data` follows the order of this list. |

## Responses

### `200` — The newest stored balances of each listed account, read from the account snapshot, never the chain. How old: the snapshot is rewritten every five minutes, and the response cache keeps an answer for up to 300 seconds more, so a balance can be about ten minutes old in healthy operation. Read each item's `timestamp` for the time its balances are true at. One item per address, in request order; match items to addresses by `address`, not by position. A valid address that is not in the newest completed snapshot (never seen, or dropped out because it no longer holds anything) gets a zero row at that snapshot. A protocol account is read from that snapshot's protocol rows and is left out when the snapshot does not hold it

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | `array` | Yes |  |
| `data[].address` | `string` | Yes | SS58 address. |
| `data[].balance_free` | `string` | Yes | Free balance (RAO, u64 as string). |
| `data[].balance_reserved` | `string` | Yes | Reserved balance (RAO, u64 as string). |
| `data[].balance_staked` | `string` | Yes | Total staked, root and alpha valued as TAO (RAO, u64 as string). |
| `data[].balance_total` | `string` | Yes | Total balance (RAO, u64 as string). |
| `data[].block_number` | `integer (int32)` | Yes | Block of the snapshot tick the balances are from. |
| `data[].timestamp` | `string` | Yes | ISO 8601 timestamp of that tick, e.g. `"2026-06-13T09:10:00.000Z"`. |

### `400` — Missing, empty, too long, duplicated or invalid address list

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `message` | `string` | Yes | Plain-english message describing the failure from the caller's perspective. |
| `status_code` | `integer (int32)` | Yes | HTTP status code (mirrored in the response status line for convenience). |

### `500` — Internal server error

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `message` | `string` | Yes | Plain-english message describing the failure from the caller's perspective. |
| `status_code` | `integer (int32)` | Yes | HTTP status code (mirrored in the response status line for convenience). |

Every request needs an `Authorization` header holding your API key — see [Getting started with the Taostats API](https://taostats.io/docs/start-here/getting-started-with-taostats-api).