Stake positions of up to 100 accounts (POST)
https://api.bittensor.ai/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 400BATCH_TOO_LARGE, an invalid one a 400INVALID_ADDRESSnaming 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_FINALwithRetry-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_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 · 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 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 · 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 (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).- 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'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.
- 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).
- 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_heightafter decay (locked_mass x exp(-(height - last_update) / UnlockRate), or the mass itself whenperpetual; within 1 rao of the runtime's I64F64 exp), in alpha rao. Served as the chain holds it, never clamped: abovesubnet_alpha_raoonly withexceeds_holdings. Null when the lock does not decode (locks_knownfalse).- 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_blocksx 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:
speeddecay(the mass decays into unlocked alpha stake on the same subnet,lands_asalpha_stake, atcost_ratio0,exact: no fee, the cost is time) ornonewhileperpetual(cost_unavailable_reasonno_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:
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).
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), 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).- 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.
- ADDRESSES_REQUIRED
- ADDRESS_NOT_IN_PLAN_SCOPE
- AMBIGUOUS_CREDENTIALS
- AT_OUT_OF_COVERAGE
- BAD_GATEWAY
- BATCH_TOO_EXPENSIVE
- BATCH_TOO_LARGE
- BILLING_UNAVAILABLE
- BLOCK_NOT_FOUND
- BUDGET_EXCEEDED
- CONCURRENCY_LIMIT
- INSUFFICIENT_PERMISSIONS
- INTERNAL_ERROR
- INVALID_ADDRESS
- INVALID_AT
- INVALID_PARAMETER
- NOT_FINAL
- PAYMENT_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.