Skip to content
TAO$189.03
BTC0.002931
MCap$2.22B
Vol$87.61M

API reference / Subnets

Every validator pool on a subnet quoted at one stake amount: its yield before and after the stake

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

The validator picker: every staking pool on the subnet, each quoted at the same amount_rao TAO.

Full description

The validator picker: every staking pool on the subnet, each quoted at the same amount_rao TAO. Per row (the base members): the pool's nominator APY before the stake (nominator_apy_ratio), the stake's own APY and APR after it dilutes the pool by the multiplier M (apy_at_amount_ratio, apr_at_amount_ratio), the same in TAO terms, the stake in the pool's alpha (stake_alpha_rao), the small-pool tier and the model's inputs; null on a pool with no figures for data.day. Options, beside them, one option per answer (data.option): on a subnet (option C) each row's identity name, takes, permit, activity, pool size and stakers, pool (the pool's own 7-day APY, TAO APR and price change, RatioFigures) and at_amount on the no-dilution bound, an UPPER bound, never an expected yield, with this API's breakeven_days (a LOWER bound) and breakeven_state; on root (option A) each root validator's or fund's holder-true accrual and the amount's (an upper bound), the 7-day sell gate, what the accrual sits in (unclaimed_exposure, option B's figures, never added) and the two risks. Computed by this API: data.cost (the swap cost of the amount now, one per subnet, which each breakeven divides), data.fv_level (the pool's fair-value level; L3 under 1 alpha in reserve, an empty pool included) and the risk flag thin_pool on an L3 pool, and each row's exit. Rows are in sort / order (nulls last, then the larger pool, then the hotkey; the old spellings order=<key> and dir are still accepted); never average rates across rows. Yields are alpha-denominated and net of take; on root the rate is accrued, never an amount. Tip-cached (the cost is read at the head). Errors are application/problem+json: INVALID_AMOUNT, INVALID_SORT, INVALID_ORDER, INVALID_DIR, NOT_FOUND (404: no pool on the subnet), SUBNET_NOT_FOUND (404), UNKNOWN_PARAMETER, SOURCE_TIMEOUT (503), 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).

Path parameters

netuidpath, required· integer · 0 to 65535

Subnet slot (0 = root).

Query parameters

amount_raoquery· string

Required: the TAO staked, a decimal integer 1..1000000000000000000 in rao. Anything else is a 400 INVALID_AMOUNT.

sortquery· enum · one of apy_at_amount, tao_apr_at_amount, breakeven_days, pool_stake, take, root_stake

The rows' key (sent only when given). On a subnet: apy_at_amount (the default), tao_apr_at_amount, breakeven_days (ascending by default), pool_stake, take (ascending by default); on root: apy_at_amount (the default), take (ascending by default), root_stake. Anything else, or a key of the other kind of pool, is a 400 INVALID_SORT.

orderquery· enum · one of asc, desc

The direction, asc or desc (default: the key's; nulls last either way; sent only when given). Anything else is a 400 INVALID_ORDER.

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 quotes.

optionenum

The option every row is: subnet_stake (option C, netuid >= 1) or root_stake (option A, netuid 0); the rows' option members are that option's (checked).

One of: subnet_stake, root_stake
netuidinteger · unit id

The subnet slot.

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's current life. Null on root and older answers.

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.

daystring (date) · can be null

The per-day members' day: the latest available (every pool's day end). Null when no such day is available yet (the option members carry their own as_of_day).

Format: date, YYYY-MM-DD
amount_tao_raostring · unit rao (÷1e9)

