The node's dry run of a root-dividend claim: what it pays now, its fee and the net
https://api.bittensor.ai/api/v2/accounts/{address}/claim-preview- Status
- Beta
- Auth
- API key or OAuth access token
- Scope
data:read- Rate limit
plan
What claiming would pay now, from the chain node's own runtime claim preview at its best block.
Full description
What claiming would pay now, from the chain node's own runtime claim preview at its best block (BetaBasketRuntimeApi, the claim dust rules applied), for one validator's fund (hotkey, the claim_root_with_hotkey call) or every fund (claim_root), priced with the call's transaction fee: redeemable_tao_rao (the funds that clear RootClaimableThreshold; a claim below it pays nothing), fee_estimate_tao_rao and net_after_fee_tao_rao (signed: negative when the claim costs more than it pays), with the per-fund rows. A dry run: no signing request is created. status: available, nothing_owed (the node answered, nothing is owed), unavailable (the node answered in a shape this API cannot read, unavailable_reason). A quote, never a holding: never in a net worth or an account total. Without hotkey, claim_root is refused by the chain for a coldkey staking through two or more hotkeys (RootClaimTooHeavy): preview each fund with hotkey then.
Reads the chain node, not the data source: at most 30 previews per caller per minute (429 RATE_LIMITED with Retry-After), on top of the tier's limits. A node that does not answer is a 503 SERVICE_UNAVAILABLE with Retry-After, never an empty answer. Cached as a quote (tip). Errors are application/problem+json: INVALID_ADDRESS, UNKNOWN_PARAMETER, RATE_LIMITED (429), SERVICE_UNAVAILABLE (503).
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
The validator whose fund to claim (SS58, or 0x + 64 hex):
claim_root_with_hotkey. Default: every fund (claim_root).
Response
data is an object 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.
The preview.
- hotkeystring · can be null
The validator whose fund is claimed (SS58), or null for every fund (
claim_root).- Format: SS58 address
- callenum
The call previewed and priced: one fund (
hotkey) or every fund.- One of:
claim_root_with_hotkey,claim_root - statusstring
available: something is owed, the figures are the node's;nothing_owed: the node answered and nothing is owed (redeemable_tao_rao0, no fee read);unavailable: the node answered in a shape this API cannot read (unavailable_reason), every figure null. A node that does not answer is a 503SERVICE_UNAVAILABLE, never this. New values may be added; show an unknown value as is (or generically).- redeemable_tao_raostring · unit rao (÷1e9) · can be null
What the claim pays now after the dust rules: the funds'
redeemable_tao_raothat clear the threshold, summed (a fund below it pays nothing), rao of TAO. A payout QUOTE, never a holding: never add it to a balance. Null whenunavailable.- Format: whole number, as a string · on chain: u64
- fee_estimate_tao_raostring · unit rao (÷1e9) · can be null
The claim call's transaction fee estimate (from the free balance), rao of TAO. Null unless
available.- Format: whole number, as a string · on chain: u64
- net_after_fee_tao_raostring · unit rao (÷1e9) · can be null
redeemable_tao_rao-fee_estimate_tao_rao, rao of TAO, signed: negative when the claim costs more than it pays. Null unlessavailable.- Format: whole number, as a string · can be negative
- threshold_tao_raostring · unit rao (÷1e9) · can be null
RootClaimableThreshold[ROOT] at the node's best block, rounded up to rao. Null when
unavailable.- Format: whole number, as a string · on chain: u64
- is_above_thresholdboolean · can be null
Whether any previewed fund clears the threshold (the claim pays). Null when
unavailable.- paying_fundsinteger · unit count · can be null
Funds whose payout clears the threshold. Null when
unavailable.- fundsarray of objects
Per fund with something owed (the one
hotkey, or every fundclaim_roottouches), byredeemable_tao_raodescending.[]when nothing is owed orunavailable.9 fields in funds (each item)
- hotkeystring
The fund's validator hotkey, SS58 (prefix 42).
- Format: SS58 address
- owed_unitsstring · unit count
The fund units the account is owed at the node's best block. Units.
- Format: whole number, as a string
- accrued_tao_raostring · unit rao (÷1e9)
The whole entitlement at every holding's realizable value, rao of TAO. Not the payout.
- Format: whole number, as a string · on chain: u64
- redeemable_tao_raostring · unit rao (÷1e9)
What a claim on this fund pays after the dust rules, rao of TAO, when it clears the threshold (
is_above_threshold; below it the claim pays nothing). A quote, never a holding.- Format: whole number, as a string · on chain: u64
- forfeited_tao_est_raostring · unit rao (÷1e9)
The owed slices of the skipped dust holdings, left in the fund, rao of TAO.
- Format: whole number, as a string · on chain: u64
- rowsinteger · unit count
The fund's holdings.
- rows_to_sellinteger · unit count
Holdings the claim sells.
- dust_rowsinteger · unit count
Holdings the claim skips as dust.
- is_above_thresholdboolean
Whether
redeemable_tao_raoreaches RootClaimableThreshold (threshold_tao_rao).
- at_heightinteger · unit block · can be null
The node's best block the preview ran at (not necessarily final). Null when
unavailable.- at_block_hashstring · can be null
That block's hash. Null when
unavailable.
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.
From the API's published specification, version 1.165.0.