Skip to content
TAO$188.58
BTC0.002932
MCap$2.21B
Vol$86.73M

API reference / Validators

Every validator, ranked and filtered: stake, nominators, wallets, 30-day emission, permits, fund NAV

GET/api/v2/validators
Status
Beta
Auth
API key or OAuth access token
Scope
data:read
Rate limit
plan

The validators directory.

Full description

The validators directory: every validator hotkey (scope=all: a validator permit on any subnet now; scope=root: a root UID), ranked (sort) by stake (its stake on every subnet at spot, root 1:1), nominators (positions, per pool), nominator_wallets (distinct coldkeys), emission_30d (realized credits only), subnet_count (permits), nav (a fund's realizable NAV), holder_return, take, age (blocks since the hotkey was first written), return_7d / return_30d (a fund's holders' return over 7 / 30 day ends), share_price (a fund's display price) or vs_index (its price against the bag index), in order desc (the default; age: the oldest first) or asc, rows without the key last either way, offset-paged (offset, limit; meta.page.total counts the scope). Ties are broken by the hotkey's bytes, ascending: the order is stable, so offset paging never repeats or skips a validator. Each row is GET /hotkeys' hotkey-level default row (identity, falling back to the Owner coldkey's; owner; root UID; take; stake and own stake; nominators; the 30-day emission split, whose total is realized credits only: the root claimable is its own member, never in it) plus rank, the three subnet counts (subnet_count: a UID; validator_subnet_count: a validator permit; staked_subnet_count: stake in its pool), nominator_wallets (distinct coldkeys over all its pools, counted at meta.nominator_wallets_at), validator_subnet_count and two realised nominator APYs over the last 7 days: nominator_apy_7d_ratio covers the SUBNET pools only (alpha-denominated). The root stake has two of its own, because root dividends arrive as alpha claims on the subnets, not as root-pool growth: root_claimable_apy_7d_ratio (ACCRUED, unrealised until claimed: never income) and root_claimed_apy_7d_ratio (REALISED: the claims executed, lumpier); show them on scope=root rows. staking (the APY at the reference stake, swap costs, breakeven) is filled for fund validators only, null for every other validator for now. A fund validator's row also carries its spot and realizable NAV and its holders' return over up to 30 days (null for the rest), and its share price, vs-index and holders' return over 7 / 30 day ends at the funds' latest available pricing day; every row its distinct nominator wallets and first / last seen blocks; and its stake split, take_raised_30d and staking_options (option A root_stake and option B's directory summary fund, two blocks never combined, each with its own as_of_*), and the orders root_stake, subnet_stake, root_apy_7d / _30d, fund_nav_realizable (nav its alias) and holder_return_7d / _30d; the picker adds root_apy_7d and holder_return_30d (RatioFigures). fields=picker answers the ranking's own fields only (ValidatorPickerRow: rank, hotkey, identity name, stake, the three subnet counts, nominator positions and wallets, the 30-day realized total, the fund's realizable NAV and holders' return, the take, first / last seen and the fund's price members: every order's key), much faster, for selectors and watchlists; meta, paging and totals are the same. Filters (ranks are within the filtered set, meta.page.total counts it, meta.totals sums it and meta.filters echoes them): q (the owner's identity name or the hotkey's label, a case-insensitive substring, or a hotkey prefix as 0x hex or SS58), hotkeys (a watchlist), netuid (a validator permit there now), min_stake_rao / max_stake_rao (on the ranking stake). include=subnets adds each full row's option-C pools (staking_options.subnets, ranked, never averaged). The old spellings order=<key> and direction are still accepted (giving both spellings of one parameter is a 400). Errors are application/problem+json: INVALID_SCOPE, INVALID_SORT, INVALID_ORDER, INVALID_DIRECTION, INVALID_FIELDS, INVALID_INCLUDE, INVALID_LIMIT, INVALID_OFFSET, INVALID_QUERY, INVALID_ADDRESS, BATCH_TOO_LARGE, INVALID_RANGE, NOT_READY (503), UNKNOWN_PARAMETER, SOURCE_TIMEOUT (503), SOURCE_NOT_READY (503).

Beta: this route may change with one release's notice in the v2 changelog; additive changes need none (x-stability: beta).

Query parameters

scopequery· enum · one of all, root · default all

all (the default): a validator permit on any subnet now; root: a root UID. Anything else is a 400.

sortquery· enum · one of stake, nominators, nominator_wallets, emission_30d, subnet_count, nav, holder_return, take, age, return_7d, return_30d, share_price, vs_index, root_stake, subnet_stake, root_apy_7d, root_apy_30d, fund_nav_realizable, holder_return_7d, holder_return_30d, nominator_wallets_valued, nominator_positions_valued

