Every validator pool on a subnet quoted at one stake amount: its yield before and after the stake
https://api.bittensor.ai/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 400INVALID_SORT.- orderquery· enum · one of asc, desc
The direction,
ascordesc(default: the key's; nulls last either way; sent only when given). Anything else is a 400INVALID_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) orroot_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_heightfor 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
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.- 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, defaultapy_at_amount). Null on an older data version's answer (bestapy_at_amount_ratiofirst).- 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, defaultascfortakeandbreakeven_days, elsedesc); 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'scost). 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 atstate_height(fees and slippage), 8 decimals. 0 on astablesubnet (root). Null withunavailable_reason.- Format: decimal number, as a string
- entry_cost_ratiostring · unit ratio · 8 decimals · can be null
1 -
alpha_out_raox spot /amount_tao_rao: the stake's loss against the pool's spot price (fee and slippage), 8 decimals. 0 on astablesubnet. Null withunavailable_reason.- Format: decimal number, as a string
- exit_cost_ratiostring · unit ratio · 8 decimals · can be null
1 -
tao_back_rao/ (alpha_out_raox spot): the unstake's loss against spot, 8 decimals. 0 on astablesubnet. Null withunavailable_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).
- 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):L1when 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;L2when it holds at least 1 alpha; elseL3(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_childrenpools 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 atday, bestapy_at_amount_ratiofirst (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.daysdays 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_childrenorstandard. Null on a row whose pool has no figures fordata.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_childrenpool (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_readyorpool_refused.- Format: decimal number, as a string · can be negative
- stake_tierstring · can be null
lowwhen the pool's own stake A is below X, elsenormal. 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
- 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
takeorder'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_stakeorder'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, plusprice_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 (modelno_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
lowwhen the pool's own stake (pool_alpha_rao) is below X (the stake would be most of the pool), elsenormal(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 (modelno_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 (modelno_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_unknownwithout a spot at both ends. An UPPER bound, never an expected yield (modelno_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 unlessbreakeven_stateisdays.- Format: decimal number, as a string · can be negative
- breakeven_statestring
dayswhen computed;neverwhen the APR is not above 0 (it never earns the cost back);unknownwhen 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
lowerbeside abreakeven_days(the opposite ofbound); null otherwise.
- riskobject · can be null
Subnet rows: option C's risk (
high;thin_pooladded by this API whendata.fv_levelisL3). Null on root rows and older answers.4 fields in risk
- labelstring
The option's fixed label (root principal
low, root accrualmedium, fund unitshigh); 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_stakeorder'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'ssell_gate_closed_in_windowfor this window, and 0 is what the window's rate'ssell_gate_closedmeans (both checked). Null withnot_ready.- Format: whole number, as a string
- window_blocksstring · unit blocks · can be null
The window's blocks (after
from_day's close throughto_day's), a u64 string. Null withnot_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
- 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.
- 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 accrualmedium, fund unitshigh); 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 accrualmedium, fund unitshigh); 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,
instantto free TAO atdata.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:
0on subnet stake; on root stake RootStakeUnlockInterval at the head. Null withdecay/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;
0on a decaying lock (no fee: the cost is time). Null exactly withcost_unavailable_reason(checked: exactly one of the two is set).- Format: decimal number, as a string
- cost_basisstring · can be null
Whether
cost_ratiois the cost (exact) or the most it can be. Null with nocost_ratio. Known values:exact,upper_bound. New values may be added; show an unknown value as is (or generically).
- as_of_daystring (date) · can be null
The
to_dayof 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), 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_AMOUNT
- INVALID_DIR
- INVALID_NETUID
- INVALID_ORDER
- INVALID_SORT
- NOT_FOUND
- PAYMENT_REQUIRED
- PLAN_REQUIRED
- RATE_LIMITED
- REPEATED_PARAMETER
- SERVICE_UNAVAILABLE
- SOURCE_BUSY
- SOURCE_NOT_READY
- SOURCE_TIMEOUT
- SUBNET_NOT_FOUND
- UNAUTHORIZED
- UNKNOWN_PARAMETER
- VALIDATION_ERROR
From the API's published specification, version 1.165.0.