Skip to content
TAO$188.66
BTC0.002935
MCap$2.21B
Vol$85.76M

API reference / Accounts

What claiming an account's fund units would pay now, per fund

GET/api/v2/accounts/{address}/claim-quote
Status
Beta
Auth
API key or OAuth access token
Scope
data:read
Rate limit
plan

Per fund the account holds root stake in.

Full description

Per fund the account holds root stake in (or the one hotkey, or the set hotkeys): the units it is owed before the claim flushes the fund's queued credits (pending_credits; their slice in pending, every figure up to), its root stake, a GROSS estimate (tao_out_est_tao_rao: owed units x the fund's realizable NAV per unit at its anchor nav_anchor_height, before the claim's dust rules), what the claim pays after those rules (redeemable_tao_rao, with accrued_tao_rao, forfeited_tao_est_rao and the holdings sold / skipped at holdings_anchor_height; null on an older source answer), whether that clears RootClaimableThreshold (meta.threshold_tao_rao), and the fund's state. A quote, never a holding: never in a net worth or an account total. An account holding none answers [].

A set (hotkeys, 1-64 validators; not with hotkey): one row per selected validator (one the account holds nothing with is a nothing-owed row, never dropped) and meta.quote_totals: what claiming the selected validators now would pay out (redeemable_tao_rao over the funds that clear the threshold, the dust they would forfeit, the counts). That total is a payout QUOTE, not a holding: the one exception to "unclaimed root dividends are never summed", because it totals what claims would pay, never what the account holds. Any selected fund without a payout figure makes it null, with unavailable_reason.

Claim rows (include=rows; while they are not available yet, a 503 SOURCE_NOT_READY): each fund's claim_rows, one per holding row of the fund at holdings_anchor_height (netuid 0 = root, TAO 1:1), each the account's slice (owed units at the anchor / BasketShares, the runtime's divisor): owed_alpha_rao, spot_tao_rao, realizable_tao_rao, share_ratio and is_dust. Rows are floored one by one (as the claim pays each slot), redeemable_tao_rao once over their sum, so the non-dust rows' realizable_tao_rao plus the fund's rounding_remainder_rao (0 up to one rao a row) are redeemable_tao_rao exactly (anything else is a 502). The after-dust figures use the owed units at the anchor (owed_units_at_anchor, the runtime's basis); owed_units and the gross estimate stay the head's. A quote of what a claim would take and pay, never a holding of the account.

Head state: tip-cached. Errors are application/problem+json: INVALID_ADDRESS, INVALID_HOTKEY, INVALID_PARAMETER (hotkey with hotkeys), INVALID_INCLUDE, ADDRESSES_REQUIRED, BATCH_TOO_LARGE, UNKNOWN_PARAMETER, PROTOCOL_ACCOUNT (the fund escrow, once the data source refuses it), SOURCE_TIMEOUT (503), SOURCE_NOT_READY (503; also include=rows until the data source serves it).

Beta: this route may change with one release's notice in the v2 changelog; additive changes need none (x-stability: beta).

Path parameters

addresspath, required· string

The coldkey: SS58, or 0x + 64 hex.

Query parameters

hotkeyquery· string

