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

API reference / Portfolio

An account's basket positions per fund

GET/api/v2/accounts/{address}/baskets
Status
Beta
Auth
API key or OAuth access token
Scope
data:read
Rate limit
plan

The account's v441 basket positions at a UTC day end, one row per fund (the validator hotkey) it is owed units by or holds root stake on: its root stake, the units owed, the units its claims burned that day, the fund's units and its share of them, and the owed units valued at the fund's spot and realizable NAV per unit. UNREALIZED: claiming costs fees and must clear the claim threshold, so this is never part of an account total (/accounts/{address}'s basket_entitlement is the same figure, summed). meta.totals sums the rows (unvalued_funds counts the rows without a NAV, left out of the sums). By owed units descending. at is a day or a height; an explicit one is cached as settled, the latest day (no at) 5 minutes. Errors are application/problem+json: INVALID_ADDRESS, INVALID_AT, AT_OUT_OF_COVERAGE, INVALID_INCLUDE, NOT_READY (503: no day is available yet), UNKNOWN_PARAMETER, SOURCE_TIMEOUT (503), SOURCE_NOT_READY (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 account (coldkey): SS58, or 0x + 64 hex.

Query parameters

atquery· string

The UTC day end to read: a day (YYYY-MM-DD) or a block height (the latest available day end at or below it). Default: the latest available day. Outside the available days: 400 AT_OUT_OF_COVERAGE; block 0 (the genesis block, which has no timestamp) and anything else: 400 INVALID_AT.

Format: a block height or a date, YYYY-MM-DD
includequery· string

names adds the top-level included.names: every distinct account on the page (accounts in data at any depth, event args included) keyed by its SS58 address, each {identity: {name} | null, label: {text, source, confidence, verified, inferred, as_of} | null}; the on-chain identity and the off-chain label are kept apart, and a label is never a chain fact. A missing key means 'not looked up', null means 'none'. At most 500 accounts (included.names_truncated). Still one call (the data source sideloads them in the same statement); an answer with names is cached as a head answer (names follow the head). Anything else is a 400 INVALID_INCLUDE.

Response

data is a list of objects 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.

One row per fund the account is owed units by or holds root stake on, by owed_units descending, then hotkey; [] when none.

hotkeystring

The fund (its validator hotkey), SS58 (prefix 42).

Format: SS58 address
root_stake_raostring · unit rao (÷1e9) · can be null

The account's root stake on that validator, rao.

Format: whole number, as a string · on chain: u64
owed_unitsstring · unit shares · can be null

The fund units owed to the account (the runtime-capped claim).

Format: whole number, as a string
claimed_units_daystring · unit shares · can be null

The units its claims burned during the day.

Format: whole number, as a string
fund_unitsstring · unit shares · can be null

The fund's units outstanding (BasketShares) at the day end. Null when the fund has no NAV row.

Format: whole number, as a string
fund_share_ratiostring · unit ratio · 12 decimals · can be null

owed_units / fund_units: the account's share of the fund, 12 decimals. Null with fund_units.

Format: decimal number, as a string
spot_tao_raostring · unit rao (÷1e9) · can be null

owed_units at the fund's spot NAV per unit, floored, rao (spot: not what a claim realises). Null without the fund's NAV.

Format: whole number, as a string · on chain: u64
realizable_tao_raostring · unit rao (÷1e9) · can be null

owed_units at the fund's realizable NAV per unit (the runtime's, slippage-aware), floored, rao. Clamped at the fund's whole realizable NAV, as the pallet pays a claim (min(claimable x NAV / outstanding, NAV)). Null without the fund's NAV.

Format: whole number, as a string · on chain: u64
claimable_sharesstring · unit shares · can be null

The fund units the account could claim, BasketRate x root stake - BasketClaimed, capped at the fund's units as a claim redeems (equal to owed_units). Shares, not TAO; unrealized: never income and never part of an account total. Null on an older data version's answer.