The TAO staked, rao (the request's amount_rao).

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

The subnet's alpha spot at the day end, rao of TAO per 1 alpha (per 1e9 alpha rao), floor(price x 1e9): the runtime price truncated to a whole rao (root 1e9). Null without one.

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

SubnetTAO at the head, the pool's depth, rao. Null on root and older answers.

Format: whole number, as a string · on chain: u64
orderenum · can be null

The order served (the request's sort, default apy_at_amount). Null on an older data version's answer (best apy_at_amount_ratio first).

One of: apy_at_amount, tao_apr_at_amount, breakeven_days, pool_stake, take, root_stake
direnum · can be null

The direction served (the request's order, default asc for take and breakeven_days, else desc); nulls last either way. Null on an older answer.

One of: asc, desc
costobject

Computed by this API: staking the amount and unstaking it through the subnet's pool now (the swap model at cost.state_height, as /hotkeys/{hotkey}/stake-quote's cost). One per subnet: the same for every row, which each row's breakeven divides. 0 on root.

9 fields in cost
round_trip_cost_ratiostring · unit ratio · 8 decimals · can be null

1 - tao_back_rao / amount_tao_rao: staking the amount and unstaking the alpha it buys, both legs against the pool at state_height (fees and slippage), 8 decimals. 0 on a stable subnet (root). Null with unavailable_reason.

Format: decimal number, as a string
entry_cost_ratiostring · unit ratio · 8 decimals · can be null

1 - alpha_out_rao x spot / amount_tao_rao: the stake's loss against the pool's spot price (fee and slippage), 8 decimals. 0 on a stable subnet. Null with unavailable_reason.

Format: decimal number, as a string
exit_cost_ratiostring · unit ratio · 8 decimals · can be null

1 - tao_back_rao / (alpha_out_rao x spot): the unstake's loss against spot, 8 decimals. 0 on a stable subnet. Null with unavailable_reason.

Format: decimal number, as a string
alpha_out_raostring · unit alpha_rao (÷1e9) · can be null

The alpha the amount buys, alpha rao of this subnet (after the fee). Null with a reason.

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

The TAO that alpha sells back for against the same pool state, rao. Null with a reason.

Format: whole number, as a string · on chain: u64
state_heightinteger · unit block · can be null

The block of the pool inputs (state.pool.state_height).

mechanismstring · can be null

The curve modelled (state.pool.swap_mechanism). Known values: stable, constant_product, concentrated_liquidity, balancer. New values may be added; show an unknown value as is (or generically).

sourcestring

Always model: computed by this API from the raw chain inputs. New values may be added; show an unknown value as is (or generically).

unavailable_reasonstring · can be null

Why every figure is null; null when they are given. One of no_state (state is null: include=state not asked, or an at off the head), mechanism_unknown (swap_mechanism null), unsupported_mechanism (constant_product or concentrated_liquidity: only the balancer and stable curves are modelled), inputs_missing (a reserve, the fee rate or the Balancer weight is null or out of range), no_reference_stake (no reference stake to cost), subtoken_disabled (hyperparams.subtoken_enabled is false, or the row's cost_unavailable_reason is staking_disabled: the chain refuses stakes and unstakes there) or swap_refused (the chain would refuse this swap: no output, or a net input over 1000 x the input reserve). New values may be added; treat unknown values as unavailable.

fv_levelstring · can be null

Computed by this API. The pool's fair-value level (valuation standard 2026-09-23, standard_version 1; computed by this API from the subnet's alpha reserve at the head, cost.state_height): L1 when a reference sale of 10 alpha moves the price by less than 1 % (10 / (alpha reserve + 10), no fee) and the reserve holds at least 1,000 alpha; L2 when it holds at least 1 alpha; else L3 (less than 1 alpha, an alpha reserve of 0 or a TAO reserve of 0 included: a thin pool, valued at a measured Level 3 value). A pool property, independent of the amount. Null when the pool has no reserve stated (no state, unpriced) and on root. New values may be added; show an unknown value as is (or generically).

subnet_stake_weightstring · unit alpha_rao (÷1e9) · can be null

S, alpha-equivalent rao: the subnet's latest epoch stake weight, each UID's alpha + TaoWeight x root stake (the filtered stake vector), summed; it is added to X (alpha rao) in S / (S + X) (all_to_children pools dilute through it). Null before the subnet's first epoch.

Format: decimal number, as a string
rowsarray of objects

Every pool on the subnet (every pool with stake now on a subnet, every root validator or fund on root) in order / dir, nulls last, ties by the larger pool then the hotkey; on an older data version's answer every pool with figures at day, best apy_at_amount_ratio first (nulls last), then the larger pool.

35 fields in rows (each item)
hotkeystring

The validator hotkey, SS58 (prefix 42).

Format: SS58 address
stake_alpha_raostring · unit alpha_rao (÷1e9) · can be null

X: the amount in the pool's alpha at the day-end spot (root: TAO 1:1), floored. Null without a spot.

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

The pool's alpha spot at its window's open (the day end inputs.days days before), rao of TAO per 1 alpha (per 1e9 alpha rao), floor(price x 1e9): the runtime price truncated to a whole rao (root 1e9). Null without one.

Format: whole number, as a string · on chain: u64
modelstring · can be null

The dilution model: root, all_to_children or standard. Null on a row whose pool has no figures for data.day (a pool newer than that day: these per-day members are null too). New values may be added; show an unknown value as is (or generically).

inputsobject · can be null

The pool's model inputs. Null with model.

10 fields in inputs
alpha_raostring · unit alpha_rao (÷1e9)

A: TotalHotkeyAlpha(hotkey, netuid) at the day end, alpha rao.

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

The hotkey's root stake at the day end, rao.

Format: whole number, as a string · on chain: u64
tao_weightstring · unit ratio

TaoWeight: how much root stake counts on a subnet (R = root x it).

Format: decimal number, as a string
s_fracstring · unit ratio

The hotkey's own share of its gross dividends there (0: all to children).

Format: decimal number, as a string
k_fracstring · unit ratio

Its childkeys' share of the stake weight (K = k_frac x T).

Format: decimal number, as a string
subnet_stake_weightstring · unit alpha_rao (÷1e9) · can be null

S, alpha-equivalent rao: the subnet's latest epoch stake weight, each UID's alpha + TaoWeight x root stake (the filtered stake vector), summed; it is added to X (alpha rao) in S / (S + X). Only for an all_to_children pool (null otherwise).

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

The return's window in days. Null when refused.

y_returnstring · unit ratio · can be null

y: the per-share return over the window, net of take (root: the accrued root claimable over the root stake, a rate basis, never a total). Null when refused.

Format: decimal number, as a string · can be negative
y_basisstring

What y is measured on. Known values: share_index, root_claimable. New values may be added; show an unknown value as is (or generically).

refusedstring · can be null

Why the return is not rated, in the source's words; null when rated.

multiplierstring · unit ratio · 12 decimals · can be null

M: the stake's dilution of the per-share return, 12 decimals. Null with pool_unpriced, not_ready or pool_refused.

Format: decimal number, as a string · can be negative
stake_tierstring · can be null

low when the pool's own stake A is below X, else normal. Null without X. New values may be added; show an unknown value as is (or generically).

nominator_apy_ratiostring · unit ratio · 8 decimals · can be null

(1 + y)^(365 / days) - 1: the pool's APY before the stake.

Format: decimal number, as a string · can be negative
apy_at_amount_ratiostring · unit ratio · 8 decimals · can be null

(1 + y M)^(365 / days) - 1: the stake's APY after joining.

Format: decimal number, as a string · can be negative
apr_at_amount_ratiostring · unit ratio · 8 decimals · can be null

y M x 365 / days: the stake's APR (a breakeven's rate: round-trip cost / (this / 365)).

Format: decimal number, as a string · can be negative
nominator_tao_apr_ratiostring · unit ratio · 8 decimals · can be null

TAO terms before the stake: ((1 + y) x spot / window-open spot - 1) x 365 / days.

Format: decimal number, as a string · can be negative
tao_apy_at_amount_ratiostring · unit ratio · 8 decimals · can be null

TAO terms at the amount: ((1 + y M) x spot / window-open spot)^(365 / days) - 1.

Format: decimal number, as a string · can be negative
tao_apr_at_amount_ratiostring · unit ratio · 8 decimals · can be null

TAO terms at the amount: ((1 + y M) x spot / window-open spot - 1) x 365 / days.

Format: decimal number, as a string · can be negative
unavailable_reasonstring · can be null

Why rates are null: pool_refused (the pool's return over the window is not rated: no share-index history, a format change, ...; every rate null), parent_set_unknown (the pool carries material childkey take, so its yield is rated over 1 day only until its per-day parent sets are stored: every annualised rate null), window_too_short (the pool's window is shorter than its full window, 7 days or root's 30, a younger pool: every annualised rate null), pool_unpriced (no spot price or no own share for the multiplier: the pool's own rates stand, the stake's are null), not_ready (the day's stake weights are not available yet: as pool_unpriced, the pool's own rates stand, the stake's are null) or root_basis_pending (a root pool rated on its flat share price instead of the accrued root claimable: every rate null, never a 0 % APY). Null when every rate is given. New values may be added; treat unknown values as unavailable.

identity_namestring · can be null

The hotkey's identity name (its own, else its owner coldkey's). Null without one, and on an older data version's answer.

