Stake positions of an account
https://api.bittensor.ai/api/v2/accounts/{address}/positions- Status
- Stable
- Auth
- API key or OAuth access token
- Scope
data:read- Rate limit
plan
The stake positions (hotkey, netuid) of the account at one block, in (netuid, hotkey) order, with their alpha, the spot price and the spot value in TAO and USD. Without limit every position (unpaged, no meta.page); with limit a page with meta.page {limit, total, next_cursor}, continued with cursor: a cursor page answers at its first page's block (the cursor carries it), whatever at says, so the pages add up to one snapshot. The account's include=positions section (child_limit) is this route's first page with limit = child_limit: its next_cursor continues here. Exact inside meta.coverage; at outside it is a 400 AT_OUT_OF_COVERAGE. A page pinned by at (a height or hash) or by a cursor is cached as settled once its block is finalized. include=exit adds each position's exit value (what selling it back to TAO realizes now; under include) and meta.exit_by_netuid. Errors are application/problem+json: INVALID_ADDRESS, INVALID_AT, INVALID_LIMIT, INVALID_CURSOR (also a cursor without limit), INVALID_INCLUDE, INCLUDE_AT_HEAD_ONLY (exit with at), AT_OUT_OF_COVERAGE, BLOCK_NOT_FOUND (404), UNKNOWN_PARAMETER, SOURCE_TIMEOUT (503), SOURCE_NOT_READY (503).
Path parameters
- addresspath, required· string
The account (coldkey): SS58, or 0x + 64 hex.
Query parameters
- atquery· string
The block the answer is for: a block height (
9179640), a0xblock hash, or an RFC 3339 time (2026-09-30T10:00:00Z, resolved to the last block at or before it). Omitted: the latest block the source has processed. Block 0 (the genesis block, by height or hash) is a 400INVALID_AT: it has no timestamp. A time the indexed head has not reached yet (in the future, or not indexed yet) is a 503NOT_FINALwithRetry-After, never an answer at an earlier block.- Format: a block height, a 0x block hash, or an RFC 3339 time
- limitquery· integer · 1 to 1000
Page size, 1..1000. Omitted: every position, unpaged. Anything else is a 400
INVALID_LIMIT.- cursorquery· string · up to 200 characters
meta.page.next_cursorof the previous page, passed back unchanged with the same other parameters. It is opaque and bound to them: a cursor used with different parameters, or altered, is a 400INVALID_CURSOR. Needslimit(the same one): without it a 400INVALID_CURSOR.- includequery· string
Comma list; anything else is a 400
INVALID_INCLUDE.exit: what selling each position back to TAO would realize now, computed by this API with the chain's exact swap on each held subnet's pool at the head (one more read of those pools):realizable_tao_rao,spot_value_tao_raoof the same alpha,fee_alpha_rao,exit_to_spot_ratio(availability: realizable / spot) andimpact_ratio(the sale's own price move; a different figure). It sells the sellable alpha only. The conviction lock is the account's, one per subnet (subnet_locks), capping its whole alpha there; only miner collateral (collateral_locked_alpha_rao) is per position. A position on a subnet without a conviction lock sellsalpha_rao- its collateral (basisunlocked); one on a subnet under a lock sells min(its alpha - its collateral, the subnet'ssellable_alpha_rao) (basissubnet_lock_capped): exactly the most that position ALONE can sell, but the subnet's positions share that amount, so their sold alpha does not add up either (readexit_by_netuid, which sells the subnet'ssellable_alpha_raoonce; the positions route reads the same locks frommeta.subnet_locks). On an older data version's answer the exit soldalpha_rao-locked_alpha_rao. A position whose lock or collateral is not known (locks_knownfalse) has a null exit (locks_unknown), and on an answer older than the locks (locks_knownnull) the exit sells the whole position, flaggedbasis=whole_position_locks_unknown(not the unlocked exit). Root exits 1:1 with no fee. A pool the model does not cover, a subnet without one or staking disabled: null figures withunavailable_reason. Each position's exit assumes that position alone is sold: exits are liquidity, not value, and do not add up (two hotkeys on one subnet sell into one pool);exit_by_netuidapplies the curve once per subnet. Head only (400INCLUDE_AT_HEAD_ONLYwithat), tip-cached.meta.exit_by_netuidis served unpaged only (null withlimit). A cursor page's positions are its first page's block's, sold into the pools now.
Response
data is a list of objects 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.
Positions holding alpha, ordered by netuid then hotkey; [] when there are none.
- hotkeystring
The hotkey the stake sits on, SS58 (prefix 42).
- Format: SS58 address
- netuidinteger · unit id
Subnet slot of the position (0 = root).
- 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 life of the subnet occupyingnetuid: netuid is a reused slot and generation tells its lives apart (compare or join on it). 0 for root. Null when not recorded.- 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.- alpha_raostring · unit alpha_rao (÷1e9)
Stake in alpha rao (1e-9 alpha of this subnet), equal to the runtime's StakeInfo stake.
- Format: whole number, as a string · on chain: u64
- price_taostring · unit tao_per_alpha · 12 decimals · can be null
Spot price of one alpha in TAO at
meta.at(SwapRuntimeApi current_alpha_price / 1e9; 1 on root), 9 to 12 decimals (12 on current answers). Null when no pool price is known.- Pattern:
^[0-9]+\.[0-9]{9,12}$ - value_spot_tao_raostring · unit rao (÷1e9) · can be null
floor(alpha x spot price), in rao of TAO. A spot valuation, not what unstaking would pay (that is
exit, withinclude=exit). Null when the price is.- Format: whole number, as a string · on chain: u64
- value_spot_usdstring · unit usd · 6 decimals · can be null
value_spot_tao_raox TAO/USD atmeta.at(6 decimals). Null when no TAO/USD price exists.- Format: decimal number, as a string
- locked_alpha_raostring · unit alpha_rao (÷1e9) · can be null · deprecated
Deprecated: mis-attributed. Earlier data versions put the account's conviction lock on its target hotkey's position (plus the position's miner collateral), in alpha rao; but the runtime's lock is one per (coldkey, subnet) and binds the coldkey's WHOLE alpha on the subnet, so it could exceed the position and missed locks whose target holds no position. Such a lock above its position is served null with
locks_knownfalse. Now always null: read the account'ssubnet_locks(sellable_alpha_rao) and the position'scollateral_locked_alpha_rao. Null on the oldest data versions' answers too. Deprecated: use subnet_locks / collateral_locked_alpha_rao; sunset 2027-02-15.- Format: whole number, as a string · on chain: u64
- Deprecated since 2026-10-03, removed after 2027-02-15. Use
subnet_locks / collateral_locked_alpha_raoinstead. - collateral_locked_alpha_raostring · unit alpha_rao (÷1e9) · can be null
The position's miner collateral at
meta.locks_as_of_height(MinerCollateral(netuid, hotkey, coldkey).locked, drained at each emission), in alpha rao: part ofalpha_rao, never added; it cannot be sold. 0 when none. Truly per position, unlike a conviction lock (the account'ssubnet_locks). Null when it does not decode (locks_knownfalse), and on an older data version's answer.- Format: whole number, as a string · on chain: u64
- locks_knownboolean · can be null
Whether the position's lock is known: its collateral (on an older data version's answer,
locked_alpha_rao). Null on an older answer (locks not served: the exit then sells the whole position,exit.basis=whole_position_locks_unknown).- exitvalue · optional
Only with
include=exit(absent otherwise; head only): what selling this position alone back to TAO would realize now. Liquidity, not value, and not additive: each figure assumes this sale alone, into the pool's head state; two sales into one pool get less than their exits summed (seeexit_by_netuid).- optionenum · can be null
The option the position is:
root_stake(option A's principal, netuid 0) orsubnet_stake(option C, a validator pool on a subnet). Null on an older data-source answer.- One of:
root_stake,subnet_stake - yieldobject · can be null
The POOL's figures over 7 days, the same for every holder of the pool: never this holder's own return (the portfolio series serves that), never added across positions. Null on an older answer.
3 fields in yield
- apy_7dobject
Subnet positions: the pool's per-share APY (alpha terms, net of take, no price term); root positions: the hotkey's holder-true root accrual rate (option A, accrued: never an amount). Reasons from the staking vocabulary (
not_readyuntil the day's figures are stored).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.
- tao_return_7dobject
Subnet positions: (1 + y) x spot at the end / spot at the open - 1, a period return in TAO terms (the price move included). Root positions: null with
not_applicable(checked).7 fields in tao_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.
- alpha_price_change_7dobject
Subnet positions: the alpha spot's change over the 7 days (a period change). Root positions: null with
not_applicable(checked).7 fields in alpha_price_change_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.
- collateralobject · can be null
The position's miner collateral beyond
collateral_locked_alpha_rao(its floor, drain ratio and the emission that drives the drain), kept separate from the account'ssubnet_locks(never summed with them except inlocked_spot_tao_rao). Null without a MinerCollateral entry (thencollateral_locked_alpha_raois0; checked: a collateral above 0 has its entry), when the collateral does not decode, and on an older data-source answer.4 fields in collateral
- min_locked_alpha_raostring · unit alpha_rao (÷1e9)
The miner-set floor, alpha rao: the drain never releases below it, and while
lockedis below it the hotkey's own emission is captured into the lock first (so it can exceedcollateral_locked_alpha_rao).- Format: whole number, as a string · on chain: u64
- drain_ratiostring · unit ratio · 12 decimals
k: collateral alpha released per alpha of hotkey emission earned (CollateralDrainRatio, U64F64, snapshot at registration; 0..10, checked), 12 decimals.
- Format: decimal number, as a string
- earned_alpha_raostring · unit alpha_rao (÷1e9)
The hotkey's emission earned while the entry existed, alpha rao (what drives the drain).
- Format: whole number, as a string · on chain: u64
- exitobject
Always
speednone,lands_asnone,cost_unavailable_reasonno_exit(checked): collateral is never withdrawn, it drains as emission is earned; no hold, no cost.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).
- staking_exitobject · can be null
Root positions only: unstaking the principal,
instantto free TAO after RootStakeUnlockInterval (hold_blocks), cost 0 (exact; root is 1:1). Null on a subnet position (its exit cost is this API's swap model:exit, withinclude=exit) and on an older answer.6 fields in staking_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).
- tao_reserve_raostring · unit rao (÷1e9) · can be null
The subnet's TAO reserve (SubnetTAO) now, rao: the pool's depth, a pool property. Null on root (no pool, checked), when not known, and on an older answer.
- Format: whole number, as a string · on chain: u64
- alpha_reserve_raostring · unit alpha_rao (÷1e9) · can be null
The subnet's alpha reserve (SubnetAlphaIn) now, alpha rao, what
fv_levelis computed from. Null on root (checked), when not known, and on an older answer.- Format: whole number, as a string · on chain: u64
- fv_levelstring · can be null
Computed by this API from the two reserves (no other read): the pool's fair-value level (valuation standard 2026-09-23, R2):
L1when a reference sale of 10 alpha moves the price by less than 1 % and the alpha 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 measured Level 3 value, the risk flagthin_pool). A pool property, never this holder's. Null on root, without both reserves, and on an older answer. New values may be added; show an unknown value as is (or generically).- last_income_heightinteger · unit block · can be null
The last day-end height, at or before the answer's day, with an income credit for this position: the pool's nominator dividend for every holder, and for the hotkey's Owner coldkey also its own take, miner incentive and owner cut credits. The root claimable (accrued, not yet income) and basket flush credits never count. Only the subnet's current life counts (from its first whole UTC day): a re-registered subnet's earlier life is another position. Null when none, and on an older answer.
- income_legs_in_windowinteger · unit count · can be null
Those income credits over the 7 available UTC emission days ending at the answer's day (
meta.income_windowon/positions; the same window on the account'sinclude=positions); 0 = none in the window (thenlast_income_height, if any, is older). The current life's credits only (the window starts at its first whole day when it is younger). Null (not known, never a partial count) when the window starts before the daily emission does (2026-09-06), when no emission day is available, and on an older answer.
Response headers
10 headers: ETag, Cache-Control, CDN-Cache-Control, X-BTAI-Stale, X-BTAI-Stale-As-Of, RateLimit-Policy, RateLimit, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
- ETag
Strong validator of this answer. Send it back as
If-None-Match: an unchanged answer is a 304 Not Modified without a body. A settled answer's validator leaves the chain head out, so it stays valid as the head moves.- Cache-Control
One of three classes: settled
public, max-age=3600, stale-while-revalidate=86400(pinned to a block that cannot move), slowpublic, max-age=300, stale-while-revalidate=600(state that moves in minutes or days) or tippublic, max-age=6, stale-while-revalidate=12(follows the chain head); the label routes are cached until the next nightly copy (public, max-age=<seconds>, stale-while-revalidate=60). Neverimmutable.no-storeon an earlier answer served because the data source failed (X-BTAI-Stale).- CDN-Cache-Control
The same class for shared caches (RFC 9213; browsers ignore it): settled 24 h, slow 300 s, tip 6 s, each with
stale-while-revalidateandstale-if-error;no-storewithX-BTAI-Stale.- X-BTAI-Stale
Present only when the data source failed to answer (it timed out or was unavailable) and an earlier answer to the same request is served instead of a 503 (stale if error, RFC 5861). Then
if-error, withX-BTAI-Stale-As-Of,Age(its seconds since then) andWarning: 110 - "Response is Stale", andCache-Control: no-store: the answer is never kept as fresh, and a later request reads again. Prices and quotes are never served this way.- X-BTAI-Stale-As-Of
With
X-BTAI-Stale: when the earlier answer served was produced, an RFC 3339 UTC time (2026-10-21T12:00:00Z).- RateLimit-Policy
The tier's request quota of the current window (IETF draft), e.g.
"tier";q=600.- RateLimit
Requests left in the current window and the seconds until it resets (IETF draft), e.g.
"tier";r=597;t=42.- X-RateLimit-Limit
The tier's request quota of the current window.
- X-RateLimit-Remaining
Requests left in the current window.
- X-RateLimit-Reset
When the current window resets, Unix seconds.
Status codes
200 · 304 · 400 · 401 · 402 · 403 · 404 · 429 · 500 · 502 · 503
304 Not Modified: the If-None-Match validator still matches; no body.
Error codes
The codes this endpoint can return. Each links to what it means and what to do.
- ADDRESS_NOT_IN_PLAN_SCOPE
- AMBIGUOUS_CREDENTIALS
- AT_OUT_OF_COVERAGE
- BAD_GATEWAY
- BILLING_UNAVAILABLE
- BLOCK_NOT_FOUND
- BUDGET_EXCEEDED
- CONCURRENCY_LIMIT
- INCLUDE_AT_HEAD_ONLY
- INSUFFICIENT_PERMISSIONS
- INTERNAL_ERROR
- INVALID_ADDRESS
- INVALID_AT
- INVALID_CURSOR
- INVALID_INCLUDE
- INVALID_LIMIT
- NOT_FINAL
- PAYMENT_REQUIRED
- RATE_LIMITED
- REPEATED_PARAMETER
- SERVICE_UNAVAILABLE
- SOURCE_BUSY
- SOURCE_NOT_READY
- SOURCE_TIMEOUT
- UNAUTHORIZED
- UNKNOWN_PARAMETER
- VALIDATION_ERROR
From the API's published specification, version 1.165.0.