What claiming fund units would pay, for up to 60 accounts (POST)
https://api.bittensor.ai/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 400BATCH_TOO_LARGE, an invalid one a 400INVALID_ADDRESSnaming 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
fundsare the set's (a validator it holds nothing with is a nothing-owed row) with its ownquote_totals. Omitted: every fund of each account,quote_totalsnull.- includearray of string · can be null
rows: each fund'sclaim_rows. 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 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
dataofGET /accounts/{address}/claim-quote(withhotkeys: the set's rows).[]for an account holding none. Null exactly witherror.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_unitsx the realizable NAV per unit atnav_anchor_height, floored, rao of TAO: an anchor-based ESTIMATE, gross, before the claim's dust rules (what the claim pays after them isredeemable_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
- clears_thresholdboolean · can be null
Whether what the claim pays reaches RootClaimableThreshold (
meta.threshold_tao_rao): judged onredeemable_tao_rao(after the dust rules, as the runtime compares); on an older data version's answer, on the gross estimatetao_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).- 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
- 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 ATholdings_anchor_height(owed_units_at_anchor, the runtime's basis:accrued_tao_raoequals 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_sellanddust_rowsshare 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 owedaccrued_tao_rao,redeemable_tao_rao,forfeited_tao_est_raoandclaim_rowsuse; equal to the runtime's owed at that block.owed_unitsstays 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_statewas read at (the fund's staking option, refreshed hourly), at or belowmeta.at. Null withfund_statenull, and when it is not available.- rounding_remainder_raostring · unit rao (÷1e9) · can be null
With
include=rows:redeemable_tao_raominus the non-dustclaim_rows'realizable_tao_rao, exactly (the rows floor one by one,redeemable_tao_raoonce over their sum: 0 up to one rao a row), rao of TAO. Null withoutinclude=rows, and whenredeemable_tao_raois 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 atholdings_anchor_height, by netuid (rowsof them,dust_rowsdust), each with the account's slice. Their non-dustrealizable_tao_raoplusrounding_remainder_raoareredeemable_tao_raoexactly.[]when nothing is owed at the anchor, no holdings are known, or the fund is not held. Null withoutinclude=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_heightfor the first block. The life of the subnet occupyingnetuidatholdings_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
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.- 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'sredeemable_tao_raoless itsrounding_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
- is_dustboolean
Whether the claim skips this row as dust (the v468 dust rules; never root): counted in
dust_rows, its slice inforfeited_tao_est_rao, left in the fund for its other holders.
- quote_totalsobject · can be null
With
hotkeysonly: this account's payout QUOTE total over the set, never a holding and never summed across accounts. Null withouthotkeys, and witherror.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_raoover the same funds), rao of TAO. Null exactly withredeemable_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_raonull: 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.
- 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 escrowmodl...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), 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
- AMBIGUOUS_CREDENTIALS
- BAD_GATEWAY
- BATCH_TOO_LARGE
- BILLING_UNAVAILABLE
- BUDGET_EXCEEDED
- CONCURRENCY_LIMIT
- INSUFFICIENT_PERMISSIONS
- INTERNAL_ERROR
- INVALID_ADDRESS
- INVALID_INCLUDE
- INVALID_PARAMETER
- 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.