Skip to content
TAO$188.10
BTC0.002929
MCap$2.22B
Vol$86.25M

API reference / Accounts

Key swaps: one key's (either side), or every swap in a window

GET/api/v2/key-swaps
Status
Beta
Auth
API key or OAuth access token
Scope
data:read
Rate limit
plan

With key: the swaps naming the key as old_key or new_key, newest first, each with its direction (out: the key was swapped away; in: swapped to it).

Full description

With key: the swaps naming the key as old_key or new_key, newest first, each with its direction (out: the key was swapped away; in: swapped to it). Follow a chain of rotations by asking for the other key. Without key: every swap in from_height..to_height (inclusive; default the most recent 2,635,200 blocks, about 366 days, ending at the index's head; wider is a 400 RANGE_TOO_LARGE), direction null. kind (one kind) and the window (from_height / to_height, from_time / to_time) apply either way: with key they keep that key's swaps of that kind in that window. from_time / to_time (RFC 3339, from_time inclusive, to_time exclusive, as on the other windowed routes) are read as the first block at or after from_time and the last block before to_time; given with heights, a swap must match both; a time window holding no block answers [] with meta.window null. Newest first, keyset-paged by (height, event index) through meta.page.next_cursor; with key and a filter a page may hold fewer than limit rows while next_cursor is set. One row per swap event the chain emitted, hotkey and coldkey, every subnet generation: kind names the event (an open vocabulary: render an unknown kind generically), old_key / new_key the keys (new_key null where the event names none; coldkey_announced carries only new_key_hash), coldkey a hotkey swap's owner, netuid / generation a single-subnet hotkey swap's subnet, execution_height when a scheduled coldkey swap takes effect. Keys are {ss58, hex}. meta.coverage.from_height is the lowest block the index covers contiguously (it fills newest first, from genesis): below it swaps may be missing. What a swap changed in storage: GET /extrinsics/{height}-{extrinsic_index}/changes (the stake moved, with each alpha position sized in alpha; item=SubtensorModule.AlphaV2,SubtensorModule.TotalHotkeyAlpha keeps the positions and the pools), for a row with an extrinsic_index. Cached as the head (a swap only appends). Errors: INVALID_ADDRESS (key), INVALID_KIND, INVALID_HEIGHT, INVALID_TIME, INVALID_RANGE, RANGE_TOO_LARGE, INVALID_LIMIT, INVALID_CURSOR, INVALID_INCLUDE. Errors are application/problem+json: UNKNOWN_PARAMETER, SOURCE_TIMEOUT (503), SOURCE_NOT_READY (503: this deployment's data source is not configured or does not have key swaps 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).

Query parameters

keyquery· string

A key (hotkey or coldkey), SS58 or 0x + 64 hex: its swaps on either side. Omitted: the chain-wide listing. Anything else is a 400 INVALID_ADDRESS.

kindquery· string

One kind (see kind in the rows; any lower-case name, an unknown one lists nothing), with or without key. Anything else is a 400 INVALID_KIND.

from_heightquery· integer · 0 to 2147483647

The lowest block (inclusive). Chain-wide default: to_height - 2,635,200 (not below 0); with key: no lower bound.

to_heightquery· integer · 0 to 2147483647

The highest block (inclusive). Chain-wide default: the index's head, or from_height + 2,635,200 when that is lower; with key: the head. Below from_height is a 400 INVALID_RANGE.

from_timequery· string (date-time)

Only swaps at or after this time (RFC 3339): from the first block at or after it. Anything else is a 400 INVALID_TIME.

Format: date and time, ISO 8601 in UTC
to_timequery· string (date-time)

Only swaps before this time (RFC 3339; exclusive): up to the last block before it. Not after from_time: a 400 INVALID_RANGE.

Format: date and time, ISO 8601 in UTC
limitquery· integer · default 50 · 1 to 200

Rows per page, 1..200 (default 50). Anything else is a 400 INVALID_LIMIT.

cursorquery· string · up to 400 characters

meta.page.next_cursor of the previous page, sent back with the same other parameters (a cursor is bound to them; altered or foreign: 400 INVALID_CURSOR).

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). Read beside the answer (one more lookup); 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.

The swaps, newest first (height, then event index); [] when none.

kindstring

The swap event, by name: hotkey (HotkeySwapped), hotkey_subnet (HotkeySwappedOnSubnet: one subnet), coldkey (ColdkeySwapped: the swap executed), coldkey_scheduled (ColdkeySwapScheduled), coldkey_disputed (ColdkeySwapDisputed), coldkey_cleared (ColdkeySwapCleared), coldkey_announced (ColdkeySwapAnnounced: the new key only as new_key_hash), coldkey_reset (ColdkeySwapReset) and hotkey_retained (HotkeySwapStakeRetained, runtime 479+: when a validator swapped hotkeys, a delegator's stake on netuid stayed on the old hotkey; coldkey is that delegator). The vocabulary is open: a new swap event becomes a new value without notice, so render an unknown kind generically (its keys and block).

directionstring · can be null

Relative to the key asked for: out when it is old_key (the key swapped away from, or the announcing / disputing / clearing coldkey of a one-key event), in when it is new_key. Null on the chain-wide listing. New values may be added; show an unknown value as is (or generically).

old_keyobject

The key swapped away from; for the one-key events (coldkey_announced, coldkey_disputed, coldkey_cleared, coldkey_reset) the coldkey the event names.

2 fields in old_key
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
new_keyobject · can be null

The key swapped to; null where the event names none.

2 fields in new_key
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
new_key_hashstring · can be null

coldkey_announced: the hash of the announced new coldkey (0x + 64 hex); null otherwise.

Format: 32-byte hex: 0x and 64 hex digits
coldkeyobject · can be null

Hotkey swaps: the owning coldkey the event names; hotkey_retained: the delegator whose stake stayed on old_key; null otherwise.

2 fields in coldkey
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 · can be null

hotkey_subnet: the subnet the hotkey was swapped on; hotkey_retained: the subnet the delegator's stake stayed on; null otherwise.

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. With netuid: the subnet's life at height (see GET /subnets/generations); null otherwise.

life_start_heightinteger · unit block · can be null

The first block of the life generation names (GET /subnets/generations' start_height): use it, never generation, for heights, ages and dates. Null exactly when generation is null (root without a life, no subnet), or transiently when this API cannot read the lives. Root's generation 0 starts at 0.

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.

heightinteger · unit block

The block the event is in.

block_timestring (date-time) · can be null

The block's time, RFC 3339 UTC; null if the block is not indexed.

Format: date and time, ISO 8601 in UTC
extrinsic_indexinteger · unit id · can be null

The extrinsic the event came from (/api/v2/extrinsics/{height}-{extrinsic_index}; what the swap changed in storage, the stake moved included, is /api/v2/extrinsics/{height}-{extrinsic_index}/changes); null for a hook or a scheduled execution.

event_indexinteger · unit id

The event's index in the block.

signerobject · can be null

The extrinsic's signer; null without one.

2 fields in signer
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
execution_heightinteger · unit block · can be null

coldkey_scheduled: the block the swap takes effect; null otherwise, and on early runtimes whose event does not carry it.

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.