Only this fund (its validator's hotkey: SS58, or 0x + 64 hex). Default: every fund.

hotkeysquery· string

A set of funds: a comma list of 1-64 validator hotkeys (SS58, or 0x + 64 hex; repeats count once), served with meta.quote_totals. Not with hotkey (400 INVALID_PARAMETER).

includequery· string

rows: each fund's claim_rows (while they are not available yet, a 503 SOURCE_NOT_READY). Anything else is a 400 INVALID_INCLUDE. Omitted: claim_rows null.

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 row per fund the account holds root stake in (or the one hotkey asked), by owed units descending; [] for an account holding none. With hotkeys: one row per selected validator, the funds held by owed units descending, then the validators the account holds nothing with (request order) as nothing-owed rows (unavailable_reason nothing_owed, fund_state null, every amount 0): never dropped.

hotkeystring

The fund's validator hotkey, SS58 (prefix 42).

Format: SS58 address
owed_unitsstring · unit count

floor(max(0, BasketRate x root stake - BasketClaimed)) capped at the fund's units, at the head, before the claim flushes the hotkey's queued credits (pending_credits: they can only add). Units.

Format: whole number, as a string
root_stake_raostring · unit rao (÷1e9)

The account's root stake on the hotkey, rao of TAO.

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

owed_units x the realizable NAV per unit at nav_anchor_height, floored, rao of TAO: an anchor-based ESTIMATE, gross, before the claim's dust rules (what the claim pays after them is redeemable_tao_rao). A quote, never a holding and never in a net worth. Null without a NAV.

Format: whole number, as a string · on chain: u64
nav_anchor_heightinteger · unit block · can be null

The fund's NAV anchor the estimate is valued at, at or below meta.at.

nav_anchorenum · can be null

That anchor's kind: a day close or a pre_claim sweep. Null with nav_anchor_height.

One of: close, pre_claim
clears_thresholdboolean · can be null

Whether what the claim pays reaches RootClaimableThreshold (meta.threshold_tao_rao): judged on redeemable_tao_rao (after the dust rules, as the runtime compares); on an older data version's answer, on the gross estimate tao_out_est_tao_rao, null with it.

pending_creditsboolean · can be null

Whether the hotkey has queued credits the claim would flush first (they can only add units).

fund_statestring · can be null

The fund's state. Null on the placeholder row of a fund not held. Known values: dissolved, no_state, off_root, active. New values may be added; show an unknown value as is (or generically).

unavailable_reasonstring · can be null

nothing_owed exactly when owed_units is 0; no_nav_row when units are owed but there is no estimate. Null otherwise. New values may be added; treat unknown values as unavailable.

pendingobject · can be null

The account's slice of the queued credits the claim flushes first, every figure up to (an upper bound). Null when there is no claim row, and on an older answer.

4 fields in pending
queued_tao_raostring · unit rao (÷1e9) · can be null

Up to: the account's slice of the flushable queued credits at their spot value, rao of TAO.

Format: whole number, as a string · on chain: u64
queued_units_eststring · unit count · can be null

Up to: queued_tao_rao / the anchor's realizable NAV per unit. Units.

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

Up to: tao_out_est_tao_rao + queued_tao_rao, gross at the anchor NAV, rao of TAO.

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

Why the figures are null: no_root_stake | no_nav_row. Null otherwise. New values may be added; treat unknown values as unavailable.

accrued_tao_raostring · unit rao (÷1e9) · can be null

The whole entitlement: owed units x every holding's realizable value per unit, rao of TAO (the runtime claim preview's accrued). Not what the claim pays. Null on an older answer.

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

