Skip to content
TAO$188.12
BTC0.002928
MCap$2.21B
Vol$86.07M

API reference / Portfolio

Stake positions of an account

GET/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), a 0x block 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 400 INVALID_AT: it has no timestamp. A time the indexed head has not reached yet (in the future, or not indexed yet) is a 503 NOT_FINAL with Retry-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_cursor of 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 400 INVALID_CURSOR. Needs limit (the same one): without it a 400 INVALID_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_rao of the same alpha, fee_alpha_rao, exit_to_spot_ratio (availability: realizable / spot) and impact_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 sells alpha_rao - its collateral (basis unlocked); one on a subnet under a lock sells min(its alpha - its collateral, the subnet's sellable_alpha_rao) (basis subnet_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 (read exit_by_netuid, which sells the subnet's sellable_alpha_rao once; the positions route reads the same locks from meta.subnet_locks). On an older data version's answer the exit sold alpha_rao - locked_alpha_rao. A position whose lock or collateral is not known (locks_known false) has a null exit (locks_unknown), and on an answer older than the locks (locks_known null) the exit sells the whole position, flagged basis = 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 with unavailable_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_netuid applies the curve once per subnet. Head only (400 INCLUDE_AT_HEAD_ONLY with at), tip-cached. meta.exit_by_netuid is served unpaged only (null with limit). 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_height for the first block. The life of the subnet occupying netuid: 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 generation names (GET /subnets/generations' start_height): use it, never generation, for heights, ages and dates. Null exactly when generation is null (root without a life, no subnet), or transiently when this API cannot read the lives. Root's generation 0 starts at 0.

is_current_lifeboolean · can be null

Whether generation is the slot's current life (true) or an ended one, re-registered since (false). Null exactly when generation is null, or transiently when this API cannot read the lives. Root's generation 0 is current.

share_formatstring

Which share map holds the position: legacy (U64F64 Alpha) or v2 (SafeFloat AlphaV2). Clients must accept values not documented yet.

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, with include=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_rao x TAO/USD at meta.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_known false. Now always null: read the account's subnet_locks (sellable_alpha_rao) and the position's collateral_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_rao instead.
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 of alpha_rao, never added; it cannot be sold. 0 when none. Truly per position, unlike a conviction lock (the account's subnet_locks). Null when it does not decode (locks_known false), 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 (see exit_by_netuid).

optionenum · can be null

The option the position is: root_stake (option A's principal, netuid 0) or subnet_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_ready until 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_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.

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

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

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's subnet_locks (never summed with them except in locked_spot_tao_rao). Null without a MinerCollateral entry (then collateral_locked_alpha_rao is 0; 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 locked is below it the hotkey's own emission is captured into the lock first (so it can exceed collateral_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 speed none, lands_as none, cost_unavailable_reason no_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: 0 on subnet stake; on root stake RootStakeUnlockInterval at the head. Null with decay / none, and on root when the interval could not be read (the hotkey runs no fund to read it from).

Format: whole number, as a string
lands_asstring

Where the proceeds land: free TAO, root stake on the same hotkey, or alpha stake. Known values: free_balance, root_stake, alpha_stake, none. New values may be added; show an unknown value as is (or generically).

cost_ratiostring · unit ratio · can be null

1 - proceeds / value given up, at this amount, now (transaction fees excluded), 8 decimals; 0 on a decaying lock (no fee: the cost is time). Null exactly with cost_unavailable_reason (checked: exactly one of the two is set).

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

Whether cost_ratio is the cost (exact) or the most it can be. Null with no cost_ratio. Known values: exact, upper_bound. New values may be added; show an unknown value as is (or generically).

cost_unavailable_reasonstring · can be null

Why cost_ratio is null: on a swap exit swap_refused, pool_not_alive (the subnet's subtoken is disabled), or the swap model's no_state / mechanism_unknown / unsupported_mechanism / inputs_missing; no_exit where nothing comes out (a perpetual lock, a miner collateral). Null exactly when cost_ratio is given. Known values: swap_refused, unpriced_holding, pool_not_alive, deposit_model_pending, no_exit, no_state, mechanism_unknown, unsupported_mechanism, inputs_missing. New values may be added; treat unknown values as unavailable.

staking_exitobject · can be null

Root positions only: unstaking the principal, instant to 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, with include=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: 0 on subnet stake; on root stake RootStakeUnlockInterval at the head. Null with decay / none, and on root when the interval could not be read (the hotkey runs no fund to read it from).

Format: whole number, as a string
lands_asstring

Where the proceeds land: free TAO, root stake on the same hotkey, or alpha stake. Known values: free_balance, root_stake, alpha_stake, none. New values may be added; show an unknown value as is (or generically).

cost_ratiostring · unit ratio · can be null

1 - proceeds / value given up, at this amount, now (transaction fees excluded), 8 decimals; 0 on a decaying lock (no fee: the cost is time). Null exactly with cost_unavailable_reason (checked: exactly one of the two is set).

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

Whether cost_ratio is the cost (exact) or the most it can be. Null with no cost_ratio. Known values: exact, upper_bound. New values may be added; show an unknown value as is (or generically).

cost_unavailable_reasonstring · can be null

Why cost_ratio is null: on a swap exit swap_refused, pool_not_alive (the subnet's subtoken is disabled), or the swap model's no_state / mechanism_unknown / unsupported_mechanism / inputs_missing; no_exit where nothing comes out (a perpetual lock, a miner collateral). Null exactly when cost_ratio is given. Known values: swap_refused, unpriced_holding, pool_not_alive, deposit_model_pending, no_exit, no_state, mechanism_unknown, unsupported_mechanism, inputs_missing. New values may be added; treat unknown values as unavailable.

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_level is 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): L1 when a reference sale of 10 alpha moves the price by less than 1 % and the alpha reserve holds at least 1,000 alpha; L2 when it holds at least 1 alpha; else L3 (less than 1 alpha, an alpha reserve of 0 or a TAO reserve of 0 included: a measured Level 3 value, the risk flag thin_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_window on /positions; the same window on the account's include=positions); 0 = none in the window (then last_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), 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.