Skip to content
TAO$188.31
BTC0.002929
MCap$2.21B
Vol$86.07M

API reference / Hotkeys

Quote staking an amount on a hotkey and subnet: swap costs now, the pool's yield and the stake's

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

What staking amount_rao TAO on this hotkey's pool on netuid costs now and what it yields, in one call.

Full description

What staking amount_rao TAO on this hotkey's pool on netuid costs now and what it yields, in one call. cost: the entry, exit and round-trip cost of that amount through the subnet's pool (this API's swap model on the pool's raw inputs at cost.state_height, the same model as /subnets/{netuid}/quote and the subnets' cost_model; root and other stable subnets 0). pool: the hotkey's pool at the latest available day and its nominator APY (and TAO-terms APR) over its yield window, before the stake (on root, the accrued root claimable rate). at_amount: the stake's own APY / APR (alpha and TAO terms) after it dilutes the pool by the multiplier M, the stake in alpha, the small-pool tier, and breakeven_days (computed by this API: the round-trip cost over the APR per day). Pool and stake come from one model and one window (the data source's stake-yield model), so the stake's APY never exceeds the pool's for a dilution. Options, beside them: option and the option's block. subnet_stake (a subnet): the pool's own 7- and 30-day rates and the stake's on the no-dilution bound, an UPPER bound, never an expected yield, with this API's fair-value level (L3 under 1 alpha in reserve, an empty pool included), breakeven_days (a LOWER bound), exit and the risk flag thin_pool on an L3 pool. root_stake (root): option A's holder-true accrual and the amount's (an upper bound), the sell gate, what the accrual sits in, the risks, this API's claim block (the claim threshold and the most a claim can forfeit to dust, from the fund's head fields: one more read on root) and exit. Data-source reads are made in parallel. Not checked: the account's balance, the chain's minimum stake and rate limits. Tip-cached. Errors are application/problem+json: INVALID_ADDRESS, INVALID_AMOUNT, SUBNET_NOT_FOUND (404), UNKNOWN_PARAMETER, NOT_READY (503), 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

hotkeypath, required· string

The hotkey: SS58, or 0x + 64 hex.

Query parameters

netuidquery, required· integer · 0 to 65535

The subnet slot (required; 0 = root).

amount_raoquery· string

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

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

optionenum

The option quoted: subnet_stake (option C, netuid >= 1; its block is subnet_stake) or root_stake (option A, netuid 0; root_stake).

One of: subnet_stake, root_stake
subnet_stakeobject · can be null

Option C at the amount, the pool's own rates and the stake's on the no-dilution bound (an UPPER bound), with this API's breakeven and exit. Null on root, without a pool now, and on an older data version's answer.

13 fields in subnet_stake
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.

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.

identity_namestring · can be null

The hotkey's identity name (its own, else its owner coldkey's). Null without one.

poolobject

The pool now and its own rates.

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

pool_alpha_raostring · unit alpha_rao (÷1e9)

TotalHotkeyAlpha(hotkey, netuid) at as_of_height: the pool's size, alpha rao.

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

The pool at the subnet's spot price, rao of TAO, floored. Null when unpriced.

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

Coldkeys with a non-zero share in this pool at as_of_day.

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

SubnetTAO at as_of_height: the subnet pool's TAO depth, rao. Null when not alive.

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

SubnetAlphaIn at as_of_height: the subnet pool's alpha depth, alpha rao. Null when not alive, and on an answer from before it.

Format: whole number, as a string · on chain: u64
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).

take_ratiostring · unit ratio · 6 decimals · can be null

The hotkey's Delegates take at the head, 0..1 (6 decimals).

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

The effective childkey take on this subnet, max(stored, floor), 0..1 (6 decimals).

Format: decimal number, as a string
validator_permitboolean

The hotkey holds a validator permit on the subnet now.

consistently_activeboolean · can be null

Active at every day end of the 7-day window. Null with no covered day.

