Skip to content
TAO$188.58
BTC0.002932
MCap$2.21B
Vol$86.73M

API reference / Validators

What running a validator takes on up to 16 subnets: registration, pruning, permit

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

Per subnet asked (netuids, at most 16), at the state head, in one call: registration (the burn now, whether registration is open, this interval's registrations against the target, the subnet's fill and its ImmunityPeriod) with prune, who a registration replaces now (the runtime's prune rule: the owner's immortal hotkeys never, immunity within ImmunityPeriod, the non-immune pool unless too few uids are past immunity, ranked by the latest epoch's emission, then registration, then uid; root by root stake), the next prune_limit candidates with the margin to the next one; permit (the permit slots, how many are held, the lowest permit holder's stake weight in the latest epoch, StakeThreshold); and with hotkey, its standing (uid, permit, stake weight, immunity, prune rank, owner-immortal). A netuid without a subnet is {netuid, registered: false}. Hotkeys are SS58. Always the head (the state moves every block): cached as a head answer. Errors are application/problem+json: INVALID_NETUID, INVALID_ADDRESS (hotkey), INVALID_LIMIT (prune_limit), UNKNOWN_PARAMETER, SOURCE_TIMEOUT (503), SOURCE_NOT_READY (503: also while this deployment's data source has not deployed the read yet).

Beta: this route may change with one release's notice in the v2 changelog; additive changes need none (x-stability: beta).

Query parameters

netuidsquery, required· string

The subnets: a comma list of 1..16 netuids (0..65535; duplicates dropped), answered by netuid ascending. Anything else is a 400 INVALID_NETUID.

hotkeyquery· string

A hotkey (SS58 or 0x + 64 hex) whose standing to add on each subnet (hotkey). Omitted: hotkey is null. Anything else is a 400 INVALID_ADDRESS.

prune_limitquery· integer · default 3 · 1 to 32

Prune candidates per subnet, 1..32 (default 3). 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 row per netuid asked, by netuid ascending.

netuidinteger · unit id

The subnet slot asked.

registeredboolean

False: no subnet on that netuid (every other member absent). True: the members below.

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. Only when registered: the subnet's life, to join on. Null when not recorded.

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.

registrationvalue · optional

Only when registered: what registering costs and replaces.

permitvalue · optional

Only when registered: what a validator permit takes.

hotkeyobject · can be null

Only when registered: the asked hotkey's standing; null without hotkey.

7 fields in hotkey
hotkeystring

The hotkey asked, SS58.

Format: SS58 address
uidinteger · unit id · can be null

Its uid. Null: not registered on the subnet (the members below null too).

validator_permitboolean · can be null

Whether it holds a validator permit. Null without a uid.

stake_weight_alphastring · unit alpha · can be null

Its stake weight in the latest epoch (permit.epoch_height), alpha. Null without a uid or an epoch.

Format: decimal number, as a string
immuneboolean · can be null

Registered within ImmunityPeriod. Null without a uid.

prune_rankinteger · unit count · can be null

Its rank in the prune order (1 = replaced next). Null without a uid, when immortal, or when not in the pool prune.basis picks.

owner_immortalboolean · can be null

One of the owner's hotkeys the runtime never prunes. Null without a uid.

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.