Documentation / New API reference / Accounts

Get Accounts Leaderboard

Reference

Last reviewed 2026-10-07

GET

https://api.taostats.io/v1/accounts/leaderboardAPI key required

Browse and rank accounts by balance.

Try it

API key

Sent only to api.taostats.io, straight from your browser. It stays in this page’s memory unless you choose to remember it for this tab.

Remember for this tab

Get an API key

Parameters

Optional parameters (18)

balance_free_min integer (int64)

Minimum free balance (RAO).

balance_free_max integer (int64)

Maximum free balance (RAO).

balance_staked_min integer (int64)

Minimum staked balance (RAO).

balance_staked_max integer (int64)

Maximum staked balance (RAO).

balance_staked_root_min integer (int64)

Minimum root-staked balance (RAO).

balance_staked_root_max integer (int64)

Maximum root-staked balance (RAO).

balance_staked_alpha_as_tao_min integer (int64)

Minimum alpha-staked-as-TAO balance (RAO).

balance_staked_alpha_as_tao_max integer (int64)

Maximum alpha-staked-as-TAO balance (RAO).

balance_total_min integer (int64)

Minimum total balance (RAO).

balance_total_max integer (int64)

Maximum total balance (RAO).

rank integer (int32)

Exact leaderboard rank.

created_on_network string

Network the account was created on (finney / kusanagi / nakamoto). Filters by the eldest observation in account_created_at_v1.

created_on_timestamp_start integer (int64)

Account-creation-time range start (unix seconds, inclusive) — filters on the eldest observation's timestamp.

created_on_timestamp_end integer (int64)

Account-creation-time range end (unix seconds, inclusive).

page integer (int32)

Page number (1-indexed). Default: 1. Bounded window: (page − 1) × limit must be below 1,000,000. Deep OFFSET paging is linear in the offset, so an uncapped page lets one request scan tens of millions of rows; a page past the window is rejected with a 400. Reach deeper history with this endpoint's range filters (block_start/block_end, timestamp_start/timestamp_end) rather than a larger page.

limit integer (int32)

Results per page. Default: 50. Max: 200.

order_by string

Column to order by. Default: balance_total.

order_dir string

Sort direction. Default: desc.

Request

GET https://api.taostats.io/v1/accounts/leaderboard

bash

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

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

python

import requests

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

Parameters

Name	In	Type	Description
`balance_free_min`	query	`integer (int64)`	Minimum free balance (RAO).
`balance_free_max`	query	`integer (int64)`	Maximum free balance (RAO).
`balance_staked_min`	query	`integer (int64)`	Minimum staked balance (RAO).
`balance_staked_max`	query	`integer (int64)`	Maximum staked balance (RAO).
`balance_staked_root_min`	query	`integer (int64)`	Minimum root-staked balance (RAO).
`balance_staked_root_max`	query	`integer (int64)`	Maximum root-staked balance (RAO).
`balance_staked_alpha_as_tao_min`	query	`integer (int64)`	Minimum alpha-staked-as-TAO balance (RAO).
`balance_staked_alpha_as_tao_max`	query	`integer (int64)`	Maximum alpha-staked-as-TAO balance (RAO).
`balance_total_min`	query	`integer (int64)`	Minimum total balance (RAO).
`balance_total_max`	query	`integer (int64)`	Maximum total balance (RAO).
`rank`	query	`integer (int32)`	Exact leaderboard rank.
`created_on_network`	query	`string`	Network the account was created on (`finney` / `kusanagi` / `nakamoto`). Filters by the eldest observation in `account_created_at_v1`.
`created_on_timestamp_start`	query	`integer (int64)`	Account-creation-time range start (unix seconds, inclusive) — filters on the eldest observation's timestamp.
`created_on_timestamp_end`	query	`integer (int64)`	Account-creation-time range end (unix seconds, inclusive).
`page`	query	`integer (int32)`	Page number (1-indexed). Default: 1. Bounded window: `(page − 1) × limit` must be below 1,000,000. Deep `OFFSET` paging is linear in the offset, so an uncapped `page` lets one request scan tens of millions of rows; a page past the window is rejected with a 400. Reach deeper history with this endpoint's range filters (`block_start`/`block_end`, `timestamp_start`/`timestamp_end`) rather than a larger `page`.
`limit`	query	`integer (int32)`	Results per page. Default: 50. Max: 200.
`order_by`	query	`string`	Column to order by. Default: `balance_total`. One of `balance_free`, `balance_staked`, `balance_staked_root`, `balance_staked_alpha_as_tao`, `balance_total`, `created_at_timestamp`.
`order_dir`	query	`string`	Sort direction. Default: `desc`. One of `asc`, `desc`.

