Quote staking an amount on a hotkey and subnet: swap costs now, the pool's yield and the stake's
https://api.bittensor.ai/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 issubnet_stake) orroot_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_heightfor the first block. The subnet's current life.- 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.- 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, 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.- 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):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).- 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_7dover 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 (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:
cost.round_trip_cost_ratio/ (at_amount.apr.value/ 365), 2 decimals. A LOWER bound (the APR is an upper bound). Null unlessbreakeven_stateisdays.- Format: decimal number, as a string · can be negative
- breakeven_statestring
days,never(the APR is not above 0) orunknown(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; null otherwise.- exitobject
Unstaking:
instant, no hold, back to free TAO, at the swap model'scost.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:
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).
- riskobject
Option C's risk:
high. Flagstake_raised_30d,subtoken_disabled,thin_pool(added by this API whenpool.fv_levelisL3); window flagsno_permit_in_window.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).
- as_of_daystring (date) · can be null
The
to_dayof 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'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
- 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_exposurenull 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'smeta.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.
- 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:
instantafter 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:
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).
- risk_principalobject
The principal's risk:
low.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
The accrual's risk:
medium.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).
- as_of_daystring (date) · can be null
The
to_dayof 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 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).
- 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_daybefore 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_basisroot_claimable). A rate, never a total. Null withunavailable_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.
- 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_raoearns after joining, alpha-denominated, net of take. Null withunavailable_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 withunavailable_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 whenapr_ratiois 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:
lowwhen the pool's own stake A is below X (the stake would be most of the pool), elsenormal. 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) orstandard. Null without a pool. New values may be added; show an unknown value as is (or generically).
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_ADDRESS
- INVALID_AMOUNT
- INVALID_NETUID
- NOT_READY
- 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.