Skip to content
TAO$188.12
BTC0.002928
MCap$2.21B
Vol$86.07M

API reference / Accounts

What claiming fund units would pay, for up to 60 accounts (POST)

POST/api/v2/accounts/claim-quote/batch
Status
Beta
Auth
API key or OAuth access token
Scope
data:read
Rate limit
plan

The claim quote of 1-60 accounts at ONE anchor (meta.at, shared): one item per requested address, in request order, {address, funds, quote_totals, error}, funds the rows of GET /accounts/{address}/claim-quote (with hotkeys the set's, with include=rows each fund's claim_rows). quote_totals is per account (with hotkeys): a payout QUOTE, never a holding, never summed across accounts. Unclaimed value is never an amount total. A protocol account (the fund escrow) is served in place with error protocol_account and funds null; the rest of the batch is still served.

While this route is not available yet, it is a 503 SOURCE_NOT_READY. The body is {addresses, hotkeys, include}; 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), INVALID_INCLUDE, UNKNOWN_PARAMETER, SOURCE_TIMEOUT (503), SOURCE_NOT_READY (503).

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

Request body

A JSON object with these fields:

addressesarray of string

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

hotkeysarray of string · can be null

A set of funds (validator hotkeys, SS58 or 0x + 64 hex, 1-64; repeats count once): each account's funds are the set's (a validator it holds nothing with is a nothing-owed row) with its own quote_totals. Omitted: every fund of each account, quote_totals null.

includearray of string · can be null

rows: each fund's claim_rows. 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 item per requested address, in request order.

addressstring

The account, SS58 (prefix 42).

Format: SS58 address
fundsarray of objects · can be null

The account's funds, as data of GET /accounts/{address}/claim-quote (with hotkeys: the set's rows). [] for an account holding none. Null exactly with error.

22 fields in funds (each item)
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.

quote_totalsobject · can be null

With hotkeys only: this account's payout QUOTE total over the set, never a holding and never summed across accounts. Null without hotkeys, and with error.

6 fields in quote_totals
redeemable_tao_raostring · unit rao (÷1e9) · can be null

What claiming the selected validators now would pay out: the sum of redeemable_tao_rao (after the claim dust rules) over the funds whose claim clears the threshold (clears_threshold; a claim below it pays nothing), rao of TAO. A payout QUOTE, not a holding: never add it to a balance. Before the queued credits a claim flushes first (pending, up to). Null when any selected fund has no payout figure (unavailable_reason): never a partial sum.

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

What those claims would leave in their funds as dust (forfeited_tao_est_rao over the same funds), rao of TAO. Null exactly with redeemable_tao_rao.

Format: whole number, as a string · on chain: u64
fundsinteger · unit count

The selected validators: the rows of data.

unpriced_fundsinteger · unit count

Selected funds without a payout figure (redeemable_tao_rao null: owed units without a NAV, or an older source answer). Any makes the amounts null.

paying_fundsinteger · unit count

Selected funds whose claim clears the threshold: the ones the amounts sum.

unavailable_reasonstring · can be null

Why the amounts are null: partial_answer (the data source's answer states no payout after the dust rules) | unpriced_funds (a selected fund has no payout figure). Null otherwise. New values may be added; treat unknown values as unavailable.

errorenum · can be null

Why this account has no quote, the rest of the batch still served: protocol_account (a protocol account such as the fund escrow modl...beta/esc: custody, never a claimant) | invalid_address (the data source could not decode it; not expected, this API checks every address first). An account with nothing owed is not an error (funds []). Null otherwise.

One of: invalid_address, protocol_account

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.