Skip to content
TAO$188.99
BTC0.002933
MCap$2.22B
Vol$85.39M

API reference / Portfolio

Each stake position's alpha and value at every closed UTC day's end

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

Per stake position.

Full description

Per stake position (hotkey, netuid) of the coldkey that held alpha on a day of the window, one point per closed UTC day it had a share key, oldest first, at the day's last block: its exact alpha (the runtime's share arithmetic over the day-end share and pool keys), the subnet's runtime price there (root 1) and the spot value floor(alpha x price). An unpriced day serves the value null, never 0. Per day and subnet the positions' alpha is the daily stake series' (the data source's statement). hotkey / netuid narrow it. Paging back: from_day / to_day ask for an explicit window anywhere in the served history (meta.available_from_day is the oldest day served); an explicit to_day is never answered with an earlier day (one not available yet, today included, is a 503 NOT_READY). No window ceiling: a page holds at most 366 days and 60,000 position-days, meta.page.next_cursor continues with cursor, and meta.range states the whole request. While paged windows are not available yet, a window over 366 days is a 400 RANGE_TOO_LARGE, over 60,000 position-days its 400 TOO_MANY_POSITIONS, and cursor a 503 SOURCE_NOT_READY. Every life (complete across lives, never truncated): a position is (hotkey, netuid, life): a re-registration splits its series into one row per life (generation, life_start_height; null on root), ordered by netuid, hotkey, then generation; the TAO stake before dTAO (block 4,920,351) is served as netuid 0 at 1:1. While per-life rows are not available yet, one row per (hotkey, netuid) with those members null. Moves when the next day is available: cached as slow. Errors are application/problem+json: INVALID_ADDRESS, INVALID_NETUID, INVALID_DAYS, INVALID_DAY, INVALID_RANGE, INVALID_CURSOR, RANGE_TOO_LARGE, AT_OUT_OF_COVERAGE (the window ends before meta.available_from_day), TOO_MANY_POSITIONS, NOT_READY (503), UNKNOWN_PARAMETER, SOURCE_TIMEOUT (503), SOURCE_NOT_READY (503). meta.final_through_day is the key to cache closed days by: the rows through it never change again (but by an announced rerun), so pass to_day = meta.final_through_day for an answer that never changes (null on an older data version's answer).

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 coldkey: SS58, or 0x + 64 hex.

Query parameters

daysquery· integer · default 30 · at least 1

How many closed UTC days end at to_day (default 30, ending at the newest closed day; fewer where the daily stake series starts later: meta.from_day says where). No ceiling: a range longer than one page pages by cursor (while paged day windows are not available yet, more than 365 is a 400 INVALID_DAYS). Not with from_day (both: a 400 INVALID_RANGE). Outside 1..1,000,000 is a 400 INVALID_DAYS.

hotkeyquery· string

Only the positions under this hotkey (SS58, or 0x + 64 hex). Default: every one.

netuidquery· integer · 0 to 65535

Only the positions on this subnet (0 = root). Default: every one.

from_dayquery· string (date)

The window's first closed UTC day, YYYY-MM-DD (raised to meta.available_from_day). Omitted: to_day - days + 1. Not with days (both: a 400 INVALID_RANGE); not a date: a 400 INVALID_DAY; after to_day: a 400 INVALID_RANGE.

Format: date, YYYY-MM-DD
to_dayquery· string (date)

The window's last closed UTC day, YYYY-MM-DD, never moved: a day not available yet (today included) is a 503 NOT_READY, never an earlier day. Omitted: the newest closed day. With neither from_day nor to_day: the newest days days. Not a date: a 400 INVALID_DAY; after today a 400 INVALID_RANGE; a window ending before meta.available_from_day: a 400 AT_OUT_OF_COVERAGE.

Format: date, YYYY-MM-DD
cursorquery· string · up to 200 characters

meta.page.next_cursor of the previous page: the next days of a range longer than one page, sent back unchanged with the same other parameters (a changed or altered one is a 400 INVALID_CURSOR). While paged day windows are not available yet: 503 SOURCE_NOT_READY.

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 item per position that held alpha on a day of the window, by netuid then hotkey (per life too, then by generation, null first); [] when none.

hotkeyobject

The hotkey staked to, as {ss58, hex}.

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
netuidinteger · unit id

The subnet slot (0 = root).

pointsarray of objects

Oldest first, the days the position had a share key in the window (the days of this life only).

5 fields in points (each item)
daystring (date)

The UTC day.

Format: date, YYYY-MM-DD
heightinteger · unit block

The day's last block (the same for every position that day).

alpha_raostring · unit alpha_rao (÷1e9)

The position's exact alpha at that block (the runtime's share arithmetic), alpha rao; root's is TAO. 0 on a day it held none.

Format: whole number, as a string · on chain: u64
price_taostring · unit tao_per_alpha · 9 decimals · can be null

The subnet's runtime price at that block, TAO per alpha, 9 decimals (root: 1). Null when the pool has no price there.

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

floor(alpha x price), rao of TAO: a valuation, not what an unstake would realize. Null exactly when price_tao is (never 0 for an unpriced position).

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

Opaque life id (the life's registration identifier), NOT a block height; use life_start_height for the first block. The subnet life of this position's points (GET /subnets/generations). One row per (hotkey, netuid, life): a re-registration splits the series into one row per life, every life kept (the portfolio is complete across lives). Null for a netuid without a recorded life (root, and the TAO-stake era before dTAO, netuid 0), and on an older data version's answer.

is_current_lifeboolean · can be null

Whether generation is the slot's current life (true) or an ended one, re-registered since (false). Null exactly when generation is null, or transiently when this API cannot read the lives. Root's generation 0 is current.

life_start_heightinteger · unit block · can be null

That life's first block. Null exactly when generation is null.

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.