What the claim pays after its dust rules (v468: dust holdings are skipped and their slices forfeited to the fund), rao of TAO, over the holdings at holdings_anchor_height. An estimate (the node's own claim preview at the head decides), never a holding. redeemable_tao_rao <= accrued_tao_rao. Null on an older data version's answer. It is computed with the owed units AT holdings_anchor_height (owed_units_at_anchor, the runtime's basis: accrued_tao_rao equals its payout at that block); an older data version's answer took the head's owed units with the anchor's holdings, so today's figure can read lower or higher than that one by the accrual after the anchor (a correction, not noise). accrued_tao_rao, forfeited_tao_est_rao, clears_threshold, rows_to_sell and dust_rows share that basis.

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

The owed slices of the skipped dust holdings, left in the fund for its other holders, rao of TAO. Null on an older answer.

Format: whole number, as a string · on chain: u64
rowsinteger · unit count · can be null

The fund's holdings at holdings_anchor_height. Null on an older answer.

rows_to_sellinteger · unit count · can be null

Holdings the claim sells. rows_to_sell + dust_rows <= rows. Null on an older answer.

dust_rowsinteger · unit count · can be null

Holdings the claim skips as dust. Null on an older answer.

holdings_anchor_heightinteger · unit block · can be null

The block whose fund holdings the dust rules ran on: the newest NAV anchor or hour end, at or below meta.at. Null without one, and on an older answer.

owed_units_at_anchorstring · unit count · can be null

The owed units at holdings_anchor_height (BasketRate, root stake, BasketClaimed and BasketShares all at that block), the owed accrued_tao_rao, redeemable_tao_rao, forfeited_tao_est_rao and claim_rows use; equal to the runtime's owed at that block. owed_units stays the head's. Null without a claim row, and on an older answer. Units.

Format: whole number, as a string
fund_state_as_of_heightinteger · unit block · can be null

The block fund_state was read at (the fund's staking option, refreshed hourly), at or below meta.at. Null with fund_state null, and when it is not available.

rounding_remainder_raostring · unit rao (÷1e9) · can be null

With include=rows: redeemable_tao_rao minus the non-dust claim_rows' realizable_tao_rao, exactly (the rows floor one by one, redeemable_tao_rao once over their sum: 0 up to one rao a row), rao of TAO. Null without include=rows, and when redeemable_tao_rao is null.

Format: whole number, as a string · on chain: u64
claim_rowsarray of objects · can be null

With include=rows: the fund's holding rows at holdings_anchor_height, by netuid (rows of them, dust_rows dust), each with the account's slice. Their non-dust realizable_tao_rao plus rounding_remainder_rao are redeemable_tao_rao exactly. [] when nothing is owed at the anchor, no holdings are known, or the fund is not held. Null without include=rows.

9 fields in claim_rows (each item)
netuidinteger · unit id

The subnet of the holding. 0 = root: TAO cash, valued 1:1.

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 at holdings_anchor_height (root: 0): netuid is a reused slot. Null when not known.

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.

owed_alpha_raostring · unit alpha_rao (÷1e9)

floor(the row's alpha x the owed units at the anchor / BasketShares): the alpha a claim takes from this row for the account, rao of the subnet's alpha (rao of TAO on root).

Format: whole number, as a string · on chain: u64
spot_tao_raostring · unit rao (÷1e9)

The slice at the pool's spot price at the anchor (min(floor(the owed units at the anchor x the row's spot value / BasketShares), the row's spot value)), rao of TAO; on root equal to owed_alpha_rao. Not what a claim pays (it sells: realizable_tao_rao).

Format: whole number, as a string · on chain: u64
realizable_tao_raostring · unit rao (÷1e9)

What the slice realizes when the claim sells the row (the runtime's slot entitlement: min(floor(the owed units at the anchor x the row's realizable value / BasketShares), the row's realizable value)), rao of TAO; on root equal to owed_alpha_rao. Floored per row, so over the rows that are not dust these sum to the fund's redeemable_tao_rao less its rounding_remainder_rao (under one rao a row). A dust row is skipped and its slice forfeited to the fund.

Format: whole number, as a string · on chain: u64
share_ratiostring · unit ratio

The account's slice of the fund: the owed units at the anchor / BasketShares (the fund's outstanding units, the runtime's divisor), a ratio 0..1 as a decimal string (18 decimals).

Format: decimal number, as a string
is_dustboolean

Whether the claim skips this row as dust (the v468 dust rules; never root): counted in dust_rows, its slice in forfeited_tao_est_rao, left in the fund for its other holders.

Response headers

10 headers: ETag, Cache-Control, CDN-Cache-Control, X-BTAI-Stale, X-BTAI-Stale-As-Of, RateLimit-Policy, RateLimit, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
ETag

Strong validator of this answer. Send it back as If-None-Match: an unchanged answer is a 304 Not Modified without a body. A settled answer's validator leaves the chain head out, so it stays valid as the head moves.

Cache-Control

One of three classes: settled public, max-age=3600, stale-while-revalidate=86400 (pinned to a block that cannot move), slow public, max-age=300, stale-while-revalidate=600 (state that moves in minutes or days) or tip public, max-age=6, stale-while-revalidate=12 (follows the chain head); the label routes are cached until the next nightly copy (public, max-age=<seconds>, stale-while-revalidate=60). Never immutable. no-store on an earlier answer served because the data source failed (X-BTAI-Stale).

CDN-Cache-Control

The same class for shared caches (RFC 9213; browsers ignore it): settled 24 h, slow 300 s, tip 6 s, each with stale-while-revalidate and stale-if-error; no-store with X-BTAI-Stale.

X-BTAI-Stale

Present only when the data source failed to answer (it timed out or was unavailable) and an earlier answer to the same request is served instead of a 503 (stale if error, RFC 5861). Then if-error, with X-BTAI-Stale-As-Of, Age (its seconds since then) and Warning: 110 - "Response is Stale", and Cache-Control: no-store: the answer is never kept as fresh, and a later request reads again. Prices and quotes are never served this way.

X-BTAI-Stale-As-Of

With X-BTAI-Stale: when the earlier answer served was produced, an RFC 3339 UTC time (2026-10-21T12:00:00Z).

RateLimit-Policy

The tier's request quota of the current window (IETF draft), e.g. "tier";q=600.

RateLimit

Requests left in the current window and the seconds until it resets (IETF draft), e.g. "tier";r=597;t=42.

X-RateLimit-Limit

The tier's request quota of the current window.

X-RateLimit-Remaining

Requests left in the current window.

X-RateLimit-Reset

When the current window resets, Unix seconds.

Status codes

200 · 304 · 400 · 401 · 402 · 403 · 404 · 429 · 500 · 502 · 503

304 Not Modified: the If-None-Match validator still matches; no body.

Error codes

The codes this endpoint can return. Each links to what it means and what to do.

From the API's published specification, version 1.165.0.