Skip to content
TAO$188.40
BTC0.00293
MCap$2.21B
Vol$86.07M

API reference / Subnets

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

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

Per closed UTC day, oldest first, at the day's last block.

Full description

Per closed UTC day, oldest first, at the day's last block: the coldkeys holding the subnet's alpha (holder_count), the delegates (delegate_count: the hotkeys holding a share from a coldkey other than their Owner, null before meta.delegate_count_from_day; on an older data version's answer the hotkeys with a staker), the (hotkey, coldkey) positions, the alpha staked (total_alpha_rao), the largest position, the 10 largest coldkeys' alpha, nakamoto, the normalised HHI and the validator permits. The delegates, positions and largest position come from the pools' day-end stakers: null on a day where they cannot be whole, never a 0 standing in. A subnet without holder rows in the window answers [] with meta.missing_netuids = [netuid]. 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 the subnet's current life with rows or not. include=distribution adds the analytics store's stake distribution of the series' life over the same days (data[].distribution: per closed day the Gini coefficient and top-10 share of the holders' alpha, the holdings' TAO value at the close, its p50 / p90 / p99 (null under 50 priced holdings) and the unpriced holdings; never a holder list), its day watermark in meta.sections.distribution and both stores in meta.sources. The holder figures stay the chain database's. Each day is computed after it closes, so its newest day can trail the page's. The section never fails the call: when it cannot be served it is null and meta.sections.distribution.unavailable_reason says why (not_enabled where this deployment does not read it, not_ready, stale when the store is more than 6 hours overdue, source_unavailable, no_series); the answer is then cached as slow. Errors are application/problem+json: INVALID_NETUID, INVALID_DAYS, INVALID_DAY, INVALID_RANGE, INVALID_CURSOR, INVALID_INCLUDE, 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).

Path parameters

netuidpath, required· integer · 0 to 65535

Subnet slot (0 = root).

Query parameters

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.

includequery· string

distribution: add the life's stake distribution per day from the analytics store (data[].distribution, meta.sections.distribution). Anything else 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 subnet's series (one item), or [] when it has no holder rows in the window.

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.