Validators' stakers, nominators, stake and network share now and 7 or 30 days ago
https://api.bittensor.ai/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 400BATCH_TOO_LARGE, an invalid one a 400INVALID_ADDRESSnaming 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 (seeunpriced_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_raoover the subnet pools only (root left out), rao. Null when a pool counted here had no close price that day (seeunpriced_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 (seeunpriced_pools).- Format: whole number, as a string · on chain: u64
- 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_daythroughmeta.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 whenlife_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 whenlife_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 whenlife_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 whenlife_changed.- Format: whole number, as a string · on chain: u64
- stake_tao_raostring · unit rao (÷1e9) · can be null
alpha_raovalued 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_raovalued atmeta.from_day's close price, rao. Null without a price, or whenlife_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_daythroughmeta.through_day, in alpha rao (take a hotkey pays itself is left out). Null whenlife_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_raowith each day's take valued at that day's close price, rao. Null when a day with take had no close price, or whenlife_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_raovalued the same way, rao. Null when a day with take had no close price, or whenlife_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), slowpublic, max-age=300, stale-while-revalidate=600(state that moves in minutes or days) or tippublic, 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). Neverimmutable.no-storeon 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-revalidateandstale-if-error;no-storewithX-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, withX-BTAI-Stale-As-Of,Age(its seconds since then) andWarning: 110 - "Response is Stale", andCache-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.
- ADDRESSES_REQUIRED
- AMBIGUOUS_CREDENTIALS
- BAD_GATEWAY
- BATCH_TOO_LARGE
- BILLING_UNAVAILABLE
- BUDGET_EXCEEDED
- CONCURRENCY_LIMIT
- INSUFFICIENT_PERMISSIONS
- INTERNAL_ERROR
- INVALID_ADDRESS
- INVALID_DAYS
- PAYMENT_REQUIRED
- PLAN_REQUIRED
- RATE_LIMITED
- REPEATED_PARAMETER
- SERVICE_UNAVAILABLE
- SOURCE_BUSY
- SOURCE_NOT_READY
- SOURCE_TIMEOUT
- UNAUTHORIZED
- UNKNOWN_PARAMETER
- VALIDATION_ERROR
From the API's published specification, version 1.165.0.