Skip to content
TAO$188.32
BTC0.002928
MCap$2.22B
Vol$86.25M

API reference / Accounts

Balances and stake of up to 50 accounts (POST)

POST/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 400 BATCH_TOO_LARGE (the cap in its detail), 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.

includearray of string · can be null

positions: each item's positions (every stake position at meta.at); baskets: each item's basket positions at meta.baskets_day; names: the top-level included.names. Anything else is a 400 INVALID_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's error is 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 error is 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 error is 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 error is 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 error is 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_unpriced counts the positions left out, and total_is_lower_bound says so. Null when the item's error is 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 the positions section is cut at child_limit; /accounts/{address}/positions lists them). Null when the item's error is 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 (their value_spot_tao_rao is null). Above 0, stake_spot_tao_rao and total_spot_tao_rao leave them out and total_is_lower_bound is true. Null when the item's error is 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 in total_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 below meta.at. Null when the item's error is 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's close anchor: 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_funds counts the rest (0 when none is valued). Never part of total_spot_tao_rao.

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

How spot_tao_rao is 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 of spot_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_entitlement null). 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's error is 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 is basket_entitlement). Never null: when total_is_lower_bound it is the known part, a lower bound. Null when the item's error is 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 (and total_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's error is set (the item failed its checks).

free_usdstring · unit usd · 6 decimals · can be null

free_rao in USD at meta.tao_usd (6 decimals); null exactly when meta.tao_usd is. Null when the item's error is 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_rao in USD at meta.tao_usd (6 decimals); null exactly when meta.tao_usd is. Null when the item's error is 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_rao in USD at meta.tao_usd (6 decimals): a lower bound with it. Null exactly when meta.tao_usd is (no TAO/USD price for that minute), never because a member is unknown. Null when the item's error is 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 with total_is_lower_bound. Null when either part is null (an unknown unclaimed amount never counts as 0); equal to total_spot_tao_rao when pending_tao_rao is 0. Computed by this API from the served fields. Null when the item's error is 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_rao in USD at meta.tao_usd, the price total_spot_usd uses (6 decimals, half away from zero). Null when either is null; equal to total_spot_usd when pending_tao_rao is 0. Computed by this API. Null when the item's error is 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's collateral_locked_alpha_rao, each at its subnet's price; on an older data version's answer, each position's locked_alpha_rao x 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's error is 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_rao null when not). Null on an older answer (locks not served). Null when the item's error is 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's error is 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_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.

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_rao or any total. 0 when known and none; null when a fund owing units has no NAV, and on an older answer. Null when the item's error is 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 error is 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 error is 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 error is 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 error is 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's error is set (the item failed its checks).

Format: whole number, as a string
accrued_tao_raostring · unit rao (÷1e9) · can be null

accrued_units at each fund's latest realizable NAV per unit, rao (at most pending_tao_rao, checked). Unrealised: never in total_spot_tao_rao or any total. Null when a fund owing units has no NAV, and on an older answer. Null when the item's error is 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 error is set (the item failed its checks).

Format: whole number, as a string
fund_principal_spot_tao_raostring · unit rao (÷1e9) · can be null

invested_units at 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 in total_spot_tao_rao. Null when not known (a fund holding invested units has no spot NAV: never a partial sum; fund_principal_known false), and on an older answer. Null when the item's error is 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_rao is 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's error is set (the item failed its checks).

positionsarray of objects · can be null

Only with include=positions (absent otherwise): every stake position of the account at meta.at, the rows of /accounts/{address}/positions (position_count of them). Null when the item's error is 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_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).

basketsarray of objects · can be null

Only with include=baskets (absent otherwise): the account's basket positions per fund at meta.baskets_day, the rows of /accounts/{address}/baskets?at=<meta.baskets_day>; [] when none. UNREALIZED: never part of total_spot_tao_rao or any total. Null when the item's error is 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
fund_share_ratiostring · unit ratio · 12 decimals · can be null

owed_units / fund_units: the account's share of the fund, 12 decimals. Null with fund_units.

Format: decimal number, as a string
spot_tao_raostring · unit rao (÷1e9) · can be null

owed_units at 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_units at 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
claimable_sharesstring · unit shares · can be null

The fund units the account could claim, BasketRate x root stake - BasketClaimed, capped at the fund's units as a claim redeems (equal to owed_units). Shares, not TAO; unrealized: never income and never part of an account total. Null on an older data version's answer.

Format: whole number, as a string
fund_shares_outstandingstring · unit shares · can be null

The fund's units when its NAV was measured, one operand of realizable_tao_rao. Null without the fund's NAV row, and on an older data version's answer.

Format: whole number, as a string
fund_nav_realizable_tao_raostring · unit rao (÷1e9) · can be null

The whole fund's realizable NAV, rao: the other operand (the payout is min(claimable_shares x this / fund_shares_outstanding, this)). Null without the fund's NAV, and on an older data version's answer.

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

The whole fund's spot NAV, rao, for comparison only (a claim pays the realizable NAV). Null without the fund's NAV, and on an older data version's answer.

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) or no_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) or dissolved (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_units at the fund's spot NAV per unit, floored, rao (0 when 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_units at 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_units at 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_units at 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_failed counts it and every meta.totals member 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), 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.