Skip to content
TAO$188.36
BTC0.002929
MCap$2.22B
Vol$86.25M

API reference / Network

The network's stake distribution and capital rotation between subnets, per closed UTC day

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

The network stake page in one call, from the analytics store (aggregates and distributions only: no wallet is listed or ranked).

Full description

The network stake page in one call, from the analytics store (aggregates and distributions only: no wallet is listed or ranked). include picks the sections (default both):

- distribution: per closed UTC day, how the staked value is spread over wallets, in two scopes never blended: all (each wallet's holdings on every subnet, root included, in TAO at the day's close) and alpha (subnet holdings only, netuid >= 1). Per day: wallets, their total value, the top-10 share and Gini coefficient of the priced wallets' value, and its p50 / p90 / p99 (null under 50 priced wallets). A wallet with an unpriced holding is counted in unpriced_holders and left out of the value figures; the total is null then (never a partial sum). - rotation: per UTC day or ISO week (interval) and subnet life, the capital moved into and out of its stake (stake, unstake, swaps between subnets, stake transfers, dissolution payouts), in alpha and in TAO at each day's own close, the non-capital movements apart (other_net_alpha_rao) and every movement kind's amounts. A week the window or the store cuts is partial.

The window is from_day..to_day (UTC days, inclusive; default the 30 days ending yesterday), at most 400 days, and at most 92 for a daily rotation. Each section ends at its own meta.sections.<name>.through_day, the store's newest closed day (each day is computed after it closes). A section never fails the call: when it cannot be served it is null and meta.sections.<name>.unavailable_reason says why (not_ready, stale when the store is more than 6 hours overdue, source_unavailable). Where this deployment does not read stake history from the analytics store the route is a 503 SOURCE_NOT_READY. A pinned window of past days served whole is cached as settled, anything else as slow. Errors are application/problem+json: INVALID_DAY, INVALID_RANGE, INVALID_INTERVAL, INVALID_INCLUDE, UNKNOWN_PARAMETER, 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

includequery· string

The sections, a comma list (or the parameter repeated): distribution, rotation. Default both. Anything else is a 400 INVALID_INCLUDE.

intervalquery· enum · one of 1d, 1w · default 1d

The rotation's bucket: 1d (UTC day, the default) or 1w (ISO week, Monday UTC; bucket_start is its Monday). Anything else is a 400 INVALID_INTERVAL.

from_dayquery· string (date)

The first UTC day, YYYY-MM-DD, inclusive (default: 29 days before to_day). Not a date, or outside 1970-01-01..2149-06-06: a 400 INVALID_DAY.

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

The last UTC day, YYYY-MM-DD, inclusive (default: yesterday, UTC). Before from_day, or a window over 400 days (92 with a daily rotation): a 400 INVALID_RANGE.

Format: date, YYYY-MM-DD

Response

data is an object 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 sections asked for.

distributionobject · can be null

include=distribution: the network's stake distribution per day, in both scopes. Present when asked; null when unavailable (meta.sections.distribution.unavailable_reason).

2 fields in distribution
allarray of objects

Each wallet's holdings on every subnet, root included, valued in TAO: one row per closed day in the window up to meta.sections.distribution.through_day, oldest first.

