Skip to content
TAO$188.21
BTC0.002927
MCap$2.22B
Vol$86.25M

API reference / Validators

Validators' stakers, nominators, stake and network share now and 7 or 30 days ago

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

How validators moved.

Full description

How validators moved: for each hotkey asked, its stakers, nominators and stake (valued in TAO at each subnet's close price, root 1:1) at the newest closed UTC day and days (7 or 30) days before it, the change, its share of the network's stake at each close (network dominance), and the childkey take it received and paid between them; with the same figures per subnet pool (by_subnet). A subnet registered again between the two closes is never mixed with its earlier registration: its pool is left out of the totals and counted in pools_life_changed. A pool without a close price makes the TAO figures it enters null (unpriced_pools), never 0. A hotkey that held no pool is served with zero counts. Figures are at UTC day closes: the newest is meta.through_day (the day before today once that day's data is published, normally within about an hour of midnight UTC). A day that is late but at most 36 hours overdue is still served, labelled by meta.through_day, with the response headers X-BTAI-Data-Through: <YYYY-MM-DD> and X-BTAI-Overdue-S: <seconds>; data more than 36 hours overdue is not served (503 SOURCE_NOT_READY with Retry-After); where this deployment does not serve the route it is a 503 SOURCE_NOT_READY. Amounts are integer strings in rao, ratios decimal strings. Cached as slow (the data moves once a day). Errors are application/problem+json: ADDRESSES_REQUIRED, BATCH_TOO_LARGE, INVALID_ADDRESS, INVALID_DAYS, UNKNOWN_PARAMETER, SOURCE_TIMEOUT (503), SOURCE_NOT_READY (503), SERVICE_UNAVAILABLE (503), BAD_GATEWAY (502).

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

Query parameters

hotkeysquery· string

Required. The validators: a comma list of 1-500 hotkeys (SS58, or 0x + 64 hex; a repeat counts once). An empty list is a 400 ADDRESSES_REQUIRED, more than 500 a 400 BATCH_TOO_LARGE, an invalid one a 400 INVALID_ADDRESS naming its index (hotkeys[i]). The request line is capped at 4,094 bytes, which fits about 60 SS58 hotkeys.

daysquery· integer · default 30

The days between the two closes compared: 7 or 30 (default 30). Anything else is a 400 INVALID_DAYS.

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.

One item per hotkey asked, in the order asked (a repeated hotkey once).

hotkeyvalue · optional

The validator's hotkey, as {ss58, hex}.

poolsinteger · unit count · optional

Subnet pools counted in the totals: held at either close, on a subnet not registered again between them.

pools_life_changedinteger · unit count · optional

Subnet pools left out of the totals because their subnet was registered again between the two closes (never mixed with the new subnet's figures).

unpriced_poolsinteger · unit count · optional

Pools counted that had no close price at either close: the TAO totals they enter are null.

stakersinteger · unit count · optional

Positions with stake above 0 over the counted pools at meta.through_day's close.

stakers_frominteger · unit count · optional

The same at meta.from_day's close.

stakers_changeinteger · unit count · optional

stakers - stakers_from.

can be negative
nominatorsinteger · unit count · can be null

Positions held by coldkeys other than the validator's owner at the newest close, over the counted pools. Null when a pool's count was not recorded that day.

nominators_frominteger · unit count · can be null

The same at meta.from_day's close.

nominators_changeinteger · unit count · can be null

nominators - nominators_from; null when either is null.

can be negative
stake_tao_raostring · unit rao (÷1e9) · can be null

Stake over the counted pools at the newest close, each valued in TAO at its subnet's close price (root 1:1), rao. Null when a pool counted here had no close price that day (see unpriced_pools).

Format: whole number, as a string · on chain: u64
stake_from_tao_raostring · unit rao (÷1e9) · can be null

The same at meta.from_day's close, rao. Null when a pool counted here had no close price that day (see unpriced_pools).

Format: whole number, as a string · on chain: u64
stake_change_tao_raostring · unit rao (÷1e9) · can be null

stake_tao_rao - stake_from_tao_rao, rao; null when either is null.

Format: whole number, as a string · can be negative
subnet_stake_tao_raostring · unit rao (÷1e9) · can be null

stake_tao_rao over the subnet pools only (root left out), rao. Null when a pool counted here had no close price that day (see unpriced_pools).

Format: whole number, as a string · on chain: u64
subnet_stake_from_tao_raostring · unit rao (÷1e9) · can be null

The same at meta.from_day's close, rao. Null when a pool counted here had no close price that day (see unpriced_pools).

Format: whole number, as a string · on chain: u64
stake_share_ratiostring · unit ratio · can be null

Network dominance at the newest close: stake_tao_rao over meta.network_stake_tao_rao, 8 decimals. Null when stake_tao_rao is.

stake_share_from_ratiostring · unit ratio · can be null

The same at meta.from_day's close, over meta.network_stake_from_tao_rao.

childkey_take_gained_tao_raostring · unit rao (÷1e9) · can be null

Childkey take received as a child hotkey over the counted pools, the days after meta.from_day through meta.through_day, each day valued at its close price, rao. Null when a day with take had no close price.

Format: whole number, as a string · on chain: u64
childkey_take_paid_tao_raostring · unit rao (÷1e9) · can be null

Childkey take paid as a parent hotkey over the same pools and days, valued the same way, rao. Null when a day with take had no close price.

Format: whole number, as a string · on chain: u64
by_subnetarray of objects · optional

Each subnet the validator held a pool on at either close, or took or paid childkey take on in the window, by netuid; [] when none.

16 fields in by_subnet (each item)
netuidinteger · unit id · optional

The subnet (0 = root).

life_changedboolean · optional

True when the subnet was registered again between the two closes: its earlier figures belong to another subnet, so this pool is left out of the validator's totals and only its newest close is served (every *_from* and childkey take member is null).

presentboolean · optional

The validator had a stake pool on this subnet at meta.through_day's close.

present_fromboolean · can be null

The same at meta.from_day's close. Null when life_changed.

stakersinteger · unit count · optional

Positions with stake above 0 in the pool at the newest close.

stakers_frominteger · unit count · can be null

The same at meta.from_day's close. Null when life_changed.

nominatorsinteger · unit count · can be null

Positions held by coldkeys other than the validator's owner at the newest close (0 when the pool is absent). Null when that day's count was not recorded.

nominators_frominteger · unit count · can be null

The same at meta.from_day's close. Null when not recorded, or when life_changed.

alpha_raostring · unit alpha_rao (÷1e9) · optional

Stake in the pool at the newest close, in the subnet's alpha (root: TAO), rao.

Format: whole number, as a string · on chain: u64
alpha_from_raostring · unit alpha_rao (÷1e9) · can be null

The same at meta.from_day's close. Null when life_changed.

Format: whole number, as a string · on chain: u64
stake_tao_raostring · unit rao (÷1e9) · can be null

alpha_rao valued in TAO at the subnet's close price that day (root 1:1), rounded down, rao. Null when the subnet had no close price that day.

Format: whole number, as a string · on chain: u64
stake_from_tao_raostring · unit rao (÷1e9) · can be null

alpha_from_rao valued at meta.from_day's close price, rao. Null without a price, or when life_changed.

Format: whole number, as a string · on chain: u64
childkey_take_gained_alpha_raostring · unit alpha_rao (÷1e9) · can be null

Childkey take this validator received as a child hotkey on this subnet over the days after meta.from_day through meta.through_day, in alpha rao (take a hotkey pays itself is left out). Null when life_changed.

Format: whole number, as a string · on chain: u64
childkey_take_paid_alpha_raostring · unit alpha_rao (÷1e9) · can be null

Childkey take this validator paid as a parent hotkey on this subnet over the same days, in alpha rao. Null when life_changed.

Format: whole number, as a string · on chain: u64
childkey_take_gained_tao_raostring · unit rao (÷1e9) · can be null

childkey_take_gained_alpha_rao with each day's take valued at that day's close price, rao. Null when a day with take had no close price, or when life_changed.

Format: whole number, as a string · on chain: u64
childkey_take_paid_tao_raostring · unit rao (÷1e9) · can be null

childkey_take_paid_alpha_rao valued the same way, rao. Null when a day with take had no close price, or when life_changed.

Format: whole number, as a string · on chain: u64

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.