stake (the default), nominators (nominator positions, a coldkey counted per pool), nominator_wallets (distinct coldkeys), emission_30d (the realized 30-day total), subnet_count (validator permits: validator_subnet_count), nav (a fund's realizable NAV), holder_return (a fund's holders' return), take (take_ratio), age (blocks since first_seen_height), return_7d / return_30d (fund_holder_return_7d_ratio / _30d_ratio), share_price (fund_share_price) or vs_index (fund_vs_index_ratio), root_stake (root_stake_tao_rao), subnet_stake (subnet_stake_spot_tao_rao), root_apy_7d / root_apy_30d (option A's holder-true accrual, staking_options.root_stake.apy_*), fund_nav_realizable (fund_nav_realizable_tao_rao; nav is its alias for this version) or holder_return_7d / holder_return_30d (option B's, staking_options.fund.holder_return_*), or nominator_wallets_valued / nominator_positions_valued (the stored valued nominator counts, refreshed hourly: a hotkey not counted yet sorts last); rank follows it in order (nulls last either way). Anything else is a 400 INVALID_SORT.

orderquery· enum · one of asc, desc

The direction: desc (the default: highest first; for age the oldest first) or asc. Rows without the key (a non-fund's share price, say) come last either way. The old spelling order=<key> (a sort key, read as sort) and direction (the old name of this parameter) are still accepted; giving both spellings of one parameter is a 400. Anything else is a 400 INVALID_ORDER.

fieldsquery· enum · one of full, picker · default full

The row shape: full (the default: ValidatorDirectoryRow) or picker (ValidatorPickerRow, the ranking's own fields only). Anything else is a 400 INVALID_FIELDS.

limitquery· integer · default 50 · 1 to 1000

Page size, 1..1000 (default 50): limit=1000 reads the whole directory in one request. With include, at most 100 (else a 400 INVALID_LIMIT). A page over 100 rows can answer a 503 NOT_READY for a minute or two after a data refresh; retry it.

offsetquery· integer · default 0 · 0 to 1000000

Rows skipped: the page holds ranks offset + 1..offset + limit (default 0). Past the end the page is [] with the same meta.

qquery· string · 1 to 64 characters

A search, 1..64 characters: the owner's identity name or the hotkey's label (case-insensitive substring), or a hotkey prefix (0x hex, or SS58 from 3 characters).

hotkeysquery· string

A watchlist: a comma list of 1..500 hotkeys, SS58 or 0x + 64 hex; only these are ranked. An invalid one is a 400 INVALID_ADDRESS naming its index, too many a 400 BATCH_TOO_LARGE.

netuidquery· integer · 0 to 65535

Only validators holding a validator permit on this subnet now.

min_stake_raoquery· string

Only validators whose ranking stake is at least this, TAO rao (a decimal integer). Anything else, or above max_stake_rao, is a 400 INVALID_RANGE.

max_stake_raoquery· string

Only validators whose ranking stake is at most this, TAO rao (a decimal integer).

includequery· string

subnets (full rows only): each row's staking_options.subnets, option C, one row per pool the hotkey has stake in on a subnet, ranked by its 7-day APY (never averaged). A heavier read, cached apart from the landing page (sent only when given). Anything else, or with fields=picker, is a 400 INVALID_INCLUDE.

Response

data is a list of objects with these fields. Amounts are integer strings in their base unit, and null means unknown, never zero (see Units and formats). meta.at names the block the answer was read at.

The page's validators, by rank ascending ([] past the end): every row a ValidatorDirectoryRow with fields=full (the default), every row a ValidatorPickerRow with fields=picker (meta.fields says which).

Response headers

10 headers: ETag, Cache-Control, CDN-Cache-Control, X-BTAI-Stale, X-BTAI-Stale-As-Of, RateLimit-Policy, RateLimit, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
ETag

Strong validator of this answer. Send it back as If-None-Match: an unchanged answer is a 304 Not Modified without a body. A settled answer's validator leaves the chain head out, so it stays valid as the head moves.

Cache-Control

One of three classes: settled public, max-age=3600, stale-while-revalidate=86400 (pinned to a block that cannot move), slow public, max-age=300, stale-while-revalidate=600 (state that moves in minutes or days) or tip public, max-age=6, stale-while-revalidate=12 (follows the chain head); the label routes are cached until the next nightly copy (public, max-age=<seconds>, stale-while-revalidate=60). Never immutable. no-store on an earlier answer served because the data source failed (X-BTAI-Stale).

CDN-Cache-Control

The same class for shared caches (RFC 9213; browsers ignore it): settled 24 h, slow 300 s, tip 6 s, each with stale-while-revalidate and stale-if-error; no-store with X-BTAI-Stale.

X-BTAI-Stale

Present only when the data source failed to answer (it timed out or was unavailable) and an earlier answer to the same request is served instead of a 503 (stale if error, RFC 5861). Then if-error, with X-BTAI-Stale-As-Of, Age (its seconds since then) and Warning: 110 - "Response is Stale", and Cache-Control: no-store: the answer is never kept as fresh, and a later request reads again. Prices and quotes are never served this way.

X-BTAI-Stale-As-Of

With X-BTAI-Stale: when the earlier answer served was produced, an RFC 3339 UTC time (2026-10-21T12:00:00Z).

RateLimit-Policy

The tier's request quota of the current window (IETF draft), e.g. "tier";q=600.

RateLimit

Requests left in the current window and the seconds until it resets (IETF draft), e.g. "tier";r=597;t=42.

X-RateLimit-Limit

The tier's request quota of the current window.

X-RateLimit-Remaining

Requests left in the current window.

X-RateLimit-Reset

When the current window resets, Unix seconds.

Status codes

200 · 304 · 400 · 401 · 402 · 403 · 404 · 429 · 500 · 502 · 503

304 Not Modified: the If-None-Match validator still matches; no body.

Error codes

The codes this endpoint can return. Each links to what it means and what to do.

From the API's published specification, version 1.165.0.