Responses

`200` — Paginated leaderboard of accounts

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 (RAO, u64 as string).
`data[].balance_staked_alpha_as_tao`	`string`	Yes	Alpha-staked as TAO equivalent (RAO, u64 as string).
`data[].balance_staked_root`	`string`	Yes	Root-staked (RAO, u64 as string).
`data[].balance_total`	`string`	Yes	Total balance (RAO, u64 as string).
`data[].block_number`	`integer (int32)`	Yes	Block number of the snapshot.
`data[].created_on_date`	`string, nullable`	Yes	Account creation date (YYYY-MM-DD) from `account_created_at_v1`. `null` only when the account has no created-at row.
`data[].created_on_network`	`string, nullable`	Yes	Network the account was created on (from `account_created_at_v1`). `null` only when the account has no created-at row.
`data[].network`	`string`	Yes	Network name: `"finney"`, except on history rows, which carry their own network (`kusanagi` or `nakamoto` rows come back for those networks and for `network=all` or no `network`). See module docs.
`data[].rank`	`integer (int32)`	Yes	Leaderboard rank at this snapshot.
`data[].root_basket_claimable_tao`	`string, nullable`	Yes	TAO claimable from this coldkey's root beta baskets at this snapshot (RAO, u64 as string) — what redeeming every basket share would have realized at that block. `null` means unknown, never zero. It is populated on `/v1/accounts/{address}/history` from the daily snapshot block, and is `null` on rows before basket state existed on chain (below block 8,765,684, i.e. before 2026-08-03). On `/v1/accounts/leaderboard` it is always `null`: the figure needs a per-coldkey computation the latest snapshot does not carry, and the old API is the same — it fills the field for one address, never for a list. Not part of `balance_total`. It is an entitlement held by the funds, not a balance the coldkey holds, so it cannot move the rank.
`data[].root_claim_type`	`string, nullable`	Yes	Always `null`. The root-claim preference was deleted from the chain at spec 441 and is no longer served (#774, see module docs); the field is kept because the OLD API returns it as `null`.
`data[].timestamp`	`string`	Yes	ISO 8601 timestamp, e.g. `"2026-06-13T09:10:00.000Z"`.
`pagination`	`object`	Yes	Pagination metadata appended to collection responses. `next_page` / `prev_page` are explicitly required+nullable in the OpenAPI spec: per `docs/api_standards.md` we emit `null` rather than omitting the field, so the SDK should model them as `Option`/nullable types that are always present in the response. `total_items` is the exact number of matching rows on every route (issue #992). It used to stop at 1,000,000, which reported a million transfers when finney holds 7,513,252 and a million events when the real figure is 981,179,110; the cap was removed on 29 Sep 2026 and nothing may reintroduce one — `crate::pagination::exact_count_sql` is the only count form, and `no_capped_count_reaches_the_api_surface` in `data-debug-scripts` fails the build if a capped one comes back. `total_pages` is still bounded, to `crate::pagination::max_reachable_page(per_page)`, because the `page` parameter is capped to a 1,000,000-row window: deep `OFFSET` paging reads every skipped row (24.7M rows / 36.6 GiB / 42 s measured on one endpoint, issue #413). So `total_pages` is exactly the last page this API will serve and `next_page` / `prev_page` stay coherent at the window edge, while `total_items` tells the caller how many rows there really are. History beyond the window is reached with each endpoint's range filters, not a larger `page`.
`pagination.current_page`	`integer (int32)`	Yes	1-indexed page that produced the rows in `data`.
`pagination.next_page`	`integer (int32), nullable`	Yes	Next page number, or `null` if this is the last page.
`pagination.per_page`	`integer (int32)`	Yes	Number of items requested per page.
`pagination.prev_page`	`integer (int32), nullable`	Yes	Previous page number, or `null` if this is the first page.
`pagination.total_items`	`integer (int64)`	Yes	Number of items matching the query across all pages. This is the exact count — every matching row, however many there are. It is not bounded by `total_pages`, so a listing can legitimately report far more items than `total_pages × per_page`.
`pagination.total_pages`	`integer (int32)`	Yes	Number of pages at the current `per_page` that this API will serve: `ceil(total_items / per_page)`, capped at `ceil(1000000 / per_page)` because the `page` parameter only reaches into the first 1,000,000 rows. When the cap bites, `total_items` is still the true total and this is the last page a request can ask for; reach deeper history with the endpoint's range filters instead of a larger `page`.

`400` — Invalid query parameter

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.

Was this page helpful?

Documentation / New API reference / Accounts

Get Accounts Leaderboard

Reference

Last reviewed 2026-10-07

GET

https://api.taostats.io/v1/accounts/leaderboardAPI key required

Browse and rank accounts by balance.

Try it

API key

Sent only to api.taostats.io, straight from your browser. It stays in this page’s memory unless you choose to remember it for this tab.

Remember for this tab

Get an API key

Parameters

Optional parameters (18)

balance_free_min integer (int64)

Minimum free balance (RAO).

balance_free_max integer (int64)

Maximum free balance (RAO).

balance_staked_min integer (int64)

Minimum staked balance (RAO).

balance_staked_max integer (int64)

Maximum staked balance (RAO).

balance_staked_root_min integer (int64)

Minimum root-staked balance (RAO).

balance_staked_root_max integer (int64)

Maximum root-staked balance (RAO).

balance_staked_alpha_as_tao_min integer (int64)

Minimum alpha-staked-as-TAO balance (RAO).

balance_staked_alpha_as_tao_max integer (int64)

Maximum alpha-staked-as-TAO balance (RAO).

balance_total_min integer (int64)

Minimum total balance (RAO).

balance_total_max integer (int64)

Maximum total balance (RAO).

rank integer (int32)

Exact leaderboard rank.

created_on_network string

Network the account was created on (finney / kusanagi / nakamoto). Filters by the eldest observation in account_created_at_v1.

created_on_timestamp_start integer (int64)

Account-creation-time range start (unix seconds, inclusive) — filters on the eldest observation's timestamp.

created_on_timestamp_end integer (int64)

Account-creation-time range end (unix seconds, inclusive).

page integer (int32)

limit integer (int32)

Results per page. Default: 50. Max: 200.

order_by string

Column to order by. Default: balance_total.

order_dir string

Sort direction. Default: desc.

Request

GET https://api.taostats.io/v1/accounts/leaderboard

bash

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

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

python

import requests

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

Parameters

Name	In	Type	Description
`balance_free_min`	query	`integer (int64)`	Minimum free balance (RAO).
`balance_free_max`	query	`integer (int64)`	Maximum free balance (RAO).
`balance_staked_min`	query	`integer (int64)`	Minimum staked balance (RAO).
`balance_staked_max`	query	`integer (int64)`	Maximum staked balance (RAO).
`balance_staked_root_min`	query	`integer (int64)`	Minimum root-staked balance (RAO).
`balance_staked_root_max`	query	`integer (int64)`	Maximum root-staked balance (RAO).
`balance_staked_alpha_as_tao_min`	query	`integer (int64)`	Minimum alpha-staked-as-TAO balance (RAO).
`balance_staked_alpha_as_tao_max`	query	`integer (int64)`	Maximum alpha-staked-as-TAO balance (RAO).
`balance_total_min`	query	`integer (int64)`	Minimum total balance (RAO).
`balance_total_max`	query	`integer (int64)`	Maximum total balance (RAO).
`rank`	query	`integer (int32)`	Exact leaderboard rank.
`created_on_network`	query	`string`	Network the account was created on (`finney` / `kusanagi` / `nakamoto`). Filters by the eldest observation in `account_created_at_v1`.
`created_on_timestamp_start`	query	`integer (int64)`	Account-creation-time range start (unix seconds, inclusive) — filters on the eldest observation's timestamp.
`created_on_timestamp_end`	query	`integer (int64)`	Account-creation-time range end (unix seconds, inclusive).
`page`	query	`integer (int32)`	Page number (1-indexed). Default: 1. Bounded window: `(page − 1) × limit` must be below 1,000,000. Deep `OFFSET` paging is linear in the offset, so an uncapped `page` lets one request scan tens of millions of rows; a page past the window is rejected with a 400. Reach deeper history with this endpoint's range filters (`block_start`/`block_end`, `timestamp_start`/`timestamp_end`) rather than a larger `page`.
`limit`	query	`integer (int32)`	Results per page. Default: 50. Max: 200.
`order_by`	query	`string`	Column to order by. Default: `balance_total`. One of `balance_free`, `balance_staked`, `balance_staked_root`, `balance_staked_alpha_as_tao`, `balance_total`, `created_at_timestamp`.
`order_dir`	query	`string`	Sort direction. Default: `desc`. One of `asc`, `desc`.

Responses

`200` — Paginated leaderboard of accounts

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 (RAO, u64 as string).
`data[].balance_staked_alpha_as_tao`	`string`	Yes	Alpha-staked as TAO equivalent (RAO, u64 as string).
`data[].balance_staked_root`	`string`	Yes	Root-staked (RAO, u64 as string).
`data[].balance_total`	`string`	Yes	Total balance (RAO, u64 as string).
`data[].block_number`	`integer (int32)`	Yes	Block number of the snapshot.
`data[].created_on_date`	`string, nullable`	Yes	Account creation date (YYYY-MM-DD) from `account_created_at_v1`. `null` only when the account has no created-at row.
`data[].created_on_network`	`string, nullable`	Yes	Network the account was created on (from `account_created_at_v1`). `null` only when the account has no created-at row.
`data[].network`	`string`	Yes	Network name: `"finney"`, except on history rows, which carry their own network (`kusanagi` or `nakamoto` rows come back for those networks and for `network=all` or no `network`). See module docs.
`data[].rank`	`integer (int32)`	Yes	Leaderboard rank at this snapshot.
`data[].root_basket_claimable_tao`	`string, nullable`	Yes	TAO claimable from this coldkey's root beta baskets at this snapshot (RAO, u64 as string) — what redeeming every basket share would have realized at that block. `null` means unknown, never zero. It is populated on `/v1/accounts/{address}/history` from the daily snapshot block, and is `null` on rows before basket state existed on chain (below block 8,765,684, i.e. before 2026-08-03). On `/v1/accounts/leaderboard` it is always `null`: the figure needs a per-coldkey computation the latest snapshot does not carry, and the old API is the same — it fills the field for one address, never for a list. Not part of `balance_total`. It is an entitlement held by the funds, not a balance the coldkey holds, so it cannot move the rank.
`data[].root_claim_type`	`string, nullable`	Yes	Always `null`. The root-claim preference was deleted from the chain at spec 441 and is no longer served (#774, see module docs); the field is kept because the OLD API returns it as `null`.
`data[].timestamp`	`string`	Yes	ISO 8601 timestamp, e.g. `"2026-06-13T09:10:00.000Z"`.
`pagination`	`object`	Yes	Pagination metadata appended to collection responses. `next_page` / `prev_page` are explicitly required+nullable in the OpenAPI spec: per `docs/api_standards.md` we emit `null` rather than omitting the field, so the SDK should model them as `Option`/nullable types that are always present in the response. `total_items` is the exact number of matching rows on every route (issue #992). It used to stop at 1,000,000, which reported a million transfers when finney holds 7,513,252 and a million events when the real figure is 981,179,110; the cap was removed on 29 Sep 2026 and nothing may reintroduce one — `crate::pagination::exact_count_sql` is the only count form, and `no_capped_count_reaches_the_api_surface` in `data-debug-scripts` fails the build if a capped one comes back. `total_pages` is still bounded, to `crate::pagination::max_reachable_page(per_page)`, because the `page` parameter is capped to a 1,000,000-row window: deep `OFFSET` paging reads every skipped row (24.7M rows / 36.6 GiB / 42 s measured on one endpoint, issue #413). So `total_pages` is exactly the last page this API will serve and `next_page` / `prev_page` stay coherent at the window edge, while `total_items` tells the caller how many rows there really are. History beyond the window is reached with each endpoint's range filters, not a larger `page`.
`pagination.current_page`	`integer (int32)`	Yes	1-indexed page that produced the rows in `data`.
`pagination.next_page`	`integer (int32), nullable`	Yes	Next page number, or `null` if this is the last page.
`pagination.per_page`	`integer (int32)`	Yes	Number of items requested per page.
`pagination.prev_page`	`integer (int32), nullable`	Yes	Previous page number, or `null` if this is the first page.
`pagination.total_items`	`integer (int64)`	Yes	Number of items matching the query across all pages. This is the exact count — every matching row, however many there are. It is not bounded by `total_pages`, so a listing can legitimately report far more items than `total_pages × per_page`.
`pagination.total_pages`	`integer (int32)`	Yes	Number of pages at the current `per_page` that this API will serve: `ceil(total_items / per_page)`, capped at `ceil(1000000 / per_page)` because the `page` parameter only reaches into the first 1,000,000 rows. When the cap bites, `total_items` is still the true total and this is the last page a request can ask for; reach deeper history with the endpoint's range filters instead of a larger `page`.

`400` — Invalid query parameter

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.

Try it

Request

Parameters

Responses

200 — Paginated leaderboard of accounts

400 — Invalid query parameter

500 — Internal server error

Was this page helpful?

Try it

Request

Parameters

Responses

200 — Paginated leaderboard of accounts

400 — Invalid query parameter

500 — Internal server error

Was this page helpful?

`200` — Paginated leaderboard of accounts

`400` — Invalid query parameter

`500` — Internal server error

`200` — Paginated leaderboard of accounts

`400` — Invalid query parameter

`500` — Internal server error