What claiming an account's fund units would pay now, per fund
https://api.bittensor.ai/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 withhotkey(400INVALID_PARAMETER).- includequery· string
rows: each fund'sclaim_rows(while they are not available yet, a 503SOURCE_NOT_READY). Anything else is a 400INVALID_INCLUDE. Omitted:claim_rowsnull.
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_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.
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), 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).- 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-revalidateandstale-if-error;no-storewithX-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, withX-BTAI-Stale-As-Of,Age(its seconds since then) andWarning: 110 - "Response is Stale", andCache-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.
- ADDRESSES_REQUIRED
- AMBIGUOUS_CREDENTIALS
- BAD_GATEWAY
- BATCH_TOO_LARGE
- BILLING_UNAVAILABLE
- BUDGET_EXCEEDED
- CONCURRENCY_LIMIT
- INSUFFICIENT_PERMISSIONS
- INTERNAL_ERROR
- INVALID_ADDRESS
- INVALID_HOTKEY
- INVALID_INCLUDE
- INVALID_PARAMETER
- PAYMENT_REQUIRED
- PROTOCOL_ACCOUNT
- 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.