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

API reference / Portfolio

The return on up to 60 wallets' unclaimed root entitlement, combined and per wallet (POST)

POST/api/v2/accounts/baskets/returns/batch
Status
Beta
Auth
API key or OAuth access token
Scope
data:read
Rate limit
plan

GET /accounts/{address}/baskets/returns for 1..60 wallets in one answer.

Full description

GET /accounts/{address}/baskets/returns for 1..60 wallets in one answer: by_wallet holds each wallet's composite and by_validator as the GET form serves them, in request order (a repeated wallet once), and data.composite is one GIPS composite over every (wallet, validator) pair: each day's returns weighted by the pairs' opening values (units owed at the open x NAV per unit), chain-linked over the days some pair opened with units owed. It rates the wallets' unclaimed units as one portfolio; it is not a mean of the wallets' returns. Cumulative, never annualised; no blended APY. Any pair's nav_missing makes it null, never a partial chain. Prices are read once for the union of the wallets' validators. The body's unknown members are a 400 UNKNOWN_PARAMETER; the answer is not cached (no-store).

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.

Batch errors: ADDRESSES_REQUIRED, BATCH_TOO_LARGE, INVALID_ADDRESS (addresses[i], hotkeys[i]). 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).

Request body

A JSON object with these fields:

addressesarray of string

The root stakers' coldkeys, SS58 or 0x + 64 hex, 1..60, answered in this order (a repeated wallet once). An empty list is a 400 ADDRESSES_REQUIRED, more than 60 a 400 BATCH_TOO_LARGE, an invalid one a 400 INVALID_ADDRESS naming its index (addresses[i]).

from_daystring · can be null

As the GET form's from_day.

to_daystring · can be null

As the GET form's to_day.

daysinteger · can be null

As the GET form's days: 1..365 (else a 400 INVALID_DAYS), not with from_day.

hotkeysarray of string · can be null

As the GET form's hotkeys, as a list (1..64; repeats count once): every wallet is rated on these validators only, each served on every wallet (one it was owed nothing by as a nothing_held row).

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.

Combined, and per wallet.

compositeobject

ONE composite over every (wallet, validator) pair: each day's returns weighted by the pairs' opening values, chain-linked: the wallets' unclaimed units as one portfolio (not a mean of the wallets' returns). Null with unavailable_reason as the GET form's (any pair's nav_missing makes it null).

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.

by_walletarray of objects

One entry per wallet asked, in request order (a repeated wallet once); never dropped.

3 fields in by_wallet (each item)
addressobject

The wallet (coldkey).

2 fields in address
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
compositeobject

This wallet's 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.

by_validatorarray of objects

This wallet's validators, as the GET form's data.by_validator.

9 fields in by_validator (each item)
hotkeyobject

The validator (its fund is its hotkey).

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.

Response headers

6 headers: Cache-Control, RateLimit-Policy, RateLimit, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
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).

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 · 400 · 401 · 402 · 403 · 404 · 429 · 500 · 502 · 503

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.