Skip to content
TAO$188.32
BTC0.002928
MCap$2.22B
Vol$86.25M

API reference / Subnets

Several or every subnet's holders, delegates, positions and staked alpha at each closed UTC day's end

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

GET /subnets/{netuid}/holders/daily for any number of subnets in one call.

Full description

GET /subnets/{netuid}/holders/daily for any number of subnets in one call (netuids), or for every current subnet (no netuids): one series per subnet, ascending by netuid, each the one-subnet route's series unchanged (per closed UTC day, oldest first, at the day's last block: holders, delegates, positions, staked alpha, the largest position, the 10 largest coldkeys' alpha, nakamoto, the normalised HHI and the validator permits; the pool members null on a day where they cannot be whole). A subnet without holder rows in the window has no series and is listed in meta.missing_netuids; meta.netuids echoes the set asked (every current subnet without netuids). A page holds at most ~11,700 subnet-days: meta.page.limit_days is 366 for up to 32 subnets and fewer above (128 subnets: 91), so read it and follow meta.page.next_cursor rather than assume 366. Moves when the next day is available: cached as slow. Day window: from_day / to_day (inclusive UTC days), or days back from to_day (not both days and from_day); no ceiling: a range longer than meta.page.limit_days pages by cursor (meta.page.next_cursor), oldest days first, and meta.range states the whole request (from_day raised to the first available day says so). An explicit to_day is never answered with an earlier day: one not available yet is a 503 NOT_READY. While paged day windows are not available yet, from_day, to_day and cursor are a 503 SOURCE_NOT_READY (a days-only request is unchanged). One life: a netuid is a slot and a re-registered subnet is a new life; the series covers the subnet's CURRENT life only, from its first whole UTC day (data[].generation, data[].life_start_height, data[].life_first_day; a life with no whole day yet answers no rows). While per-life series are not available yet, the series is not limited to one life and those members are null. meta.lives states every subnet asked's current life, with a series or not. The cursor is bound to the subnet set (every subnet: one registered between pages joins). Errors are application/problem+json: INVALID_NETUID (malformed, or every subnet / that many subnets where the data source does not serve them yet), INVALID_DAYS, INVALID_DAY, INVALID_RANGE, INVALID_CURSOR, UNKNOWN_PARAMETER, NOT_READY (503), NOT_FINAL (503), SOURCE_TIMEOUT (503), SOURCE_NOT_READY (503). meta.final_through_day is the key to cache closed days by: the rows through it never change again (but by an announced rerun); later rows may (null on an older data version's answer).

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

Query parameters

netuidsquery· string

The subnets: a comma list (or the parameter repeated) of netuids, each 0..65535, as many as needed; duplicates are ignored. Omitted: every current subnet. Anything else is a 400 INVALID_NETUID.

daysquery· integer · default 30 · at least 1

How many closed UTC days end at to_day (default 30, ending at the newest closed day; fewer where the daily holders starts later: meta.from_day says where). No ceiling: a range longer than one page pages by cursor (while paged day windows are not available yet, more than 365 is a 400 INVALID_DAYS). Not with from_day (both: a 400 INVALID_RANGE). Outside 1..1,000,000 is a 400 INVALID_DAYS.

from_dayquery· string (date)

The first UTC day, YYYY-MM-DD, inclusive (raised to the first available day: meta.range.from_day_raised). Not with days (both: a 400 INVALID_RANGE); after to_day: a 400 INVALID_RANGE; not a date: a 400 INVALID_DAY.

Format: date, YYYY-MM-DD
to_dayquery· string (date)

The last closed UTC day, YYYY-MM-DD, inclusive (default: the newest available day). Final or refused, never an earlier day: a day not available yet is a 503 NOT_READY, one available but after meta.final_through_day a 503 NOT_FINAL (retry). Today is a 503 NOT_READY (closed days only), a later day a 400 INVALID_RANGE, not a date a 400 INVALID_DAY. A final to_day is cached as settled.

Format: date, YYYY-MM-DD
cursorquery· string · up to 200 characters

meta.page.next_cursor of the previous page: the next days of a range longer than one page, sent back unchanged with the same other parameters (a changed or altered one is a 400 INVALID_CURSOR). While paged day windows are not available yet: 503 SOURCE_NOT_READY.

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 series per subnet asked (every current subnet without netuids) that has holder rows in the window, ascending by netuid; each series' days oldest first.

netuidinteger · unit id

The subnet slot.

daysarray of objects

One per closed day with holder rows, oldest first; the current life's days only (from life_first_day).

11 fields in days (each item)
daystring (date)

The UTC day.

Format: date, YYYY-MM-DD
heightinteger · unit block

The day's last block: every figure is read there.

holder_countinteger · unit count

Coldkeys with alpha > 0 on the subnet (each counted once).

delegate_countinteger · unit count · can be null

