Balances and stake of up to 50 accounts (POST)
https://api.bittensor.ai/api/v2/accounts/batch- Status
- Stable
- Auth
- API key or OAuth access token
- Scope
data:read- Rate limit
plan
Balances and stake of several accounts at one block: each item is the GET /api/v2/accounts/{address} object ({ss58, hex}, balances, stake at spot with totals and USD twins), in request order, all read at the one meta.at. meta.totals sums the batch, each distinct address once (the combined portfolio: free, priced stake and the settled total, with total_is_lower_bound when any member's total is a lower bound; the unrealized basket entitlements summed apart, never in the total). Per-item isolation: an account whose source answer breaks a rule of its own is served in place with error (SOURCE_CONTRACT) and every other member null, the rest of the batch still served; meta.items_failed counts them, and with any every meta.totals member is null (a failed item is never summed). A breach of the whole answer is a 502. The body is {addresses, at, include} with up to 50 addresses (the same cap as the GET form) and include a list; 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..50. Answered in this order; a duplicate is answered as given. An empty list is a 400
ADDRESSES_REQUIRED, more than 50 a 400BATCH_TOO_LARGE(the cap in itsdetail), 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.- includearray of string · can be null
positions: each item'spositions(every stake position atmeta.at);baskets: each item's basket positions atmeta.baskets_day;names: the top-levelincluded.names. Anything else is a 400INVALID_INCLUDE.
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 account per requested address, in request order (a duplicate is answered as given); each is the GET /api/v2/accounts/{address} object's balances, with positions on request. An item whose source answer broke its contract keeps its place with error set and every other member null.
- 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
- account_existsboolean · can be null
False when the chain has no System.Account entry at
meta.at(never created, or reaped); the balances are then a measured 0. Null when the item'serroris set (the item failed its checks).- free_raostring · unit rao (÷1e9) · can be null
Free balance (System.Account data.free), in rao. Null when the item's
erroris set (the item failed its checks).- Format: whole number, as a string · on chain: u64
- reserved_raostring · unit rao (÷1e9) · can be null
Reserved balance (data.reserved), in rao. Null when the item's
erroris set (the item failed its checks).- Format: whole number, as a string · on chain: u64
- frozen_raostring · unit rao (÷1e9) · can be null
Frozen balance (data.frozen), in rao. Null when the item's
erroris set (the item failed its checks).- Format: whole number, as a string · on chain: u64
- transferable_raostring · unit rao (÷1e9) · can be null
free - frozen, floored at 0, in rao. Null when the item's
erroris set (the item failed its checks).- Format: whole number, as a string · on chain: u64
- stake_spot_tao_raostring · unit rao (÷1e9) · can be null
The priced positions at spot: the sum of their
value_spot_tao_rao(alpha x spot price), in rao. A spot valuation, not an exit value. Never null:positions_unpricedcounts the positions left out, andtotal_is_lower_boundsays so. Null when the item'serroris set (the item failed its checks).- Format: whole number, as a string · on chain: u64
- position_countinteger · unit count · can be null
Number of stake positions at
meta.at(all of them, also when thepositionssection is cut atchild_limit;/accounts/{address}/positionslists them). Null when the item'serroris set (the item failed its checks).- positions_unpricedinteger · unit count · can be null
How many of those positions have no spot price at
meta.at(theirvalue_spot_tao_raois null). Above 0,stake_spot_tao_raoandtotal_spot_tao_raoleave them out andtotal_is_lower_boundis true. Null when the item'serroris set (the item failed its checks).- basket_entitlementobject · can be null
What a root staker is owed by its root validators' v441 basket funds (root dividends held in escrow), valued at spot, as of the latest available UTC day end at or below
meta.at(it lags the head by up to a day:as_of_day/as_of_height). Unrealized and its own figure: never intotal_spot_tao_rao(claiming costs fees and has a threshold). Null when no units are owed (every account that is no root staker) or no day is available at or belowmeta.at. Null when the item'serroris set (the item failed its checks).7 fields in basket_entitlement
- owed_unitsstring · unit shares
The fund units it is owed, summed over its funds, at
as_of_day.- Format: whole number, as a string
- spot_tao_raostring · unit rao (÷1e9)
Those units valued at each fund's spot NAV per unit at
as_of_height(the NAV'scloseanchor: spot_nav / units), floored per fund, summed, in rao of TAO: a spot valuation, not what a claim would pay. Only the valued funds:unvalued_fundscounts the rest (0 when none is valued). Never part oftotal_spot_tao_rao.- Format: whole number, as a string · on chain: u64
- basisstring
How
spot_tao_raois valued:basket_nav spot, each fund's spot NAV per unit. New values may be added; show an unknown value as is (or generically).- fundsinteger · unit count
Basket funds that owe it units (each > 0).
- unvalued_fundsinteger · unit count
Of those, the funds without a NAV at
as_of_height: left out ofspot_tao_rao.- as_of_daystring (date)
The UTC day end the entitlement is read at: the latest available day whose last block is at or below
meta.at(it lags the head by up to a day).- Format: date, YYYY-MM-DD
- as_of_heightinteger · unit block
That day's last block: where the units and NAVs are read.
- basket_entitlement_missingboolean · can be null
True for a root staker (root stake > 0 at
meta.at) whose basket entitlement isn't available yet for that block (basket_entitlementnull). It never affects the total (the entitlement is never in it). False otherwise, including for every root staker whose entitlement is served. Null when the item'serroris set (the item failed its checks).- total_spot_tao_raostring · unit rao (÷1e9) · can be null
Settled value only: free + reserved + the priced stake (
stake_spot_tao_rao), in rao (the basket entitlement is never included; it isbasket_entitlement). Never null: whentotal_is_lower_boundit is the known part, a lower bound. Null when the item'serroris set (the item failed its checks).- Format: whole number, as a string · on chain: u64
- total_is_lower_boundboolean · can be null
True exactly when a position has no price (
positions_unpriced> 0):total_spot_tao_rao(andtotal_spot_usd) then leave it out, the known part only. Show the total as 'at least'. (A missing or unvalued basket entitlement never touches the total.) Null when the item'serroris set (the item failed its checks).- free_usdstring · unit usd · 6 decimals · can be null
free_raoin USD atmeta.tao_usd(6 decimals); null exactly whenmeta.tao_usdis. Null when the item'serroris set (the item failed its checks).- Format: decimal number, as a string
- stake_spot_usdstring · unit usd · 6 decimals · can be null
stake_spot_tao_raoin USD atmeta.tao_usd(6 decimals); null exactly whenmeta.tao_usdis. Null when the item'serroris set (the item failed its checks).- Format: decimal number, as a string
- total_spot_usdstring · unit usd · 6 decimals · can be null
total_spot_tao_raoin USD atmeta.tao_usd(6 decimals): a lower bound with it. Null exactly whenmeta.tao_usdis (no TAO/USD price for that minute), never because a member is unknown. Null when the item'serroris set (the item failed its checks).- Format: decimal number, as a string
- total_incl_unclaimed_spot_tao_raostring · unit rao (÷1e9) · can be null
Total including unclaimed root rewards (
pending_tao_rao): not yet claimed and not liquid until claimed; the plain total excludes them.total_spot_tao_rao+pending_tao_rao, in rao. The unclaimed part is the root funds' entitlement claimable at the same block, at each fund's latest realizable NAV; a lower bound withtotal_is_lower_bound. Null when either part is null (an unknown unclaimed amount never counts as 0); equal tototal_spot_tao_raowhenpending_tao_raois0. Computed by this API from the served fields. Null when the item'serroris set (the item failed its checks).- Format: whole number, as a string · on chain: u64
- total_incl_unclaimed_spot_usdstring · unit usd · 6 decimals · can be null
Total including unclaimed root rewards (
pending_tao_rao): not yet claimed and not liquid until claimed; the plain total excludes them.total_incl_unclaimed_spot_tao_raoin USD atmeta.tao_usd, the pricetotal_spot_usduses (6 decimals, half away from zero). Null when either is null; equal tototal_spot_usdwhenpending_tao_raois0. Computed by this API. Null when the item'serroris set (the item failed its checks).- Format: decimal number, as a string
- locked_spot_tao_raostring · unit rao (÷1e9) · can be null · beta
The stake's locked part at spot, in rao: part of
stake_spot_tao_rao, never added to it. Every subnet lock at min(subnet_locks[].locked_alpha_rao,subnet_alpha_rao) (a lock above its holdings,exceeds_holdings, counts only the stake it binds) plus every position'scollateral_locked_alpha_rao, each at its subnet's price; on an older data version's answer, each position'slocked_alpha_raox its price. Null when a lock or collateral is not known, a locked amount is unpriced, and on an older answer. Null when the item'serroris set (the item failed its checks).- Format: whole number, as a string · on chain: u64
- locks_knownboolean · can be null · beta
Whether every lock and collateral of the account is known (
locked_spot_tao_raonull when not). Null on an older answer (locks not served). Null when the item'serroris set (the item failed its checks).- subnet_locksarray of objects · can be null · beta
The account's conviction locks, one per subnet, each binding its WHOLE alpha on the subnet, with what is sellable there (
sellable_alpha_rao);[]when none. A conviction lock is never a position's: positions carry only their miner collateral (collateral_locked_alpha_rao). Null on an older answer (there the lock was attributed to a position,positions[].locked_alpha_rao). Null when the item'serroris set (the item failed its checks).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).
- pending_tao_raostring · unit rao (÷1e9) · can be null · beta
The root funds' (basket) entitlement claimable at this block: the owed units at each fund's latest realizable NAV per unit, in rao. Unrealized and its own leg: never in
total_spot_tao_raoor any total.0when known and none; null when a fund owing units has no NAV, and on an older answer. Null when the item'serroris set (the item failed its checks).- Format: whole number, as a string · on chain: u64
- pending_unitsstring · unit shares · can be null · beta
The fund units owed (BasketRate x root stake - BasketClaimed, capped at the fund's shares), summed over the funds. Null on an older answer. Null when the item's
erroris set (the item failed its checks).- Format: whole number, as a string
- pending_knownboolean · can be null · beta
Whether the pending entitlement is known at this block. Null on an older answer. Null when the item's
erroris set (the item failed its checks).- pending_fundsinteger · unit count · can be null · beta
How many funds owe the account units. Null on an older answer. Null when the item's
erroris set (the item failed its checks).- pending_as_of_heightinteger · unit block · can be null · beta
The block the pending entitlement is read at. Null on an older answer. Null when the item's
erroris set (the item failed its checks).- accrued_unitsstring · unit shares · can be null
The owed fund units NOT bought through stake_into_basket (
pending_units-invested_units, checked): the unrealised root accrual. Never in an amount total. Null on an older answer. Null when the item'serroris set (the item failed its checks).- Format: whole number, as a string
- accrued_tao_raostring · unit rao (÷1e9) · can be null
accrued_unitsat each fund's latest realizable NAV per unit, rao (at mostpending_tao_rao, checked). Unrealised: never intotal_spot_tao_raoor any total. Null when a fund owing units has no NAV, and on an older answer. Null when the item'serroris set (the item failed its checks).- Format: whole number, as a string · on chain: u64
- invested_unitsstring · unit shares · can be null
The owed units bought through stake_into_basket since each fund's last claim (principal; an attribution). Null on an older answer. Null when the item's
erroris set (the item failed its checks).- Format: whole number, as a string
- fund_principal_spot_tao_raostring · unit rao (÷1e9) · can be null
invested_unitsat each fund's spot NAV per unit, rao: principal, which may enter a total that states its spot basis; never the accrued part, and not intotal_spot_tao_rao. Null when not known (a fund holding invested units has no spot NAV: never a partial sum;fund_principal_knownfalse), and on an older answer. Null when the item'serroris set (the item failed its checks).- Format: whole number, as a string · on chain: u64
- fund_principal_knownboolean · can be null
Whether
fund_principal_spot_tao_raois known (false exactly when it is null: a fund holding invested units has no spot NAV). Null on an older answer. Null when the item'serroris set (the item failed its checks).- positionsarray of objects · can be null
Only with
include=positions(absent otherwise): every stake position of the account atmeta.at, the rows of/accounts/{address}/positions(position_countof them). Null when the item'serroris set (the item failed its checks).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).
- basketsarray of objects · can be null
Only with
include=baskets(absent otherwise): the account's basket positions per fund atmeta.baskets_day, the rows of/accounts/{address}/baskets?at=<meta.baskets_day>;[]when none. UNREALIZED: never part oftotal_spot_tao_raoor any total. Null when the item'serroris set (the item failed its checks).25 fields in baskets (each item)
- hotkeystring
The fund (its validator hotkey), SS58 (prefix 42).
- Format: SS58 address
- root_stake_raostring · unit rao (÷1e9) · can be null
The account's root stake on that validator, rao.
- Format: whole number, as a string · on chain: u64
- owed_unitsstring · unit shares · can be null
The fund units owed to the account (the runtime-capped claim).
- Format: whole number, as a string
- claimed_units_daystring · unit shares · can be null
The units its claims burned during the day.
- Format: whole number, as a string
- fund_unitsstring · unit shares · can be null
The fund's units outstanding (BasketShares) at the day end. Null when the fund has no NAV row.
- Format: whole number, as a string
- spot_tao_raostring · unit rao (÷1e9) · can be null
owed_unitsat the fund's spot NAV per unit, floored, rao (spot: not what a claim realises). Null without the fund's NAV.- Format: whole number, as a string · on chain: u64
- realizable_tao_raostring · unit rao (÷1e9) · can be null
owed_unitsat the fund's realizable NAV per unit (the runtime's, slippage-aware), floored, rao. Clamped at the fund's whole realizable NAV, as the pallet pays a claim (min(claimable x NAV / outstanding, NAV)). Null without the fund's NAV.- Format: whole number, as a string · on chain: u64
- exactnessenum · can be null
exact(every operand read exactly: root stake, rate, watermark, the fund's NAV at the day end; a dissolved fund's 0 too) orno_nav(no NAV row at the day end, or one whose NAV is null: the value is unknown, never 0). Null on an older data version's answer.- One of:
exact,no_nav - realizable_statusstring · can be null
The state of
realizable_tao_rao:exact,no_nav(no value: the fund has no units at its NAV row) ordissolved(the fund is dissolved: a claim on it is a no-op and pays 0, whatever the NAV says). Null on an older data version's answer. New values may be added; show an unknown value as is (or generically).- dissolvedboolean · can be null
The fund's hotkey had no BasketRate at the served day end: a claim on it is a no-op and the runtime pays 0, so the position is worth
"0"(exact). Null on an older data version's answer.- last_seen_heightinteger · unit block · can be null
The fund's newest NAV row at or before the served day end (its last for a dissolved fund). Null when it has none, and on an older data version's answer.
- invested_unitsstring · unit shares · can be null
The owed units bought through stake_into_basket since the account's last claim on this fund (BasketStakedIn after its last BasketClaimed, capped at
owed_units): PRINCIPAL. An attribution (units are fungible; a claim redeems every owed unit together). Null on an older data version's answer.- Format: whole number, as a string
- invested_cost_basis_tao_raostring · unit rao (÷1e9) · can be null
The TAO those stake-ins paid (BasketStakedIn.tao), rao. Null on an older data version's answer.
- Format: whole number, as a string · on chain: u64
- invested_first_heightinteger · unit block · can be null
The first of those stake-ins (never null beside invested units, checked). Null without any, and on an older data version's answer.
- accrued_unitsstring · unit shares · can be null
owed_units-invested_units(checked): the unrealised root accrual. Never in an amount total. Null on an older data version's answer.- Format: whole number, as a string
- invested_spot_tao_raostring · unit rao (÷1e9) · can be null
invested_unitsat the fund's spot NAV per unit, floored, rao (0when the fund is dissolved). Null without the fund's NAV, and on an older data version's answer.- Format: whole number, as a string · on chain: u64
- invested_realizable_tao_raostring · unit rao (÷1e9) · can be null
invested_unitsat the fund's realizable NAV per unit, floored, rao. Null without the fund's NAV, and on an older data version's answer.- Format: whole number, as a string · on chain: u64
- accrued_spot_tao_raostring · unit rao (÷1e9) · can be null
accrued_unitsat the fund's spot NAV per unit, floored, rao: unrealised, never in a total. Null without the fund's NAV, and on an older data version's answer.- Format: whole number, as a string · on chain: u64
- accrued_realizable_tao_raostring · unit rao (÷1e9) · can be null
accrued_unitsat the fund's realizable NAV per unit, floored, rao: unrealised, never in a total. Null without the fund's NAV, and on an older data version's answer.- Format: whole number, as a string · on chain: u64
- accrued_value_at_accrual_tao_raostring · unit rao (÷1e9) · can be null
The accrued units' value when they accrued (each day's new units at that day's realizable NAV) summed since the last claim, rao. Null while not available, and on an older data version's answer.
- Format: whole number, as a string · on chain: u64
- errorobject · can be null
Null when the item is served. Set when the source's answer for this account broke its contract (per-item isolation): the item keeps its place and
address, every other member is null,meta.items_failedcounts it and everymeta.totalsmember is null. Show the account as not available (never as 0); a retry may serve it.2 fields in error
- codestring
What failed, UPPER_SNAKE (an open vocabulary).
SOURCE_CONTRACT: the data source's answer for this account broke a rule of its contract (null over wrong: never served).- detailstring
The rule that was broken, for humans (no stable wording: never parse it).
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_INCLUDE
- 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.