Skip to content
TAO$188.32
BTC0.002928
MCap$2.22B
Vol$86.25M

API reference / Accounts

Did these keys swap? Up to 500 keys' newest swaps (POST)

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

Per requested key (1..500, in request order, a duplicate once): swapped (any swap event names it, either side, any kind) and its newest limit_per_key swaps (default 1: the newest), each with its direction relative to that key.

Full description

Per requested key (1..500, in request order, a duplicate once): swapped (any swap event names it, either side, any kind) and its newest limit_per_key swaps (default 1: the newest), each with its direction relative to that key. A swap between two requested keys is listed under both. One read for the whole list: the badge check of an explorer or identity page. 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. The body's unknown members are a 400 UNKNOWN_PARAMETER; the answer is not cached (no-store). Errors: ADDRESSES_REQUIRED, BATCH_TOO_LARGE, INVALID_ADDRESS (each invalid entry named by its index), INVALID_LIMIT (limit_per_key). 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).

Request body

A JSON object with these fields:

keysarray of string

The keys (hotkeys or coldkeys), SS58 or 0x + 64 hex, 1..500, served in this order (a duplicate once). An empty list is a 400 ADDRESSES_REQUIRED, more than 500 a 400 BATCH_TOO_LARGE, an invalid one a 400 INVALID_ADDRESS naming its index (keys[i]).

limit_per_keyinteger · optional

The most swaps served per key, 1..200 (default 1: "did these keys swap", with the newest). Anything else is a 400 INVALID_LIMIT.

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 requested key, in request order (a duplicate once).

keyobject

The key, as asked (a duplicate is served once).

2 fields in 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
swappedboolean

Whether any swap event names the key on either side, of any kind (an announcement, a schedule or a dispute included: read swaps[].kind). False when none is indexed (see meta.coverage.from_height).

swapsarray of objects

Its newest limit_per_key swaps, newest first, direction relative to it; [] when none.

16 fields in swaps (each item)
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

6 headers: Cache-Control, RateLimit-Policy, RateLimit, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
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).

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 · 400 · 401 · 402 · 403 · 404 · 429 · 500 · 502 · 503

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.