The nominator count: hotkeys whose pool on the subnet holds a non-zero share from a coldkey other than the hotkey's Owner (the validators other people delegate to; the subnet list's delegates), at the day's end. Null on a day before meta.delegate_count_from_day (each pool's Owner is not recorded for those days; every day when that is null), never a 0 standing in. On an older data version's answer: hotkeys with at least one staker. Either way null, with position_count and max_position_alpha_rao, when the pools' day-end stakers cannot be whole (fewer positions than holders) or disagree with the holders (the largest position above top10_alpha_rao).

position_countinteger · unit count · can be null

(hotkey, coldkey) positions with alpha > 0 (at least holder_count). Null when the pools' day-end stakers cannot be whole (fewer positions than holders) or disagree with the holders (the largest position above top10_alpha_rao).

total_alpha_raostring · unit alpha_rao (÷1e9)

The holders' alpha together, alpha rao.

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

The largest single (hotkey, coldkey) position, alpha rao (at most top10_alpha_rao). Null with position_count.

Format: whole number, as a string · on chain: u64
top10_alpha_raostring · unit alpha_rao (÷1e9)

The 10 largest coldkeys' alpha together, alpha rao (at most total_alpha_rao).

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

The fewest coldkeys holding more than half the alpha (0 without a holder; at most 10 exactly when top10_alpha_rao is more than half, checked).

hhi_ratiostring · unit ratio · 8 decimals · can be null

Normalised Herfindahl-Hirschman index over the coldkeys' alpha, 0..1, 8 decimals (0 = spread evenly, 1 = one holder). Null when the source has none.

Format: decimal number, as a string
validator_permitsinteger · unit count · can be null

UIDs holding a validator permit at the day's end. Null while the day's neuron data isn't available yet.

generationinteger · unit id · can be null

Opaque life id (the life's registration identifier), NOT a block height; use life_start_height for the first block. The subnet life served (GET /subnets/generations). A netuid is a slot: a re-registered subnet is a new life, and this series covers the current one only. Null when the slot has no recorded life (root) and on an older data version's answer.

is_current_lifeboolean · can be null

Whether generation is the slot's current life (true) or an ended one, re-registered since (false). Null exactly when generation is null, or transiently when this API cannot read the lives. Root's generation 0 is current.

life_start_heightinteger · unit block · can be null

The served life's first block. Null exactly when generation is null.

life_first_daystring (date) · can be null

The served life's first whole UTC day (the day after its first block's day, which also holds the previous life's blocks): the days start here. Null without a life (or when its first block's time is unknown), and on an older data version's answer.

Format: date, YYYY-MM-DD
distributionarray of objects · can be null

include=distribution (GET /subnets/{netuid}/holders/daily only): the life's stake distribution per closed day of the page, oldest first: the Gini coefficient, the top-10 share, the holdings' TAO value and its percentiles. It ends at meta.sections.distribution.through_day (each day is computed after it closes, so its newest day may trail days); a day with no holder has no row. Null when the section is unavailable (meta.sections.distribution.unavailable_reason); absent without the include.

11 fields in distribution (each item)
daystring (date)

The closed UTC day; every figure is at its last block.

Format: date, YYYY-MM-DD
day_end_heightinteger · unit block

The day's last block.

holdersinteger · unit count

Coldkeys holding the life's alpha (> 0, summed over their hotkeys): the holder figure's population.

alpha_raostring · unit alpha_rao (÷1e9)

Their alpha together, alpha rao.

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

That alpha's TAO value at the day's close, rao. Null when any holding could not be priced (unpriced_holders > 0): a partial total is never served.

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

Holdings whose value is unknown that day (no close price): left out of the value figures, never counted as 0.

top10_share_ratiostring · unit ratio · 6 decimals · can be null

The 10 largest holders' share of the alpha, 0..1, 6 decimals. Null without alpha.

Format: decimal number with 6 places, as a string
gini_ratiostring · unit ratio · 6 decimals

The Gini coefficient of the holders' alpha, 0..1, 6 decimals (0 = evenly held, near 1 = one holder).

Format: decimal number with 6 places, as a string
value_p50_tao_raostring · unit rao (÷1e9) · can be null

The median holding's TAO value at the close, rao. Linear interpolation between closest ranks (R-7), floored to rao, over the priced holdings only. Null when fewer than 50 holdings are priced: a small population's high percentile would be one holder's exact holding.

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

The 90th percentile of the holdings' TAO value, rao. Linear interpolation between closest ranks (R-7), floored to rao, over the priced holdings only. Null when fewer than 50 holdings are priced: a small population's high percentile would be one holder's exact holding.

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

The 99th percentile of the holdings' TAO value, rao. Linear interpolation between closest ranks (R-7), floored to rao, over the priced holdings only. Null when fewer than 50 holdings are priced: a small population's high percentile would be one holder's exact holding.

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.