Skip to content
TAO$188.76
BTC0.002936
MCap$2.21B
Vol$85.76M

API reference / Portfolio

Alpha history of one stake position

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

Every block in which one stake position (the account's shares of hotkey on netuid) changed, newest first: the exact alpha before and after (the runtime's own share arithmetic, equal to StakeInfo), the extrinsic and outer call or the block hook, the event that explains it, a category, the emission components a block hook credited, and the change valued at its own block (price_tao, delta_spot_tao_rao, delta_spot_usd). Nominator dividends grow the hotkey's pool, not the shares, so they are value growth, not rows. limit is at most 200 here (default 50): every row is valued on read. Pages go back in time through meta.page.next_cursor, which is present only when another page exists. The page that reaches meta.coverage.from_height has meta.page.end_of_coverage: true. meta.page.has_older_outside_coverage (a boolean on every page) says whether older history exists below coverage (not served yet). Errors are application/problem+json: INVALID_ADDRESS, INVALID_NETUID, INVALID_LIMIT, INVALID_CURSOR, POSITION_NOT_FOUND (404, the account never held shares of this hotkey on this subnet), UNKNOWN_PARAMETER, SOURCE_TIMEOUT (503), SOURCE_NOT_READY (503), RECALCULATING (503, Retry-After: the history is being recalculated under a corrected method; retry after it).

Path parameters

addresspath, required· string

The account (coldkey): SS58, or 0x + 64 hex.

hotkeypath, required· string

The hotkey the stake sits on: SS58, or 0x + 64 hex.

netuidpath, required· integer · 0 to 65535

Subnet slot of the position (0 = root).

Query parameters

limitquery· integer · default 50 · 1 to 200

Page size, 1..200 (this route's cap; above it is a 400 INVALID_LIMIT).

cursorquery· string · up to 200 characters

meta.page.next_cursor of the previous page, passed back unchanged with the same other parameters. It is opaque and bound to them: a cursor used with different parameters, or altered, is a 400 INVALID_CURSOR.

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 block in which the position changed, newest first; [] when none in coverage.

heightinteger · unit block

Block in which the position's shares changed.

timestring (date-time)

Timestamp of that block, RFC 3339 UTC.

Format: date and time, ISO 8601 in UTC
phasestring · can be null

When in the block the share write happened: extrinsic, block_start (on_initialize hooks) or block_end (on_finalize hooks). Null when no share write in the block explains the change. Clients must accept values not documented yet.

extrinsicstring · unit id · can be null

The extrinsic (height-index) that made the change; null for a block hook.

Format: block and index, such as 4200000-3
callstring · can be null

Pallet.call of that extrinsic (the OUTER call); null for a block hook.

eventstring · can be null

SubtensorModule event that explains the change (it names the hotkey or the account); null when none does.

event_indexinteger · unit id · can be null

Index of that event in the block; null with event.

categorystring

What the change was: stake, unstake, move_stake, validator_take, miner_incentive, root_take, owner_cut, basket_flush_credit, emission (several components in one block: see emission), root_claim, coldkey_swap, hotkey_swap or other. Nominator dividends accrue to the hotkey's pool, not to shares, so they show as value growth, not as rows. Clients must accept values not documented yet.

emissionarray of objects · can be null

Block-hook emission credited to this position in this block, per component. Null outside hooks.

2 fields in emission (each item)
componentstring

Which emission: validator_take, miner_incentive, root_take, owner_cut or basket_flush_credit. Clients must accept values not documented yet.

alpha_raostring · unit alpha_rao (÷1e9)

Alpha credited by this component in the block, in alpha rao.

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

Share map holding the position after the block: legacy (U64F64 Alpha) or v2 (SafeFloat AlphaV2); null when neither holds it (the position closed). Clients must accept values not documented yet.

alpha_before_raostring · unit alpha_rao (÷1e9)

Exact alpha of the position after block height - 1 (= StakeInfo), in alpha rao.

Format: whole number, as a string · on chain: u64
alpha_after_raostring · unit alpha_rao (÷1e9)

Exact alpha of the position after block height (= StakeInfo), in alpha rao.

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

alpha_after_rao - alpha_before_rao, signed, in alpha rao.

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

Spot price of one alpha in TAO at height (1 on root), 9 decimals: the price the change is valued at. Null when no pool price is known.

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

alpha_delta_rao x price_tao, truncated, signed, in rao of TAO: a spot valuation of the change at its own block, not what unstaking would pay. Null when the price is.

Format: whole number, as a string · can be negative
delta_spot_usdstring · unit usd · 6 decimals · can be null

delta_spot_tao_rao in USD at the TAO/USD price of the block's own minute (an amount), signed, 6 decimals. Null when either price is missing.

Format: decimal number, as a string · can be negative

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.