Each stake position's alpha and value at every closed UTC day's end
https://api.bittensor.ai/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_daysays where). No ceiling: a range longer than one page pages bycursor(while paged day windows are not available yet, more than 365 is a 400INVALID_DAYS). Not withfrom_day(both: a 400INVALID_RANGE). Outside 1..1,000,000 is a 400INVALID_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 tometa.available_from_day). Omitted:to_day-days+ 1. Not withdays(both: a 400INVALID_RANGE); not a date: a 400INVALID_DAY; afterto_day: a 400INVALID_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 503NOT_READY, never an earlier day. Omitted: the newest closed day. With neitherfrom_daynorto_day: the newestdaysdays. Not a date: a 400INVALID_DAY; after today a 400INVALID_RANGE; a window ending beforemeta.available_from_day: a 400AT_OUT_OF_COVERAGE.- Format: date, YYYY-MM-DD
- cursorquery· string · up to 200 characters
meta.page.next_cursorof 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 400INVALID_CURSOR). While paged day windows are not available yet: 503SOURCE_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_taois (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_heightfor 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
generationis the slot's current life (true) or an ended one, re-registered since (false). Null exactly whengenerationis null, or transiently when this API cannot read the lives. Root'sgeneration0 is current.- life_start_heightinteger · unit block · can be null
That life's first block. Null exactly when
generationis 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), 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).- 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-revalidateandstale-if-error;no-storewithX-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, withX-BTAI-Stale-As-Of,Age(its seconds since then) andWarning: 110 - "Response is Stale", andCache-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.
- ADDRESS_NOT_IN_PLAN_SCOPE
- AMBIGUOUS_CREDENTIALS
- AT_OUT_OF_COVERAGE
- BAD_GATEWAY
- BILLING_UNAVAILABLE
- BUDGET_EXCEEDED
- CONCURRENCY_LIMIT
- INSUFFICIENT_PERMISSIONS
- INTERNAL_ERROR
- INVALID_ADDRESS
- INVALID_CURSOR
- INVALID_DAY
- INVALID_DAYS
- INVALID_NETUID
- INVALID_RANGE
- NOT_READY
- PAYMENT_REQUIRED
- RANGE_TOO_LARGE
- RATE_LIMITED
- REPEATED_PARAMETER
- SERVICE_UNAVAILABLE
- SOURCE_BUSY
- SOURCE_NOT_READY
- SOURCE_TIMEOUT
- TOO_MANY_POSITIONS
- UNAUTHORIZED
- UNKNOWN_PARAMETER
- VALIDATION_ERROR
From the API's published specification, version 1.165.0.