Key swaps: one key's (either side), or every swap in a window
https://api.bittensor.ai/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
kindin the rows; any lower-case name, an unknown one lists nothing), with or withoutkey. Anything else is a 400INVALID_KIND.- from_heightquery· integer · 0 to 2147483647
The lowest block (inclusive). Chain-wide default:
to_height- 2,635,200 (not below 0); withkey: 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; withkey: the head. Belowfrom_heightis a 400INVALID_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 400INVALID_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_cursorof the previous page, sent back with the same other parameters (a cursor is bound to them; altered or foreign: 400INVALID_CURSOR).- includequery· string
namesadds the top-levelincluded.names: every distinct account on the page (accounts indataat 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 400INVALID_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 asnew_key_hash),coldkey_reset(ColdkeySwapReset) andhotkey_retained(HotkeySwapStakeRetained, runtime 479+: when a validator swapped hotkeys, a delegator's stake onnetuidstayed on the old hotkey;coldkeyis 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:
outwhen it isold_key(the key swapped away from, or the announcing / disputing / clearing coldkey of a one-key event),inwhen it isnew_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 onold_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_heightfor the first block. Withnetuid: the subnet's life atheight(seeGET /subnets/generations); null otherwise.- life_start_heightinteger · unit block · can be null
The first block of the life
generationnames (GET /subnets/generations'start_height): use it, nevergeneration, for heights, ages and dates. Null exactly whengenerationis null (root without a life, no subnet), or transiently when this API cannot read the lives. Root'sgeneration0 starts at 0.- 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.- 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), 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.
- AMBIGUOUS_CREDENTIALS
- BAD_GATEWAY
- BILLING_UNAVAILABLE
- BUDGET_EXCEEDED
- CONCURRENCY_LIMIT
- INSUFFICIENT_PERMISSIONS
- INTERNAL_ERROR
- INVALID_ADDRESS
- INVALID_CURSOR
- INVALID_HEIGHT
- INVALID_INCLUDE
- INVALID_KIND
- INVALID_LIMIT
- INVALID_RANGE
- INVALID_TIME
- PAYMENT_REQUIRED
- PLAN_REQUIRED
- RANGE_TOO_LARGE
- RATE_LIMITED
- REPEATED_PARAMETER
- SERVICE_UNAVAILABLE
- SOURCE_BUSY
- SOURCE_NOT_READY
- SOURCE_TIMEOUT
- UNAUTHORIZED
- UNKNOWN_PARAMETER
- VALIDATION_ERROR
From the API's published specification, version 1.165.0.