Skip to content
TAO$188.31
BTC0.002929
MCap$2.21B
Vol$86.07M

API reference / Portfolio

Stake positions of up to 100 accounts (POST)

POST/api/v2/accounts/positions/batch
Status
Stable
Auth
API key or OAuth access token
Scope
data:read
Rate limit
plan

Stake positions of several accounts at one block: one item per requested address, in request order, {address: {ss58, hex}, positions} where positions are the rows of /accounts/{address}/positions, all read at the one meta.at. The body is {addresses, at} with up to 100 addresses; the answer is not cached (no-store). The batch is atomic: one invalid address fails it. Errors are application/problem+json: ADDRESSES_REQUIRED, BATCH_TOO_LARGE, INVALID_ADDRESS (each invalid entry named by its index), BATCH_TOO_EXPENSIVE (the addresses hold more than 25,000 live stake positions together, the count in detail: split the request), INVALID_AT, AT_OUT_OF_COVERAGE, BLOCK_NOT_FOUND (404), UNKNOWN_PARAMETER, SOURCE_TIMEOUT (503), SOURCE_NOT_READY (503).

Request body

A JSON object with these fields:

addressesarray of string

The accounts (coldkeys), SS58 or 0x + 64 hex, 1..100. Answered in this order; a duplicate is answered as given. An empty list is a 400 ADDRESSES_REQUIRED, more than 100 a 400 BATCH_TOO_LARGE, an invalid one a 400 INVALID_ADDRESS naming its index (addresses[i]); the batch is atomic.

atone of several · can be null

The block to read at: a height (an integer, or the same digits as a string), a 0x block hash or an RFC 3339 time. Default: the head. A time the indexed head has not reached yet is a 503 NOT_FINAL with Retry-After.

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.

One entry per requested address, in request order (a duplicate is answered as given).

addressobject

The account, as {ss58, hex}.

2 fields in address
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
positionsarray of objects

Its positions holding alpha, ordered by netuid then hotkey (the rows of /accounts/{address}/positions); [] when there are none.

21 fields in positions (each item)
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 · beta

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 · beta

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 · beta

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

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

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

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.

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

locks_knownboolean · can be null · beta

Whether every lock and collateral of the account is known. Null on an older answer.

subnet_locksarray of objects · can be null · beta

The account's conviction locks, one per subnet, each binding its whole alpha there, with what is sellable; [] when none. Null on an older answer.

12 fields in subnet_locks (each item)
netuidinteger · unit id

The subnet slot the lock is on.

hotkeystring

The conviction TARGET (the lock's third key), SS58 (prefix 42). Not where the locked alpha sits: the lock binds every position of the account on the subnet, and the account may hold none on this hotkey (target_position_held).

Format: SS58 address
locked_alpha_raostring · unit alpha_rao (÷1e9) · can be null

The lock's mass at meta.locks_as_of_height after decay (locked_mass x exp(-(height - last_update) / UnlockRate), or the mass itself when perpetual; within 1 rao of the runtime's I64F64 exp), in alpha rao. Served as the chain holds it, never clamped: above subnet_alpha_rao only with exceeds_holdings. Null when the lock does not decode (locks_known false).

Format: whole number, as a string · on chain: u64
perpetualboolean

True when the lock does not decay (DecayingLock(coldkey, netuid) false).

last_update_heightinteger · unit block · can be null

The block the lock's decay clock was last reset at. Null when not known.

subnet_alpha_raostring · unit alpha_rao (÷1e9)

The account's alpha on the subnet at the block, every position there summed, in alpha rao: what the lock binds (never one position).

Format: whole number, as a string · on chain: u64
target_position_heldboolean

Whether the account holds a position on the target hotkey on this subnet.

exceeds_holdingsboolean · can be null

True when the chain holds a lock above the account's alpha on the subnet (locked_alpha_rao > subnet_alpha_rao): served as is, never clamped; nothing on the subnet is then sellable. False otherwise. Null when the lock is not known.

sellable_alpha_raostring · unit alpha_rao (÷1e9) · can be null

What the account can unstake on the subnet now: max(subnet_alpha_rao - locked_alpha_rao - the subnet's positions' collateral_locked_alpha_rao, 0), in alpha rao. One amount for the whole subnet, shared by its positions. Null when the lock or a collateral there is not known.

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

The lock's conviction rolled forward to meta.locks_as_of_height (LockState.conviction, U64F64, floored; the runtime's roll_forward_lock, equal to StakeInfoRuntimeApi.get_coldkey_lock): it grows toward the mass while the lock is held (MaturityRate) and, on a lock on the subnet owner's hotkey, equals the mass. In alpha rao. A measure of commitment, never an amount held or sellable, never in a total. Null when the lock does not decode, and on an older data-source answer.

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

How the lock unwinds from the block if nothing is added or moved (null exactly when perpetual: a perpetual lock never decays; checked). Null too when the lock does not decode, and on an older data-source answer.

3 fields in decay
tau_blocksstring · unit blocks

UnlockRate, the decay timescale in blocks (live; default 934,866), a u64 string.

Format: whole number, as a string
half_life_blocksstring · unit blocks

round(tau_blocks x ln 2): blocks for the lock to halve (648,000 at the default, about 90 days).

Format: whole number, as a string
schedulearray of objects

The mass after 30, 90, 180 and 365 days, in that order (exactly those four; checked).

exitobject · can be null

How the locked alpha leaves the lock: speed decay (the mass decays into unlocked alpha stake on the same subnet, lands_as alpha_stake, at cost_ratio 0, exact: no fee, the cost is time) or none while perpetual (cost_unavailable_reason no_exit); no hold (checked). Null on an older data-source answer.

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.

Response headers

6 headers: Cache-Control, RateLimit-Policy, RateLimit, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
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).

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 · 400 · 401 · 402 · 403 · 404 · 429 · 500 · 502 · 503

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.