take_ratiostring · unit ratio · 6 decimals · can be null

The hotkey's Delegates take at the head, 0..1 (6 decimals); the take order's key. Null on an older answer.

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

Subnet rows: the effective childkey take here, max(stored, floor), 0..1. Null on root rows and on an older answer.

Format: decimal number, as a string
validator_permitboolean · can be null

Subnet rows: a validator permit on the subnet now. Null on root rows and older answers.

consistently_activeboolean · can be null

Subnet rows: Active at every day end of the 7-day window. Null with no covered day, on root rows and on an older answer.

pool_alpha_raostring · unit alpha_rao (÷1e9) · can be null

Subnet rows: TotalHotkeyAlpha now, the pool's size (the pool_stake order's key). Null on root rows and older answers.

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

Subnet rows: the pool at spot, rao of TAO. Null when unpriced, on root rows and older.

Format: whole number, as a string · on chain: u64
staker_countinteger · unit count · can be null

Subnet rows: coldkeys with a share in the pool. Null on root rows and older answers.

poolobject · can be null

Subnet rows: the pool's own 7-day rates (alpha APY, TAO APR, the price's change). Null on root rows and older answers.

3 fields in pool
apy_7dobject

The pool's per-share growth over 7 whole days to as_of_day, compounded (APY): alpha terms, net of take, no price term. Reasons: not_ready, insufficient_history, no_pool, no_permit, pool_not_alive, pool_refused (checked).

