The return on up to 60 wallets' unclaimed root entitlement, combined and per wallet (POST)
https://api.bittensor.ai/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 400BATCH_TOO_LARGE, an invalid one a 400INVALID_ADDRESSnaming 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 400INVALID_DAYS), not withfrom_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 anothing_heldrow).
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_reasonas the GET form's (any pair'snav_missingmakes 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'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
- 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'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
- 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
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), 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).- 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.
- 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_PARAMETER
- INVALID_RANGE
- NOT_READY
- PAYMENT_REQUIRED
- PLAN_REQUIRED
- RANGE_TOO_LARGE
- RATE_LIMITED
- SERVICE_UNAVAILABLE
- SOURCE_BUSY
- SOURCE_NOT_READY
- SOURCE_TIMEOUT
- UNAUTHORIZED
- UNKNOWN_PARAMETER
- VALIDATION_ERROR
From the API's published specification, version 1.165.0.