A validator's staking options: root stake (A) and fund units (B), each with its own windows
https://api.bittensor.ai/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.0when 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_reasonis set, and served only whendays_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 withnot_readyornot_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 beforemeta.at's day. Null withfrom_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 withfrom_day.- days_expectedinteger · unit count
The nominal window in days: 7 or 30.
- 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_reasonis set, and served only whendays_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 withnot_readyornot_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 beforemeta.at's day. Null withfrom_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 withfrom_day.- days_expectedinteger · unit count
The nominal window in days: 7 or 30.
- 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 whenapy_7dis (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 whenapy_30dis.- 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_reasonis set, and served only whendays_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 withnot_readyornot_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 beforemeta.at's day. Null withfrom_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 withfrom_day.- days_expectedinteger · unit count
The nominal window in days: 7 or 30.
- 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_reasonis set, and served only whendays_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 withnot_readyornot_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 beforemeta.at's day. Null withfrom_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 withfrom_day.- days_expectedinteger · unit count
The nominal window in days: 7 or 30.
- 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_reasonis set, and served only whendays_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 withnot_readyornot_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 beforemeta.at's day. Null withfrom_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 withfrom_day.- days_expectedinteger · unit count
The nominal window in days: 7 or 30.
- 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_reasonis set, and served only whendays_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 withnot_readyornot_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 beforemeta.at's day. Null withfrom_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 withfrom_day.- days_expectedinteger · unit count
The nominal window in days: 7 or 30.
- 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_reasonis set, and served only whendays_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 withnot_readyornot_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 beforemeta.at's day. Null withfrom_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 withfrom_day.- days_expectedinteger · unit count
The nominal window in days: 7 or 30.
- 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_reasonis set, and served only whendays_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 withnot_readyornot_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 beforemeta.at's day. Null withfrom_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 withfrom_day.- days_expectedinteger · unit count
The nominal window in days: 7 or 30.
- 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
- 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'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
- 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(it sits in the fund's units).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 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 againsthas_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.- 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_reasonis set, and served only whendays_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 withnot_readyornot_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 beforemeta.at's day. Null withfrom_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 withfrom_day.- days_expectedinteger · unit count
The nominal window in days: 7 or 30.
- 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_reasonis set, and served only whendays_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 withnot_readyornot_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 beforemeta.at's day. Null withfrom_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 withfrom_day.- days_expectedinteger · unit count
The nominal window in days: 7 or 30.
- 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'sn_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 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 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), 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
- HOTKEY_NOT_FOUND
- INSUFFICIENT_PERMISSIONS
- INTERNAL_ERROR
- INVALID_ADDRESS
- INVALID_HOTKEY
- INVALID_INCLUDE
- PAYMENT_REQUIRED
- PLAN_REQUIRED
- RATE_LIMITED
- SERVICE_UNAVAILABLE
- SOURCE_BUSY
- SOURCE_NOT_READY
- SOURCE_TIMEOUT
- UNAUTHORIZED
- UNKNOWN_PARAMETER
- VALIDATION_ERROR
From the API's published specification, version 1.165.0.