tao_apr_7dobject

The same in TAO terms, simple: ((1 + y) x spot at the end / spot at the open - 1) x 365 / 7. Includes the alpha price's move. apy_7d's reasons, plus price_unknown.

alpha_price_change_7dobject

The alpha spot at the window's end over its open, minus 1 (a period change): the price risk on its own. Reasons: not_ready, insufficient_history, price_unknown.

at_amountobject · can be null

Subnet rows: the stake at the amount on the no-dilution bound, with its breakeven. An UPPER bound, never an expected yield. Null on root rows and older answers.

11 fields in at_amount
modelstring

Always no_dilution_bound: the stake does not dilute the pool's per-share return.

boundstring

Always upper. An UPPER bound, never an expected yield (model no_dilution_bound): the stake is assumed not to change the pool's per-share return, but under Yuma it falls by about S / (S + X) and bonds lag, so the real figure is lower.

stake_alpha_raostring · unit alpha_rao (÷1e9) · can be null

X: the amount in the pool's alpha at the head spot, floored. Null without a spot.

Format: whole number, as a string · on chain: u64
stake_tierstring · can be null

low when the pool's own stake (pool_alpha_rao) is below X (the stake would be most of the pool), else normal (checked). Null without X. New values may be added; show an unknown value as is (or generically).

apyobject

The stake's APY at the amount: equal to the pool's apy_7d (checked). An UPPER bound, never an expected yield (model no_dilution_bound): the stake is assumed not to change the pool's per-share return, but under Yuma it falls by about S / (S + X) and bonds lag, so the real figure is lower.