10 fields in all (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 with any holding in the scope.

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

Their holdings' TAO value at the day's close together, rao. Null when any wallet holds an unpriced holding (unpriced_holders > 0): a partial total is never served.

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

Wallets with a holding whose value is unknown that day: their value is unknown, so they are left out of the value figures below, never counted as 0.

top10_share_ratiostring · unit ratio · 6 decimals · can be null

The 10 largest priced wallets' share of the priced value, 0..1, 6 decimals. Null when no wallet is priced.

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

The Gini coefficient of the priced wallets' value, 0..1, 6 decimals. Null when no wallet is priced.

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

The median priced wallet's TAO value, rao. Linear interpolation (R-7), floored to rao; null under 50 priced wallets.

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

The 90th percentile of the priced wallets' TAO value, rao (as value_p50_tao_rao).

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

The 99th percentile of the priced wallets' TAO value, rao (as value_p50_tao_rao).

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

Each wallet's subnet holdings only (netuid >= 1, the subnet-direct option), valued in TAO: the same days. A wallet holding root only is not in this scope.

10 fields in alpha (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 with any holding in the scope.

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

Their holdings' TAO value at the day's close together, rao. Null when any wallet holds an unpriced holding (unpriced_holders > 0): a partial total is never served.

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

Wallets with a holding whose value is unknown that day: their value is unknown, so they are left out of the value figures below, never counted as 0.

top10_share_ratiostring · unit ratio · 6 decimals · can be null

The 10 largest priced wallets' share of the priced value, 0..1, 6 decimals. Null when no wallet is priced.

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

The Gini coefficient of the priced wallets' value, 0..1, 6 decimals. Null when no wallet is priced.

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

The median priced wallet's TAO value, rao. Linear interpolation (R-7), floored to rao; null under 50 priced wallets.

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

The 90th percentile of the priced wallets' TAO value, rao (as value_p50_tao_rao).

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

The 99th percentile of the priced wallets' TAO value, rao (as value_p50_tao_rao).

Format: whole number, as a string · on chain: u64
rotationarray of objects · can be null

include=rotation: capital rotation per bucket and subnet life, by bucket, then netuid, then life. A bucket and life without movement has no row. Present when asked; null when unavailable (meta.sections.rotation.unavailable_reason).

19 fields in rotation (each item)
bucket_startstring (date)

The UTC day (1d), or the ISO week's Monday (1w).

Format: date, YYYY-MM-DD
partialboolean

True when the window or the store's watermark cuts the week (1w only): its sums cover only the days served. Always false for 1d.

netuidinteger · unit id

The subnet slot (0 = root).

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 the movements belong to (GET /subnets/generations). A re-registered slot's lives are separate rows, never blended; on a life's end day the ended life's movements (its dissolution payouts and its holders' trades) are its own row. Null when the slot has no recorded life (root).

life_start_heightinteger · unit block · can be null

The first block of the life generation names (GET /subnets/generations' start_height): use it, never generation, for heights, ages and dates. Null exactly when generation is null (root without a life, no subnet), or transiently when this API cannot read the lives. Root's generation 0 starts at 0.

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.

net_alpha_raostring · unit alpha_rao (÷1e9)

Net capital into the life's stake (in_alpha_rao + out_alpha_rao), alpha rao, signed. Capital = the movements the portfolio decomposition puts in its flow bucket: stake, unstake, swaps between subnets, stake transfers, dissolution payouts.

Format: whole number, as a string · can be negative
in_alpha_raostring · unit alpha_rao (÷1e9)

The capital movements into the stake, alpha rao (>= 0).

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

The capital movements out of the stake, alpha rao, signed: 0 or negative (net = in + out).

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

net_alpha_rao in TAO, each day's movements valued at that day's own close (floored per wallet and day), rao, signed. Null when a capital movement had no close price (always on a life's end day: an ended life has no close to value it at).

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

in_alpha_rao in TAO at each day's close, rao. Null as net_tao_rao.

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

out_alpha_rao in TAO at each day's close, rao, signed (<= 0). Null as net_tao_rao.

Format: whole number, as a string · can be negative
other_net_alpha_raostring · unit alpha_rao (÷1e9)

Net non-capital movements, alpha rao, signed: hotkey swaps, migrations, dust, automatic claims, the escrow's legs and kinds not classified yet. Not part of net_alpha_rao.

Format: whole number, as a string · can be negative
movesinteger · unit count

Wallet-days with a movement in the bucket (one per wallet and day).

net_alpha_by_kindobject

Every movement kind's net amount, alpha rao, signed, keyed by kind: <kind> for an extrinsic's movements, <kind>:hook for a block hook's. A kind netting to 0 over the bucket is omitted. Capital and non-capital kinds alike: they sum to net_alpha_rao + other_net_alpha_rao. Kinds are data: clients must accept kinds not documented yet.

in_alpha_by_kindobject

Every kind's inflows, alpha rao (as net_alpha_by_kind).

out_alpha_by_kindobject

Every kind's outflows, alpha rao, signed (as net_alpha_by_kind).

life_endboolean

True when the bucket holds the life's end day (its last movements are unvalued: the TAO members are null when they are capital).

day_end_heightinteger · unit block

The last block of the bucket's last day served.

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.