Format: whole number, as a string
fund_shares_outstandingstring · unit shares · can be null

The fund's units when its NAV was measured, one operand of realizable_tao_rao. Null without the fund's NAV row, and on an older data version's answer.

Format: whole number, as a string
fund_nav_realizable_tao_raostring · unit rao (÷1e9) · can be null

The whole fund's realizable NAV, rao: the other operand (the payout is min(claimable_shares x this / fund_shares_outstanding, this)). Null without the fund's NAV, and on an older data version's answer.

Format: whole number, as a string · on chain: u64
fund_nav_spot_tao_raostring · unit rao (÷1e9) · can be null

The whole fund's spot NAV, rao, for comparison only (a claim pays the realizable NAV). Null without the fund's NAV, and on an older data version's answer.

Format: whole number, as a string · on chain: u64
exactnessenum · can be null

exact (every operand read exactly: root stake, rate, watermark, the fund's NAV at the day end; a dissolved fund's 0 too) or no_nav (no NAV row at the day end, or one whose NAV is null: the value is unknown, never 0). Null on an older data version's answer.

One of: exact, no_nav
realizable_statusstring · can be null

The state of realizable_tao_rao: exact, no_nav (no value: the fund has no units at its NAV row) or dissolved (the fund is dissolved: a claim on it is a no-op and pays 0, whatever the NAV says). Null on an older data version's answer. New values may be added; show an unknown value as is (or generically).

dissolvedboolean · can be null

The fund's hotkey had no BasketRate at the served day end: a claim on it is a no-op and the runtime pays 0, so the position is worth "0" (exact). Null on an older data version's answer.

last_seen_heightinteger · unit block · can be null

The fund's newest NAV row at or before the served day end (its last for a dissolved fund). Null when it has none, and on an older data version's answer.

invested_unitsstring · unit shares · can be null

The owed units bought through stake_into_basket since the account's last claim on this fund (BasketStakedIn after its last BasketClaimed, capped at owed_units): PRINCIPAL. An attribution (units are fungible; a claim redeems every owed unit together). Null on an older data version's answer.

Format: whole number, as a string
invested_cost_basis_tao_raostring · unit rao (÷1e9) · can be null

The TAO those stake-ins paid (BasketStakedIn.tao), rao. Null on an older data version's answer.

Format: whole number, as a string · on chain: u64
invested_first_heightinteger · unit block · can be null

The first of those stake-ins (never null beside invested units, checked). Null without any, and on an older data version's answer.

accrued_unitsstring · unit shares · can be null

owed_units - invested_units (checked): the unrealised root accrual. Never in an amount total. Null on an older data version's answer.

Format: whole number, as a string
invested_spot_tao_raostring · unit rao (÷1e9) · can be null

invested_units at the fund's spot NAV per unit, floored, rao (0 when the fund is dissolved). Null without the fund's NAV, and on an older data version's answer.

Format: whole number, as a string · on chain: u64
invested_realizable_tao_raostring · unit rao (÷1e9) · can be null

invested_units at the fund's realizable NAV per unit, floored, rao. Null without the fund's NAV, and on an older data version's answer.

Format: whole number, as a string · on chain: u64
accrued_spot_tao_raostring · unit rao (÷1e9) · can be null

accrued_units at the fund's spot NAV per unit, floored, rao: unrealised, never in a total. Null without the fund's NAV, and on an older data version's answer.

Format: whole number, as a string · on chain: u64
accrued_realizable_tao_raostring · unit rao (÷1e9) · can be null

accrued_units at the fund's realizable NAV per unit, floored, rao: unrealised, never in a total. Null without the fund's NAV, and on an older data version's answer.

Format: whole number, as a string · on chain: u64
accrued_value_at_accrual_tao_raostring · unit rao (÷1e9) · can be null

The accrued units' value when they accrued (each day's new units at that day's realizable NAV) summed since the last claim, rao. Null while not available, and on an older data version's answer.

Format: whole number, as a string · on chain: u64

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.