aprobject

The same as a simple rate, y x 365 / 7 (the breakeven's rate; consistent with apy, checked). An UPPER bound, never an expected yield (model no_dilution_bound): the stake is assumed not to change the pool's per-share return, but under Yuma it falls by about S / (S + X) and bonds lag, so the real figure is lower.

tao_apyobject

In TAO terms, compounded, with the alpha price's move over the window. price_unknown without a spot at both ends. An UPPER bound, never an expected yield (model no_dilution_bound): the stake is assumed not to change the pool's per-share return, but under Yuma it falls by about S / (S + X) and bonds lag, so the real figure is lower.

tao_aprobject

In TAO terms, simple. An UPPER bound, never an expected yield (model no_dilution_bound): the stake is assumed not to change the pool's per-share return, but under Yuma it falls by about S / (S + X) and bonds lag, so the real figure is lower.

breakeven_daysstring · unit days · 2 decimals · can be null

Computed by this API: data.cost.round_trip_cost_ratio / (apr.value / 365), 2 decimals: the days the stake must stay to earn back its round trip. A LOWER bound (the APR is an upper bound). Null unless breakeven_state is days.

Format: decimal number, as a string · can be negative
breakeven_statestring

days when computed; never when the APR is not above 0 (it never earns the cost back); unknown when the cost or the APR is null. Known values: days, never, unknown, not_applicable. New values may be added; show an unknown value as is (or generically).

breakeven_boundstring · can be null

lower beside a breakeven_days (the opposite of bound); null otherwise.

riskobject · can be null

Subnet rows: option C's risk (high; thin_pool added by this API when data.fv_level is L3). Null on root rows and older answers.

4 fields in risk
labelstring

The option's fixed label (root principal low, root accrual medium, fund units high); it never depends on data. Known values: low, medium, high, very_high. New values may be added; show an unknown value as is (or generically).

flagsarray of string

Window-free chain facts about this option (closed per option, checked; e.g. take_raised_30d, take_also_on_fund_holdings, trading_frozen, provisional). Never a judgement threshold. [] when none. Known values: take_raised_30d, take_also_on_fund_holdings, sell_gate_closed_in_window, lost_root_uid_in_window, trading_frozen, written_off_in_window, holdings_below_cap_minimum, provisional, thin_pool, no_permit_in_window, subtoken_disabled, stake_tier_low, perpetual_lock, lock_exceeds_holdings. New values may be added; show an unknown value as is (or generically).

flags_7darray of string · optional

The flags over the block's 7-day window (lost_root_uid_in_window, sell_gate_closed_in_window, written_off_in_window). Absent on a block with no figure over that window. Known values: take_raised_30d, take_also_on_fund_holdings, sell_gate_closed_in_window, lost_root_uid_in_window, trading_frozen, written_off_in_window, holdings_below_cap_minimum, provisional, thin_pool, no_permit_in_window, subtoken_disabled, stake_tier_low, perpetual_lock, lock_exceeds_holdings. New values may be added; show an unknown value as is (or generically).

flags_30darray of string · optional

The same over the 30-day window. Known values: take_raised_30d, take_also_on_fund_holdings, sell_gate_closed_in_window, lost_root_uid_in_window, trading_frozen, written_off_in_window, holdings_below_cap_minimum, provisional, thin_pool, no_permit_in_window, subtoken_disabled, stake_tier_low, perpetual_lock, lock_exceeds_holdings. New values may be added; show an unknown value as is (or generically).

has_root_uidboolean · can be null

Root rows: the hotkey holds a root UID. Null on subnet rows and older answers.

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

Root rows: the hotkey's root stake (the root_stake order's key), rao. Null on subnet rows and older answers.

Format: whole number, as a string · on chain: u64
accrualobject · can be null

Root rows: option A's holder-true accrual and the amount's (an upper bound). Null on subnet rows and older answers.

4 fields in accrual
basisstring

Always root_claimable_holder: the accrued claimable, holder-true. New values may be added; show an unknown value as is (or generically).

