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

API reference / Accounts

The node's dry run of a root-dividend claim: what it pays now, its fee and the net

GET/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_rao 0, 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 503 SERVICE_UNAVAILABLE, never this. New values may be added; show an unknown value as is (or generically).

unavailable_reasonstring · can be null

Why status is unavailable: decode_error. Null otherwise. New values may be added; treat unknown values as unavailable.

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

What the claim pays now after the dust rules: the funds' redeemable_tao_rao that 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 when unavailable.

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 unless available.

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 fund claim_root touches), by redeemable_tao_rao descending. [] when nothing is owed or unavailable.

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_rao reaches 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), 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.