The network's stake distribution and capital rotation between subnets, per closed UTC day
https://api.bittensor.ai/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 400INVALID_INCLUDE.- intervalquery· enum · one of 1d, 1w · default 1d
The rotation's bucket:
1d(UTC day, the default) or1w(ISO week, Monday UTC;bucket_startis its Monday). Anything else is a 400INVALID_INTERVAL.- from_dayquery· string (date)
The first UTC day,
YYYY-MM-DD, inclusive (default: 29 days beforeto_day). Not a date, or outside 1970-01-01..2149-06-06: a 400INVALID_DAY.- Format: date, YYYY-MM-DD
- to_dayquery· string (date)
The last UTC day,
YYYY-MM-DD, inclusive (default: yesterday, UTC). Beforefrom_day, or a window over 400 days (92 with a daily rotation): a 400INVALID_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.
- 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.
- 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 (
1wonly): its sums cover only the days served. Always false for1d.- 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_heightfor 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
generationnames (GET /subnets/generations'start_height): use it, nevergeneration, for heights, ages and dates. Null exactly whengenerationis null (root without a life, no subnet), or transiently when this API cannot read the lives. Root'sgeneration0 starts at 0.- is_current_lifeboolean · can be null
Whether
generationis the slot's current life (true) or an ended one, re-registered since (false). Null exactly whengenerationis null, or transiently when this API cannot read the lives. Root'sgeneration0 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_raoin 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_raoin TAO at each day's close, rao. Null asnet_tao_rao.- Format: whole number, as a string · on chain: u64
- out_tao_raostring · unit rao (÷1e9) · can be null
out_alpha_raoin TAO at each day's close, rao, signed (<= 0). Null asnet_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>:hookfor a block hook's. A kind netting to 0 over the bucket is omitted. Capital and non-capital kinds alike: they sum tonet_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), 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.
- AMBIGUOUS_CREDENTIALS
- BAD_GATEWAY
- BILLING_UNAVAILABLE
- BUDGET_EXCEEDED
- CONCURRENCY_LIMIT
- INSUFFICIENT_PERMISSIONS
- INTERNAL_ERROR
- INVALID_DAY
- INVALID_INCLUDE
- INVALID_INTERVAL
- INVALID_RANGE
- 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.