The return on an account's unclaimed root entitlement (fund units), per validator and combined
https://api.bittensor.ai/api/v2/accounts/{address}/baskets/returns- Status
- Beta
- Auth
- API key or OAuth access token
- Scope
data:read- Rate limit
plan
Since the basket era (2026-08-04) a root staker's dividends accrue as units of each validator's fund, owed until claimed; while unclaimed they keep the fund's alpha exposure.
Full description
Since the basket era (2026-08-04) a root staker's dividends accrue as units of each validator's fund, owed until claimed; while unclaimed they keep the fund's alpha exposure. This is what keeping them has returned: per validator (by_validator) and combined (composite), over closed UTC days.
Method (GIPS composite on the unclaimed balance): a validator's day return is its fund's NAV per unit at the close over the one before, minus 1, on the units owed at the open; units accrued, claimed or bought that day are flows, never return. The composite weights each day's returns by the validators' opening values (units x NAV per unit). Returns are chain-linked over the days that opened with units owed (a day with nothing owed is skipped and not counted in days_rated): cumulative time-weighted returns, never annualised, no blended APY. A day that opened with units owed but has no NAV makes the return null (nav_missing), never a partial chain. vs_bag_index_excess_ratio compares the composite with the bag index over the same days. NAV is the spot NAV per unit (meta.nav_basis), the basis of the funds' display price and of the bag index.
Window: from_day..to_day (inclusive UTC days) or the days ending at to_day (default 30); to_day defaults to the newest available close. At most 365 days. Units are rated from 2026-08-04 (the basket era's first whole day): a window starting earlier is clipped (meta.window.era_clipped, composite.rated_from_day), and one ending earlier is era_not_ready.
These figures value an unclaimed entitlement: never part of a stake, portfolio or account total. What a claim would pay now is GET /accounts/{address}/claim-quote.
Cached for 5 minutes (closed days). Errors are application/problem+json: INVALID_ADDRESS (address, hotkeys[i]), ADDRESSES_REQUIRED, BATCH_TOO_LARGE (hotkeys), INVALID_DAY, INVALID_DAYS, INVALID_RANGE, RANGE_TOO_LARGE (over the window's cap, or more than 60 reads of the data source for the request: narrow the window, name hotkeys, or send fewer wallets), UNKNOWN_PARAMETER, NOT_READY (503: to_day is today or not available yet), SOURCE_TIMEOUT (503), SOURCE_NOT_READY (503: this deployment's data source does not have the entitlement history yet), 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 root staker's coldkey: SS58, or 0x + 64 hex.
Query parameters
- from_dayquery· string (date)
The first UTC day,
YYYY-MM-DD, inclusive (its return is from the close before it). Not withdays(400INVALID_RANGE); afterto_daya 400INVALID_RANGE; not a date a 400INVALID_DAY.- Format: date, YYYY-MM-DD
- to_dayquery· string (date)
The last UTC day,
YYYY-MM-DD, inclusive. Default: the newest available close (yesterday once available). Never answered with an earlier day: today, or a day not available yet, is a 503NOT_READY; a later day a 400INVALID_RANGE.- Format: date, YYYY-MM-DD
- daysquery· integer · 1 to 365
The days ending at
to_day, 1..365 (default 30). Not withfrom_day.- hotkeysquery· string
Only these validators: a comma list of 1-64 hotkeys (SS58, or 0x + 64 hex; repeats count once). Each is served, a validator the account was owed nothing by as a
nothing_heldrow. Default: every validator the account was owed units by in the window.
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.
Per validator and combined.
- by_validatorarray of objects
One row per validator the account was owed units by in the window (or each of
hotkeys, never dropped: one it was owed nothing by is anothing_heldrow), by closing value, largest first; the asked validators owed nothing last, in request order.9 fields in by_validator (each item)
- hotkeyobject
The validator (its fund is its hotkey).
2 fields in hotkey
- ss58string
The account, SS58 (prefix 42).
- Format: SS58 address
- hexstring
The same 32-byte account id, 0x + 64 lower-case hex (the public key).
- Format: 32-byte hex: 0x and 64 hex digits
- twr_ratiostring · unit ratio · can be null
Time-weighted return of the unclaimed units over the days rated: each day's NAV-per-unit ratio - 1 on the units owed at the open, chain-linked, minus 1. Cumulative, never annualised. Accruals, claims and purchases are flows, never return. Decimal fraction (0.0123 = 1.23%), 12 places; null with
unavailable_reason.- can be negative
- days_ratedinteger · unit count
Days whose return is in
twr_ratio: the days that opened with units owed and a NAV at both ends. A day with nothing owed at its open is skipped and not counted.- opening_value_tao_raostring · unit rao (÷1e9) · can be null
Units owed at the window's first open (the close before
meta.window.from_day), rao at the fund's spot NAV per unit (spot NAV / units at the close), rounded half up to the rao; null when units were owed and the fund had no NAV that day.- Format: whole number, as a string · on chain: u64
- closing_value_tao_raostring · unit rao (÷1e9) · can be null
Units owed at the window's last close (
meta.window.to_day), rao at the fund's spot NAV per unit (spot NAV / units at the close), rounded half up to the rao; null when units were owed and the fund had no NAV that day. A valuation of the unclaimed entitlement: never part of a stake, portfolio or account total, and never summed with one.- Format: whole number, as a string · on chain: u64
- accrued_value_tao_raostring · unit rao (÷1e9) · can be null
Units newly owed (root dividends accrued as fund units), summed over the window, each day's units valued at that day's close; null when a day with such units had no NAV. A flow, never return.
- Format: whole number, as a string · on chain: u64
- claimed_value_tao_raostring · unit rao (÷1e9) · can be null
Units claimed (redeemed), summed over the window, each day's units valued at that day's close; null when a day with such units had no NAV. A flow, never return.
- Format: whole number, as a string · on chain: u64
- purchased_value_tao_raostring · unit rao (÷1e9) · can be null
Units bought into the fund with stake_into_basket, summed over the window, each day's units valued at that day's close; null when a day with such units had no NAV. A flow, never return.
- Format: whole number, as a string · on chain: u64
- compositeobject
The validators combined.
6 fields in composite
- twr_ratiostring · unit ratio · can be null
Each day's return is the validators' returns weighted by their opening values (units owed at the open x NAV per unit); chain-linked over the days rated, minus 1. Cumulative, never annualised; no blended APY. 12 places; null with
unavailable_reason(any validator'snav_missingmakes it null).- can be negative
- days_ratedinteger · unit count
Days in
twr_ratio: the days some validator opened with units owed (others skipped).- vs_bag_index_excess_ratiostring · unit ratio · can be null
(1 + twr_ratio) / (1 + bag index return) - 1over the same days: the bag index level at the close beforerated_from_dayto the level atrated_to_day(the index the funds' display price is benchmarked against, on the same spot basis). Null whentwr_ratiois, or the level is missing at either end (the index starts about 2026-08-26). 12 places.- can be negative
- rated_from_daystring (date) · can be null
The first day rated (its return is from the close before it), at or after
meta.window.from_day(never before 2026-08-04, the basket era's first rated day); null when no day is rated.- Format: date, YYYY-MM-DD
- rated_to_daystring (date) · can be null
The last day rated; null when no day is rated.
- Format: date, YYYY-MM-DD
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
- ADDRESS_NOT_IN_PLAN_SCOPE
- AMBIGUOUS_CREDENTIALS
- BAD_GATEWAY
- BATCH_TOO_LARGE
- BILLING_UNAVAILABLE
- BUDGET_EXCEEDED
- CONCURRENCY_LIMIT
- INSUFFICIENT_PERMISSIONS
- INTERNAL_ERROR
- INVALID_ADDRESS
- INVALID_DAY
- INVALID_DAYS
- INVALID_RANGE
- NOT_READY
- PAYMENT_REQUIRED
- PLAN_REQUIRED
- RANGE_TOO_LARGE
- RATE_LIMITED
- REPEATED_PARAMETER
- SERVICE_UNAVAILABLE
- SOURCE_BUSY
- SOURCE_NOT_READY
- SOURCE_TIMEOUT
- UNAUTHORIZED
- UNKNOWN_PARAMETER
- VALIDATION_ERROR
From the API's published specification, version 1.165.0.