pool_apy_7dobject

Option A's 7-day accrual APY on the hotkey (root_stake.apy_7d); A's reasons (checked).

pool_apy_30dobject

The same over 30 days.

at_amountobject

The accrual at the amount, an upper bound.

sell_gate_7dobject · can be null

Root rows: the root-sell gate over the 7-day window. Null on subnet rows and older.

5 fields in sell_gate_7d
gate_open_blocksstring · unit blocks · can be null

Blocks of the window whose gate was open (root accrues only then), a u64 string, at most window_blocks (checked); fewer than it sets the accrual risk's sell_gate_closed_in_window for this window, and 0 is what the window's rate's sell_gate_closed means (both checked). Null with not_ready.

Format: whole number, as a string
window_blocksstring · unit blocks · can be null

The window's blocks (after from_day's close through to_day's), a u64 string. Null with not_ready.

Format: whole number, as a string
from_daystring (date) · can be null

The window's first UTC day end.

Format: date, YYYY-MM-DD
to_daystring (date) · can be null

Its last UTC day end.

Format: date, YYYY-MM-DD
unavailable_reasonstring · can be null

not_ready while a day of the window isn't available yet: every other member null. New values may be added; treat unknown values as unavailable.

unclaimed_exposureobject · can be null

Root rows: the fund the accrual sits in (B's figures, never added to A's). Null when the hotkey runs no fund, on subnet rows and older answers.

3 fields in unclaimed_exposure
fund_statestring · can be null

The fund's state. Known values: dissolved, no_state, off_root, active. New values may be added; show an unknown value as is (or generically).

fund_holder_return_30dobject · can be null

Option B's 30-day holder return (a period return); B's reasons (checked). Never added to A.

nav_haircut_ratiostring · unit ratio · 8 decimals · can be null

1 - realizable / spot NAV: the liquidation discount the accrual is exposed to, 8 decimals. Null without both NAVs.

Format: decimal number, as a string · can be negative
risk_principalobject · can be null

Root rows: the principal's risk (low). Null on subnet rows and older answers.

4 fields in risk_principal
labelstring

The option's fixed label (root principal low, root accrual medium, fund units high); it never depends on data. Known values: low, medium, high, very_high. New values may be added; show an unknown value as is (or generically).

flagsarray of string

Window-free chain facts about this option (closed per option, checked; e.g. take_raised_30d, take_also_on_fund_holdings, trading_frozen, provisional). Never a judgement threshold. [] when none. Known values: take_raised_30d, take_also_on_fund_holdings, sell_gate_closed_in_window, lost_root_uid_in_window, trading_frozen, written_off_in_window, holdings_below_cap_minimum, provisional, thin_pool, no_permit_in_window, subtoken_disabled, stake_tier_low, perpetual_lock, lock_exceeds_holdings. New values may be added; show an unknown value as is (or generically).

flags_7darray of string · optional

The flags over the block's 7-day window (lost_root_uid_in_window, sell_gate_closed_in_window, written_off_in_window). Absent on a block with no figure over that window. Known values: take_raised_30d, take_also_on_fund_holdings, sell_gate_closed_in_window, lost_root_uid_in_window, trading_frozen, written_off_in_window, holdings_below_cap_minimum, provisional, thin_pool, no_permit_in_window, subtoken_disabled, stake_tier_low, perpetual_lock, lock_exceeds_holdings. New values may be added; show an unknown value as is (or generically).

flags_30darray of string · optional

The same over the 30-day window. Known values: take_raised_30d, take_also_on_fund_holdings, sell_gate_closed_in_window, lost_root_uid_in_window, trading_frozen, written_off_in_window, holdings_below_cap_minimum, provisional, thin_pool, no_permit_in_window, subtoken_disabled, stake_tier_low, perpetual_lock, lock_exceeds_holdings. New values may be added; show an unknown value as is (or generically).

risk_accrualobject · can be null

Root rows: the accrual's risk (medium). Null on subnet rows and older answers.

