Skip to content
TAO$188.40
BTC0.00293
MCap$2.21B
Vol$86.07M

API reference / Hotkeys

A validator's staking options: root stake (A) and fund units (B), each with its own windows

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

Two separate blocks, never combined (no rate across options): root_stake (option A, root stake to this validator: the holder-true accrual APY over 7 / 30 days, the realised claims, the staker TWR, the hold (no-claim) return, the sell gate, its principal and accrual risks) and fund (option B, the validator's fund units: state, realizable and spot NAV and per unit, the holders' return over 7 / 30 day ends, display figures, risk; null when it runs no fund). Every window figure is a RatioFigure: a value only over its whole window (days_ok = days_expected), else null with its unavailable_reason (a 7-day figure is insufficient_history until 7 days are available). Accrual is unrealised until claimed: a rate, never an amount. Head state: tip-cached. Errors are application/problem+json: INVALID_ADDRESS, INVALID_HOTKEY, HOTKEY_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

hotkeypath, required· string

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

Query parameters

includequery· string

Reserved for opt-in sections. This route defines none yet; the parameter is declared so that adding one later is additive for generated clients. Any value is a 400 INVALID_INCLUDE.

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 hotkey and its option blocks.

hotkeyobject

The validator's 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
root_stakeobject

Option A: root stake to this validator.

21 fields in root_stake
optionstring

Always root_stake.

basisstring

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

has_root_uidboolean

The hotkey holds a root UID at as_of_height.

root_stake_tao_raostring · unit rao (÷1e9)

TotalHotkeyAlpha(hotkey, 0) at as_of_height (root is 1:1), rao of TAO: the pool the accrual dilutes over. 0 when none.

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

The Delegates take at the head, 0..1 (6 decimals). Null without a Delegates entry.

Format: decimal number, as a string
apy_7dobject

Holder-true accrual (APY): the fund units a TAO of root stake held through the window accrued, each day at that day's own realizable NAV per unit (the value at accrual), annualised; net of take, before the claim, the escrow share excluded. A rate, never an amount, and accrued: unrealised until claimed. NAV moves after the mint are hold_return_*, never here.

7 fields in apy_7d
valuestring · unit ratio · can be null

The figure, a signed ratio (1 = 100 %). Null exactly when unavailable_reason is set, and served only when days_ok = days_expected (checked).

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

apy: a compounded annual rate; apr: a simple annual rate; period: an un-annualised return or change over the window. New values may be added; show an unknown value as is (or generically).

from_daystring (date) · can be null

The window opens at this UTC day's end (to_day - days_expected). Null only with not_ready or not_applicable.

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

The window closes at this UTC day's end: the block's as_of_day, at or before meta.at's day. Null with from_day.

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

Whole UTC days of the window whose inputs are valid, 0..days_expected: how far a figure short of its window (insufficient_history) has got. Null with from_day.

days_expectedinteger · unit count

The nominal window in days: 7 or 30.

unavailable_reasonstring · can be null