apy_30dobject

apy_7d over 30 whole days.

at_amountobject

The stake at the amount. 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.

8 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: cost.round_trip_cost_ratio / (at_amount.apr.value / 365), 2 decimals. 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, never (the APR is not above 0) or unknown (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; null otherwise.

exitobject

Unstaking: instant, no hold, back to free TAO, at the swap model's cost.exit_cost_ratio (exact).

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.

riskobject

Option C's risk: high. Flags take_raised_30d, subtoken_disabled, thin_pool (added by this API when pool.fv_level is L3); window flags no_permit_in_window.

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

as_of_daystring (date) · can be null

The to_day of the rates: the last available UTC day. Null while none is.

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

The block the pool's head values are read at.

root_stakeobject · can be null

Option A at the amount on root, with this API's claim block and exit. Null off root, without root stake, and on an older data version's answer.

16 fields in root_stake
identity_namestring · can be null

The hotkey's identity name. Null without one.

take_ratiostring · unit ratio · 6 decimals · can be null

The Delegates take at the head, 0..1 (6 decimals).

Format: decimal number, as a string
has_root_uidboolean

The hotkey holds a root UID (without one the stake accrues nothing).

root_stake_tao_raostring · unit rao (÷1e9)

The hotkey's root stake (the pool A dilutes over), rao.

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

Option A's accrual: the hotkey's rates and the amount's.

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

The root-sell gate over the 7-day window.

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.

claimobject · can be null

Computed by this API from the fund's head fields (one more read): the claim threshold and the dust bound. Null when the hotkey runs no fund (unclaimed_exposure null too).

5 fields in claim
threshold_tao_raostring · unit rao (÷1e9)

RootClaimableThreshold of root (the fund's meta.controls.root_claimable_threshold_root_raw, I96F32 bits / 2^32, floored): the same threshold as the claim quote's meta.threshold_tao_rao.

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

One 7-day accrual at the amount: amount x y7, floored, where y7 = (1 + at_amount.apy)^(7 / 365) - 1 is the period return behind the 8-decimal APY (so within amount x 1e-9 of the source's). An upper bound like the APY. Null without the APY.

Format: whole number, as a string · on chain: u64
valuation_basisstring

Always anchor_realizable_nav: the accrual is valued at the realizable NAV per unit at the fund's anchor, so the pro-rata sale's slippage is already inside it. New values may be added; show an unknown value as is (or generically).

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

The fund's holdings (fund.composition.holdings) x BasketClaimRowDustCapTao (meta.controls.claim_row_dust_cap_tao_rao): the most a claim can forfeit to dust rows. Null without either.

Format: whole number, as a string · on chain: u64
dust_forfeit_max_ratiostring · unit ratio · 8 decimals · can be null

min(dust_forfeit_max_tao_rao, reference_accrual_tao_rao) / reference_accrual_tao_rao, 8 decimals: at most 1 (a claim cannot forfeit more than it is owed). Null without both, or with a 0 reference accrual.

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

The fund the accrual sits in. Null when the hotkey runs no fund.

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
breakeven_daysstring · unit days · 2 decimals · can be null

Always null: the principal has no entry or exit cost.

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

Always not_applicable: root stake is 1:1, there is no cost to earn back. New values may be added; show an unknown value as is (or generically).

breakeven_boundstring · can be null

Always null (no breakeven).

exitobject

Unstaking the principal: instant after RootStakeUnlockInterval (hold_blocks, null when it could not be read), back to free TAO, cost 0 (exact).

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.

risk_principalobject

The principal's risk: low.

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

The accrual's risk: medium.

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

as_of_daystring (date) · can be null

The to_day of the rates: the last available UTC day.

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

The block the head values are read at.

hotkeyobject

The hotkey, as {ss58, hex}.

2 fields in hotkey
ss58string

The account, SS58 (prefix 42).

Format: SS58 address
hexstring

The same 32-byte account id, 0x + 64 lower-case hex (the public key).

Format: 32-byte hex: 0x and 64 hex digits
netuidinteger · unit id

The subnet slot.

amount_tao_raostring · unit rao (÷1e9)

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

Format: whole number, as a string · on chain: u64
costobject

The swap costs of staking and unstaking the amount now.

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.

poolobject

The hotkey's pool on the subnet at the latest available day, before the stake joins.

8 fields in pool
stake_alpha_raostring · unit alpha_rao (÷1e9) · can be null

TotalHotkeyAlpha on this subnet at the end of to_day (the pool's own stake A), alpha rao (root: TAO rao). Null when the hotkey has no pool here.

Format: whole number, as a string · on chain: u64
apy_ratiostring · unit ratio · 8 decimals · can be null

The pool's nominator APY over from_day..to_day before the stake, (1 + y)^(365 / days) - 1 with y the per-share return over the window: net of take, alpha-denominated, price moves excluded; on root (netuid 0) y is the accrued root claimable (apy_basis root_claimable). A rate, never a total. Null with unavailable_reason.

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

The same return in TAO terms, simple: ((1 + y) x spot / spot at the window's open - 1) x 365 / days (root: the alpha-terms APR). Signed: an alpha price fall shows. Null with unavailable_reason, and without a spot at both ends.

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

What y is measured on: the pool's share index, or root's accrued root claimable. Known values: share_index, root_claimable. New values may be added; show an unknown value as is (or generically).

from_daystring (date) · can be null

The window's open (its day end).

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

The served day (the latest available).

Format: date, YYYY-MM-DD
daysinteger · unit count · can be null

Days in the window. Null without a rated window.

unavailable_reasonstring · can be null

Why the pool's rates are null: no_pool (no staking pool for the hotkey on this subnet), amount_too_large (above 1e18 rao no yield is read), pool_refused, parent_set_unknown, window_too_short or root_basis_pending (as at_amount.unavailable_reason). Null when given. New values may be added; treat unknown values as unavailable.

at_amountobject

The stake's own yield after it joins the pool, on the same model and window as pool.

10 fields in at_amount
apy_ratiostring · unit ratio · 8 decimals · can be null

(1 + y M)^(365 / days) - 1: the APY a new stake of amount_tao_rao earns after joining, alpha-denominated, net of take. Null with unavailable_reason, or when 1 + y M is not positive.

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

y M x 365 / days: the same uncompounded, breakeven_days' rate. Null with unavailable_reason.

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

In TAO terms: ((1 + y M) x spot / spot at the window's open)^(365 / days) - 1 (root: the alpha-terms APY). Signed. Null with unavailable_reason, without both spots, and on an older data version's answer.

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

In TAO terms, simple: ((1 + y M) x spot / spot at the window's open - 1) x 365 / days. Null as tao_apy_ratio.

Format: decimal number, as a string · can be negative
breakeven_daysstring · unit days · 2 decimals · can be null

Computed by this API: cost.round_trip_cost_ratio / (apr_ratio / 365), 2 decimals: the days the stake must stay to earn back its round trip. Null without either, or when apr_ratio is not above 0 (it never earns it back).

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

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

Format: whole number, as a string · on chain: u64
multiplierstring · unit ratio · 12 decimals · can be null

M, the stake's dilution of the pool's per-share return, 12 decimals. Null without X or the subnet's stake weight a pool keeping no own share needs.

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

The small-pool warning: low when the pool's own stake A is below X (the stake would be most of the pool), else normal. Null without X, and on an older data-source answer. New values may be added; show an unknown value as is (or generically).

modelstring · can be null

The dilution model applied: root, all_to_children (the hotkey keeps no own share: its children's) or standard. Null without a pool. New values may be added; show an unknown value as is (or generically).

unavailable_reasonstring · can be null

Why the rates at the amount are null: no_pool, amount_too_large (as pool's), 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 given. New values may be added; treat unknown values as unavailable.

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.