Documentation / New API reference / Accounts
Get Accounts Balances
Reference
Last reviewed 2026-11-06
It answers each address from what is stored, as of the newest marked tick or later:
- the address's newest
account_latest_v1row, when it is at or after the newest marked tick ([latest_balances_sql]); - for an address with none, or only an older one, the newest tick
accounts-v1has 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_v1at that tick (#1336, #1802), and left out ofdatawhen the tick does not hold it — where/v1/accounts/{address}answers 404.
- an ordinary address is looked up again (the marker is read first, as
in [
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
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.