4 fields in risk_accrual
labelstring

The option's fixed label (root principal low, root accrual medium, fund units high); it never depends on data. Known values: low, medium, high, very_high. New values may be added; show an unknown value as is (or generically).

flagsarray of string

Window-free chain facts about this option (closed per option, checked; e.g. take_raised_30d, take_also_on_fund_holdings, trading_frozen, provisional). Never a judgement threshold. [] when none. Known values: take_raised_30d, take_also_on_fund_holdings, sell_gate_closed_in_window, lost_root_uid_in_window, trading_frozen, written_off_in_window, holdings_below_cap_minimum, provisional, thin_pool, no_permit_in_window, subtoken_disabled, stake_tier_low, perpetual_lock, lock_exceeds_holdings. New values may be added; show an unknown value as is (or generically).

flags_7darray of string · optional

The flags over the block's 7-day window (lost_root_uid_in_window, sell_gate_closed_in_window, written_off_in_window). Absent on a block with no figure over that window. Known values: take_raised_30d, take_also_on_fund_holdings, sell_gate_closed_in_window, lost_root_uid_in_window, trading_frozen, written_off_in_window, holdings_below_cap_minimum, provisional, thin_pool, no_permit_in_window, subtoken_disabled, stake_tier_low, perpetual_lock, lock_exceeds_holdings. New values may be added; show an unknown value as is (or generically).

flags_30darray of string · optional

The same over the 30-day window. Known values: take_raised_30d, take_also_on_fund_holdings, sell_gate_closed_in_window, lost_root_uid_in_window, trading_frozen, written_off_in_window, holdings_below_cap_minimum, provisional, thin_pool, no_permit_in_window, subtoken_disabled, stake_tier_low, perpetual_lock, lock_exceeds_holdings. New values may be added; show an unknown value as is (or generically).

exitobject · can be null

Computed by this API: unstaking, instant to free TAO at data.cost's exit cost; no hold on a subnet, RootStakeUnlockInterval on root. Null on an older answer.

6 fields in exit
speedstring

instant: one extrinsic; claim: a claim that restakes on root; decay: a lock decaying into unlocked stake; none: not withdrawable while it holds (a perpetual lock). New values may be added; show an unknown value as is (or generically).

hold_blocksstring · unit blocks · can be null

Blocks before the exit can run, a u64 string: 0 on subnet stake; on root stake RootStakeUnlockInterval at the head. Null with decay / none, and on root when the interval could not be read (the hotkey runs no fund to read it from).

Format: whole number, as a string
lands_asstring

Where the proceeds land: free TAO, root stake on the same hotkey, or alpha stake. Known values: free_balance, root_stake, alpha_stake, none. New values may be added; show an unknown value as is (or generically).

cost_ratiostring · unit ratio · can be null

1 - proceeds / value given up, at this amount, now (transaction fees excluded), 8 decimals; 0 on a decaying lock (no fee: the cost is time). Null exactly with cost_unavailable_reason (checked: exactly one of the two is set).

Format: decimal number, as a string
cost_basisstring · can be null

Whether cost_ratio is the cost (exact) or the most it can be. Null with no cost_ratio. Known values: exact, upper_bound. New values may be added; show an unknown value as is (or generically).

cost_unavailable_reasonstring · can be null

Why cost_ratio is null: on a swap exit swap_refused, pool_not_alive (the subnet's subtoken is disabled), or the swap model's no_state / mechanism_unknown / unsupported_mechanism / inputs_missing; no_exit where nothing comes out (a perpetual lock, a miner collateral). Null exactly when cost_ratio is given. Known values: swap_refused, unpriced_holding, pool_not_alive, deposit_model_pending, no_exit, no_state, mechanism_unknown, unsupported_mechanism, inputs_missing. New values may be added; treat unknown values as unavailable.

as_of_daystring (date) · can be null

The to_day of the row's rates. Null while none is available.

Format: date, YYYY-MM-DD
as_of_heightinteger · unit block · can be null

The block the row's head values are read at. Null on an older answer.

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.