Why value is null (each figure may give only the reasons its block lists, checked; no_deposits, nothing was ever deposited, only on a fund's lifetime_return); null exactly when value is given. Known values: not_ready, insufficient_history, not_applicable, no_root_uid, lost_root_uid_in_window, sell_gate_closed, fund_empty, fund_dissolved, fund_reset, share_collapse, dust_fund, provisional, unpriced_holding, no_nav_row, no_pool, pool_not_alive, no_permit, pool_refused, pool_unpriced, amount_too_large, below_min_stake, hotkey_not_on_root, nothing_owed, deposit_model_pending, swap_refused, price_unknown, no_deposits. New values may be added; treat unknown values as unavailable.

apy_30dobject

The same over 30 days.

7 fields in apy_30d
valuestring · unit ratio · can be null

The figure, a signed ratio (1 = 100 %). Null exactly when unavailable_reason is set, and served only when days_ok = days_expected (checked).

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

apy: a compounded annual rate; apr: a simple annual rate; period: an un-annualised return or change over the window. New values may be added; show an unknown value as is (or generically).

from_daystring (date) · can be null

The window opens at this UTC day's end (to_day - days_expected). Null only with not_ready or not_applicable.

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

The window closes at this UTC day's end: the block's as_of_day, at or before meta.at's day. Null with from_day.

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

Whole UTC days of the window whose inputs are valid, 0..days_expected: how far a figure short of its window (insufficient_history) has got. Null with from_day.

days_expectedinteger · unit count

The nominal window in days: 7 or 30.

unavailable_reasonstring · can be null

Why value is null (each figure may give only the reasons its block lists, checked; no_deposits, nothing was ever deposited, only on a fund's lifetime_return); null exactly when value is given. Known values: not_ready, insufficient_history, not_applicable, no_root_uid, lost_root_uid_in_window, sell_gate_closed, fund_empty, fund_dissolved, fund_reset, share_collapse, dust_fund, provisional, unpriced_holding, no_nav_row, no_pool, pool_not_alive, no_permit, pool_refused, pool_unpriced, amount_too_large, below_min_stake, hotkey_not_on_root, nothing_owed, deposit_model_pending, swap_refused, price_unknown, no_deposits. New values may be added; treat unknown values as unavailable.

accrual_period_return_7dstring · unit ratio · 12 decimals · can be null

The 7-day window's period return y behind apy_7d: the daily holder-true accrual summed over the window, 12 decimals (apy_7d = (1 + y)^(365/7) - 1, checked within its rounding). Exact where the 8-decimal APY rounds: compose an accrual at an amount from this, never from the APY. A rate, never an amount, and accrued. Null exactly when apy_7d is (checked), and on an answer from before it.

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

The same over the 30-day window (apy_30d = (1 + y)^(365/30) - 1). Null exactly when apy_30d is.

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

The root claims executed on the hotkey in the window (BasketClaimed.tao) over the mean root stake held, annualised: the realised cross-check, lumpy.

7 fields in realised_apy_7d
valuestring · unit ratio · can be null

The figure, a signed ratio (1 = 100 %). Null exactly when unavailable_reason is set, and served only when days_ok = days_expected (checked).

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

apy: a compounded annual rate; apr: a simple annual rate; period: an un-annualised return or change over the window. New values may be added; show an unknown value as is (or generically).

from_daystring (date) · can be null

The window opens at this UTC day's end (to_day - days_expected). Null only with not_ready or not_applicable.

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

The window closes at this UTC day's end: the block's as_of_day, at or before meta.at's day. Null with from_day.

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

Whole UTC days of the window whose inputs are valid, 0..days_expected: how far a figure short of its window (insufficient_history) has got. Null with from_day.

days_expectedinteger · unit count

The nominal window in days: 7 or 30.

unavailable_reasonstring · can be null

Why value is null (each figure may give only the reasons its block lists, checked; no_deposits, nothing was ever deposited, only on a fund's lifetime_return); null exactly when value is given. Known values: not_ready, insufficient_history, not_applicable, no_root_uid, lost_root_uid_in_window, sell_gate_closed, fund_empty, fund_dissolved, fund_reset, share_collapse, dust_fund, provisional, unpriced_holding, no_nav_row, no_pool, pool_not_alive, no_permit, pool_refused, pool_unpriced, amount_too_large, below_min_stake, hotkey_not_on_root, nothing_owed, deposit_model_pending, swap_refused, price_unknown, no_deposits. New values may be added; treat unknown values as unavailable.

realised_apy_30dobject

The same over 30 days.

7 fields in realised_apy_30d
valuestring · unit ratio · can be null

The figure, a signed ratio (1 = 100 %). Null exactly when unavailable_reason is set, and served only when days_ok = days_expected (checked).

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

apy: a compounded annual rate; apr: a simple annual rate; period: an un-annualised return or change over the window. New values may be added; show an unknown value as is (or generically).

from_daystring (date) · can be null

The window opens at this UTC day's end (to_day - days_expected). Null only with not_ready or not_applicable.

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

The window closes at this UTC day's end: the block's as_of_day, at or before meta.at's day. Null with from_day.

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

Whole UTC days of the window whose inputs are valid, 0..days_expected: how far a figure short of its window (insufficient_history) has got. Null with from_day.

days_expectedinteger · unit count

The nominal window in days: 7 or 30.

unavailable_reasonstring · can be null

Why value is null (each figure may give only the reasons its block lists, checked; no_deposits, nothing was ever deposited, only on a fund's lifetime_return); null exactly when value is given. Known values: not_ready, insufficient_history, not_applicable, no_root_uid, lost_root_uid_in_window, sell_gate_closed, fund_empty, fund_dissolved, fund_reset, share_collapse, dust_fund, provisional, unpriced_holding, no_nav_row, no_pool, pool_not_alive, no_permit, pool_refused, pool_unpriced, amount_too_large, below_min_stake, hotkey_not_on_root, nothing_owed, deposit_model_pending, swap_refused, price_unknown, no_deposits. New values may be added; treat unknown values as unavailable.

staker_twr_7dobject

BasketTwr over the window (claim and restake, each dividend at realizable value), a period return.

7 fields in staker_twr_7d
valuestring · unit ratio · can be null

The figure, a signed ratio (1 = 100 %). Null exactly when unavailable_reason is set, and served only when days_ok = days_expected (checked).

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

apy: a compounded annual rate; apr: a simple annual rate; period: an un-annualised return or change over the window. New values may be added; show an unknown value as is (or generically).

from_daystring (date) · can be null

The window opens at this UTC day's end (to_day - days_expected). Null only with not_ready or not_applicable.

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

The window closes at this UTC day's end: the block's as_of_day, at or before meta.at's day. Null with from_day.

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

Whole UTC days of the window whose inputs are valid, 0..days_expected: how far a figure short of its window (insufficient_history) has got. Null with from_day.

days_expectedinteger · unit count

The nominal window in days: 7 or 30.

unavailable_reasonstring · can be null

Why value is null (each figure may give only the reasons its block lists, checked; no_deposits, nothing was ever deposited, only on a fund's lifetime_return); null exactly when value is given. Known values: not_ready, insufficient_history, not_applicable, no_root_uid, lost_root_uid_in_window, sell_gate_closed, fund_empty, fund_dissolved, fund_reset, share_collapse, dust_fund, provisional, unpriced_holding, no_nav_row, no_pool, pool_not_alive, no_permit, pool_refused, pool_unpriced, amount_too_large, below_min_stake, hotkey_not_on_root, nothing_owed, deposit_model_pending, swap_refused, price_unknown, no_deposits. New values may be added; treat unknown values as unavailable.

staker_twr_30dobject

The same over 30 days.

7 fields in staker_twr_30d
valuestring · unit ratio · can be null

The figure, a signed ratio (1 = 100 %). Null exactly when unavailable_reason is set, and served only when days_ok = days_expected (checked).

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

apy: a compounded annual rate; apr: a simple annual rate; period: an un-annualised return or change over the window. New values may be added; show an unknown value as is (or generically).

from_daystring (date) · can be null

The window opens at this UTC day's end (to_day - days_expected). Null only with not_ready or not_applicable.

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

The window closes at this UTC day's end: the block's as_of_day, at or before meta.at's day. Null with from_day.

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

Whole UTC days of the window whose inputs are valid, 0..days_expected: how far a figure short of its window (insufficient_history) has got. Null with from_day.

days_expectedinteger · unit count

The nominal window in days: 7 or 30.

unavailable_reasonstring · can be null

Why value is null (each figure may give only the reasons its block lists, checked; no_deposits, nothing was ever deposited, only on a fund's lifetime_return); null exactly when value is given. Known values: not_ready, insufficient_history, not_applicable, no_root_uid, lost_root_uid_in_window, sell_gate_closed, fund_empty, fund_dissolved, fund_reset, share_collapse, dust_fund, provisional, unpriced_holding, no_nav_row, no_pool, pool_not_alive, no_permit, pool_refused, pool_unpriced, amount_too_large, below_min_stake, hotkey_not_on_root, nothing_owed, deposit_model_pending, swap_refused, price_unknown, no_deposits. New values may be added; treat unknown values as unavailable.

hold_return_7dobject

Hold without claiming: the units accrued in the window marked at realizable NAV per unit at its end against their value at accrual, a period return. Served beside apy_7d, never added to it.

7 fields in hold_return_7d
valuestring · unit ratio · can be null

The figure, a signed ratio (1 = 100 %). Null exactly when unavailable_reason is set, and served only when days_ok = days_expected (checked).

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

apy: a compounded annual rate; apr: a simple annual rate; period: an un-annualised return or change over the window. New values may be added; show an unknown value as is (or generically).

from_daystring (date) · can be null

The window opens at this UTC day's end (to_day - days_expected). Null only with not_ready or not_applicable.

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

The window closes at this UTC day's end: the block's as_of_day, at or before meta.at's day. Null with from_day.

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

Whole UTC days of the window whose inputs are valid, 0..days_expected: how far a figure short of its window (insufficient_history) has got. Null with from_day.

days_expectedinteger · unit count

The nominal window in days: 7 or 30.

unavailable_reasonstring · can be null

Why value is null (each figure may give only the reasons its block lists, checked; no_deposits, nothing was ever deposited, only on a fund's lifetime_return); null exactly when value is given. Known values: not_ready, insufficient_history, not_applicable, no_root_uid, lost_root_uid_in_window, sell_gate_closed, fund_empty, fund_dissolved, fund_reset, share_collapse, dust_fund, provisional, unpriced_holding, no_nav_row, no_pool, pool_not_alive, no_permit, pool_refused, pool_unpriced, amount_too_large, below_min_stake, hotkey_not_on_root, nothing_owed, deposit_model_pending, swap_refused, price_unknown, no_deposits. New values may be added; treat unknown values as unavailable.

hold_return_30dobject

The same over 30 days.

7 fields in hold_return_30d
valuestring · unit ratio · can be null

The figure, a signed ratio (1 = 100 %). Null exactly when unavailable_reason is set, and served only when days_ok = days_expected (checked).

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

apy: a compounded annual rate; apr: a simple annual rate; period: an un-annualised return or change over the window. New values may be added; show an unknown value as is (or generically).

from_daystring (date) · can be null

The window opens at this UTC day's end (to_day - days_expected). Null only with not_ready or not_applicable.

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

The window closes at this UTC day's end: the block's as_of_day, at or before meta.at's day. Null with from_day.

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

Whole UTC days of the window whose inputs are valid, 0..days_expected: how far a figure short of its window (insufficient_history) has got. Null with from_day.

days_expectedinteger · unit count

The nominal window in days: 7 or 30.

unavailable_reasonstring · can be null

Why value is null (each figure may give only the reasons its block lists, checked; no_deposits, nothing was ever deposited, only on a fund's lifetime_return); null exactly when value is given. Known values: not_ready, insufficient_history, not_applicable, no_root_uid, lost_root_uid_in_window, sell_gate_closed, fund_empty, fund_dissolved, fund_reset, share_collapse, dust_fund, provisional, unpriced_holding, no_nav_row, no_pool, pool_not_alive, no_permit, pool_refused, pool_unpriced, amount_too_large, below_min_stake, hotkey_not_on_root, nothing_owed, deposit_model_pending, swap_refused, price_unknown, no_deposits. New values may be added; treat unknown values as unavailable.

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.

sell_gate_30dobject

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

5 fields in sell_gate_30d
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.

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 (it sits in the fund's units).

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 block's figures: the last available UTC day. Null while none is available.

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

The block the head values (stake, take, root UID) are read at, at or below meta.at.

fundobject · can be null

Option B: this validator's fund units. Null when it runs no fund.

21 fields in fund
optionstring

Always fund_units.

statestring

dissolved (worth exactly 0); no_state (no units outstanding, nothing held); off_root (units outstanding, no root UID: holders can still claim); active (units and a root UID). Checked against has_root_uid. New values may be added; show an unknown value as is (or generically).

has_root_uidboolean

The hotkey holds a root UID at as_of_height.

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

The fund's realizable NAV (its holdings as sold through each pool), rao of TAO. Null with nav_unavailable_reason (a dissolved fund's is null with fund_dissolved, checked), and on no_state.

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

Its spot NAV (display), rao of TAO. Null together with the realizable NAV.

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

Why the NAVs are null (fund_dissolved: the fund is dissolved); null when they are given. Known values: no_nav_row, unpriced_holding, fund_dissolved. New values may be added; treat unknown values as unavailable.

units_outstandingstring · unit count · can be null

BasketShares: the fund's units outstanding (units, not TAO). Null on no_state.

Format: whole number, as a string
sum_owed_unitsstring · unit count · can be null

The units its holders are owed, summed (units).

Format: whole number, as a string
unowed_unitsstring · unit count · can be null

Units outstanding no holder is owed (units); a negative one is served as stated (a data-source defect, reported).

Format: whole number, as a string · can be negative
unit_value_realizable_raostring · unit rao_per_share · can be null

The realizable NAV per unit (rao of TAO per unit, 12 decimals). Null without a NAV or units.

Format: decimal number, as a string
unit_value_spot_raostring · unit rao_per_share · can be null

The spot NAV per unit (rao of TAO per unit). Null with the realizable one.

Format: decimal number, as a string
holder_return_7dobject

Option B's headline: the realizable NAV per unit over the window's day ends, minus 1, a period return (not annualised; flow-invariant, TAO terms).

7 fields in holder_return_7d
valuestring · unit ratio · can be null

The figure, a signed ratio (1 = 100 %). Null exactly when unavailable_reason is set, and served only when days_ok = days_expected (checked).

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

apy: a compounded annual rate; apr: a simple annual rate; period: an un-annualised return or change over the window. New values may be added; show an unknown value as is (or generically).

from_daystring (date) · can be null

The window opens at this UTC day's end (to_day - days_expected). Null only with not_ready or not_applicable.

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

The window closes at this UTC day's end: the block's as_of_day, at or before meta.at's day. Null with from_day.

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

Whole UTC days of the window whose inputs are valid, 0..days_expected: how far a figure short of its window (insufficient_history) has got. Null with from_day.

days_expectedinteger · unit count

The nominal window in days: 7 or 30.

unavailable_reasonstring · can be null

Why value is null (each figure may give only the reasons its block lists, checked; no_deposits, nothing was ever deposited, only on a fund's lifetime_return); null exactly when value is given. Known values: not_ready, insufficient_history, not_applicable, no_root_uid, lost_root_uid_in_window, sell_gate_closed, fund_empty, fund_dissolved, fund_reset, share_collapse, dust_fund, provisional, unpriced_holding, no_nav_row, no_pool, pool_not_alive, no_permit, pool_refused, pool_unpriced, amount_too_large, below_min_stake, hotkey_not_on_root, nothing_owed, deposit_model_pending, swap_refused, price_unknown, no_deposits. New values may be added; treat unknown values as unavailable.

holder_return_30dobject

The same over 30 days.

7 fields in holder_return_30d
valuestring · unit ratio · can be null

The figure, a signed ratio (1 = 100 %). Null exactly when unavailable_reason is set, and served only when days_ok = days_expected (checked).

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

apy: a compounded annual rate; apr: a simple annual rate; period: an un-annualised return or change over the window. New values may be added; show an unknown value as is (or generically).

from_daystring (date) · can be null

The window opens at this UTC day's end (to_day - days_expected). Null only with not_ready or not_applicable.

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

The window closes at this UTC day's end: the block's as_of_day, at or before meta.at's day. Null with from_day.

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

Whole UTC days of the window whose inputs are valid, 0..days_expected: how far a figure short of its window (insufficient_history) has got. Null with from_day.

days_expectedinteger · unit count

The nominal window in days: 7 or 30.

unavailable_reasonstring · can be null

Why value is null (each figure may give only the reasons its block lists, checked; no_deposits, nothing was ever deposited, only on a fund's lifetime_return); null exactly when value is given. Known values: not_ready, insufficient_history, not_applicable, no_root_uid, lost_root_uid_in_window, sell_gate_closed, fund_empty, fund_dissolved, fund_reset, share_collapse, dust_fund, provisional, unpriced_holding, no_nav_row, no_pool, pool_not_alive, no_permit, pool_refused, pool_unpriced, amount_too_large, below_min_stake, hotkey_not_on_root, nothing_owed, deposit_model_pending, swap_refused, price_unknown, no_deposits. New values may be added; treat unknown values as unavailable.

n_stakersinteger · unit count · can be null

The fund's stakers at its latest available day end (the fund row's n_stakers): the (fund hotkey, coldkey) pairs holding a root share key (Alpha / AlphaV2 on netuid 0) OR a BasketClaimed record, the fund escrow excluded; it includes stakers whose root stake is now 0 with a claim record, and dust is not excluded. The stakers with root stake > 0 are the fund row's n_stakers_with_stake (GET /baskets/{hotkey}).

first_blockinteger · unit block · can be null

The fund's first block. Null on no_state.

riskobject

The units' risk: high.

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 fund's latest available UTC day (the figures' to_day).

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

The block the head values are read at.

displayvalue · optional

The display figures. Absent on a block that carries none.

compositionvalue · optional

The holdings' concentration at the fund's newest swept anchor at or before the day close. Absent where it is not served (directory rows, an older answer).

tradingvalue · optional

The trading status, 7-day swaps and the 30-day turnover. Absent where it is not served (directory rows, an older answer).

Response headers

10 headers: ETag, Cache-Control, CDN-Cache-Control, X-BTAI-Stale, X-BTAI-Stale-As-Of, RateLimit-Policy, RateLimit, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
ETag

Strong validator of this answer. Send it back as If-None-Match: an unchanged answer is a 304 Not Modified without a body. A settled answer's validator leaves the chain head out, so it stays valid as the head moves.

Cache-Control

One of three classes: settled public, max-age=3600, stale-while-revalidate=86400 (pinned to a block that cannot move), slow public, max-age=300, stale-while-revalidate=600 (state that moves in minutes or days) or tip public, max-age=6, stale-while-revalidate=12 (follows the chain head); the label routes are cached until the next nightly copy (public, max-age=<seconds>, stale-while-revalidate=60). Never immutable. no-store on an earlier answer served because the data source failed (X-BTAI-Stale).

CDN-Cache-Control

The same class for shared caches (RFC 9213; browsers ignore it): settled 24 h, slow 300 s, tip 6 s, each with stale-while-revalidate and stale-if-error; no-store with X-BTAI-Stale.

X-BTAI-Stale

Present only when the data source failed to answer (it timed out or was unavailable) and an earlier answer to the same request is served instead of a 503 (stale if error, RFC 5861). Then if-error, with X-BTAI-Stale-As-Of, Age (its seconds since then) and Warning: 110 - "Response is Stale", and Cache-Control: no-store: the answer is never kept as fresh, and a later request reads again. Prices and quotes are never served this way.

X-BTAI-Stale-As-Of

With X-BTAI-Stale: when the earlier answer served was produced, an RFC 3339 UTC time (2026-10-21T12:00:00Z).

RateLimit-Policy

The tier's request quota of the current window (IETF draft), e.g. "tier";q=600.

RateLimit

Requests left in the current window and the seconds until it resets (IETF draft), e.g. "tier";r=597;t=42.

X-RateLimit-Limit

The tier's request quota of the current window.

X-RateLimit-Remaining

Requests left in the current window.

X-RateLimit-Reset

When the current window resets, Unix seconds.

Status codes

200 · 304 · 400 · 401 · 402 · 403 · 404 · 429 · 500 · 502 · 503

304 Not Modified: the If-None-Match validator still matches; no body.

Error codes

The codes this endpoint can return. Each links to what it means and what to do.

From the API's published specification, version 1.165.0.