Documentation / API reference / Account
Get Account History
Reference
Last reviewed 2026-09-18
Gives most recent coldkey balance (from the database)
Try it
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
address | query | string | Yes | SS58 or hex format |
network | query | string | finney, nakamoto, kusanagi | |
block_start | query | integer (int32) | Start of block range (inclusive) | |
block_end | query | integer (int32) | End of block range (inclusive) | |
timestamp_start | query | integer (int64) | Start of timestamp range in Unix timestamp (seconds since 1970-01-01) (inclusive) | |
timestamp_end | query | integer (int64) | End of timestamp range in Unix timestamp (seconds since 1970-01-01) (inclusive) | |
page | query | integer (int32) | Page of entries to retrieve. | |
limit | query | integer (int32) | Number of entries to return. Max value is 200. | |
order | query | string | One of block_number_asc, block_number_desc, timestamp_asc, timestamp_desc. |
Responses
200 — Account history retrieved successfully
| Field | Type | Required | Description |
|---|---|---|---|
data | array | Yes | |
data[].address | object | Yes | |
data[].address.hex | string | Yes | The hex format of the hot key |
data[].address.ss58 | string | Yes | The SS58 format of the hot key |
data[].balance_free | integer (int64) | Yes | |
data[].balance_liquidity | integer (int64) | Yes | |
data[].balance_reserved | integer (int64) | Yes | |
data[].balance_staked | integer (int64) | Yes | |
data[].balance_staked_alpha_as_tao | integer (int64) | Yes | |
data[].balance_staked_root | integer (int64) | Yes | |
data[].balance_total | integer (int64) | Yes | |
data[].block_number | integer (int32) | Yes | |
data[].coldkey_swap | object, nullable | ||
data[].coldkey_swap.block_number | integer (int32) | Yes | |
data[].coldkey_swap.network | string | Yes | |
data[].coldkey_swap.new_coldkey | object | Yes | |
data[].coldkey_swap.new_coldkey.hex | string | Yes | The hex format of the hot key |
data[].coldkey_swap.new_coldkey.ss58 | string | Yes | The SS58 format of the hot key |
data[].coldkey_swap.old_coldkey | object | Yes | |
data[].coldkey_swap.old_coldkey.hex | string | Yes | The hex format of the hot key |
data[].coldkey_swap.old_coldkey.ss58 | string | Yes | The SS58 format of the hot key |
data[].coldkey_swap.timestamp | string (date-time) | Yes | |
data[].created_on_date | string (date) | Yes | |
data[].created_on_network | string | Yes | |
data[].network | string | Yes | |
data[].rank | integer (int32) | Yes | |
data[].root_basket_claimable_tao | integer (int64), nullable | Realizable TAO (rao) the coldkey could claim from its beta baskets at this snapshot's block. Null before Root Reborn and on non-finney rows. | |
data[].root_claim_type | string, nullable | ||
data[].timestamp | string (date-time) | Yes | |
pagination | object | Yes | |
pagination.current_page | integer (int32) | Yes | |
pagination.next_page | integer (int32), nullable | ||
pagination.per_page | integer (int32) | Yes | |
pagination.prev_page | integer (int32), nullable | ||
pagination.total_items | integer (int32) | Yes | |
pagination.total_pages | integer (int32) | Yes |
Example response
json
{
"data": [
{
"address": {
"hex": "0xe67990e42259688c76faad3d2cb02dbba69ecef0c780356181eac0512de6d752",
"ss58": "5HGtyz1mAgRMPgtubVTaJv8VBfwJ7a5KGGGDw5PX7WPPwLKS"
},
"balance_free": "12443252",
"balance_staked": "327659746222",
"balance_staked_alpha_as_tao": "75599415",
"balance_staked_root": "327584146807",
"balance_total": "327672189474",
"block_number": 5007431,
"coldkey_swap": null,
"created_on_date": "2023-03-21",
"created_on_network": "finney",
"network": "finney",
"rank": 0,
"timestamp": "2025-02-25T23:59:48Z"
},
{
"address": {
"hex": "0xe67990e42259688c76faad3d2cb02dbba69ecef0c780356181eac0512de6d752",
"ss58": "5HGtyz1mAgRMPgtubVTaJv8VBfwJ7a5KGGGDw5PX7WPPwLKS"
},
"balance_free": "6029953",
"balance_staked": "340138134110",
"balance_staked_alpha_as_tao": "74802571",
"balance_staked_root": "340063331539",
"balance_total": "340144164063",
"block_number": 5000231,
"coldkey_swap": null,
"created_on_date": "2023-03-21",
"created_on_network": "finney",
"network": "finney",
"rank": 0,
"timestamp": "2025-02-24T23:59:48.001Z"
}
],
"pagination": {
"current_page": 1,
"next_page": 2,
"per_page": 50,
"prev_page": null,
"total_items": 708,
"total_pages": 15
}
}Response details
text
{
"address": {
"ss58": "5DCaUSocqajoo8v2936aPAGV5QBYdVhRBTLMoYUsuF8LqyEM",
"hex": "0x323d57bfbf584d04cb390b4ade567aba4628b6d34b4484035ff6c2f9ee42c827"
},
"network": "finney",
"block_number": 5403431,
"timestamp": "2025-04-21T23:59:48Z",
"rank": 0,
"balance_free": "18466145" value in rao,
"balance_staked": "99950089307" value in rao,
"balance_staked_alpha_as_tao": "0" value in rao,
"balance_staked_root": "99950089307" value in rao,
"balance_total": "99968555452" value in rao,
"balance_free_24hr_ago": null,
"balance_staked_24hr_ago": null,
"balance_staked_alpha_as_tao_24hr_ago": null,
"balance_staked_root_24hr_ago": null,
"balance_total_24hr_ago": null,
"created_on_date": "2024-03-23",
"created_on_network": "finney",
"coldkey_swap": null
},Other responses
| Status | Meaning |
|---|---|
400 | Bad request |
404 | Account history not found |
500 | Internal server error |
Every request needs an Authorization header holding your API key — see Getting started with the Taostats API.