Skip to content
TAO$188.31
BTC0.002929
MCap$2.21B
Vol$86.07M

API reference / Portfolio

The return on an account's unclaimed root entitlement (fund units), per validator and combined

GET/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 with days (400 INVALID_RANGE); after to_day a 400 INVALID_RANGE; not a date a 400 INVALID_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 503 NOT_READY; a later day a 400 INVALID_RANGE.

Format: date, YYYY-MM-DD
daysquery· integer · 1 to 365

The days ending at to_day, 1..365 (default 30). Not with from_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_held row. 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 a nothing_held row), 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
unavailable_reasonstring · can be null

Why twr_ratio is null, else null: nothing_held (no day of the window opened with units owed: nothing to rate), nav_missing (a day that opened with units owed has no NAV at its open or close: the chain is not computed partially), era_not_ready (the whole window is before 2026-08-04: root dividends then accrued in alpha, before the basket era, and are not available per staker). New values may be added; treat unknown values as unavailable.

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's nav_missing makes 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) - 1 over the same days: the bag index level at the close before rated_from_day to the level at rated_to_day (the index the funds' display price is benchmarked against, on the same spot basis). Null when twr_ratio is, 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
unavailable_reasonstring · can be null

Why twr_ratio is null, else null: nothing_held (no day of the window opened with units owed: nothing to rate), nav_missing (a day that opened with units owed has no NAV at its open or close: the chain is not computed partially), era_not_ready (the whole window is before 2026-08-04: root dividends then accrued in alpha, before the basket era, and are not available per staker). New values may be added; treat unknown values as 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.