Skip to content
TAO$188.12
BTC0.002928
MCap$2.21B
Vol$86.07M

API reference / Hotkeys

A hotkey's childkey family on one subnet

GET/api/v2/hotkeys/{hotkey}/family
Status
Beta
Auth
API key or OAuth access token
Scope
data:read
Rate limit
plan

A validator's childkey family in one call, at the state head: the hotkey itself (Owner coldkey, take, its childkey take as stored and as paid (childkey_take_effective_ratio = max(stored, the subnet's floor), childkey_take_is_floored), its alpha and root stake); family, what its UID weighs after childkey inheritance (inherited alpha and root stake, the stake weight = alpha + root x TaoWeight, TaoWeight, the subnet's childkey take floor); and its children and parents (ChildKeys / ParentKeys, in the chain's order), each with the edge's proportion_ratio and the same members. Accounts are SS58. netuid is required. Head state: cached as such. Errors are application/problem+json: INVALID_ADDRESS, INVALID_NETUID, UNKNOWN_PARAMETER, SOURCE_TIMEOUT (503), SOURCE_NOT_READY (503).

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

Path parameters

hotkeypath, required· string

The hotkey: SS58, or 0x + 64 hex.

Query parameters

netuidquery, required· integer · 0 to 65535

The subnet slot (required).

Response

data is an object 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 hotkey's family on the subnet.

hotkeyobject

The hotkey, as {ss58, hex}.

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

The subnet slot asked for.

selfobject

The hotkey's own Owner, takes and stake on the subnet (wire name self).

7 fields in self
coldkeystring · can be null

Its Owner coldkey, SS58. Null without an Owner entry.

Format: SS58 address
take_ratiostring · unit ratio · can be null

Delegates (the validator take) / 65535, a ratio 0..1. Null when not a delegate.

Format: decimal number, as a string
childkey_take_ratiostring · unit ratio · can be null

ChildkeyTake(hotkey, netuid) / 65535 as stored (0 when unset), a ratio 0..1.

Format: decimal number, as a string
childkey_take_effective_ratiostring · unit ratio · can be null

max(stored, the subnet's floor) / 65535: what the runtime pays (get_childkey_take), a ratio 0..1.

Format: decimal number, as a string
childkey_take_is_flooredboolean

True when the stored take is below the subnet's floor.

alpha_stake_raostring · unit alpha_rao (÷1e9) · can be null

TotalHotkeyAlpha on the subnet, alpha rao.

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

TotalHotkeyAlpha on root (netuid 0): TAO 1:1, rao.

Format: whole number, as a string · on chain: u64
familyobject

What its UID weighs after childkey inheritance.

5 fields in family
alpha_stake_raostring · unit alpha_rao (÷1e9) · can be null

Inherited alpha: its own x (1 - the children's proportions) + each parent's alpha x proportion, alpha rao.

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

Inherited root stake by the same rule, rao of TAO. Null on root itself.

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

Inherited alpha + inherited root x TaoWeight: the stake the epoch weighs the UID by, in alpha rao units.

Format: whole number, as a string · on chain: u64
tao_weight_ratiostring · unit ratio · can be null

TaoWeight / u64::MAX, a ratio 0..1.

Format: decimal number, as a string
childkey_take_floor_ratiostring · unit ratio · can be null

max(MinChildkeyTake, MinChildkeyTakePerSubnet(netuid)) / 65535: the subnet's childkey take floor, a ratio 0..1.

Format: decimal number, as a string
childrenarray of objects

ChildKeys(hotkey, netuid), in the chain's order.

9 fields in children (each item)
coldkeystring · can be null

Its Owner coldkey, SS58. Null without an Owner entry.

Format: SS58 address
take_ratiostring · unit ratio · can be null

Delegates (the validator take) / 65535, a ratio 0..1. Null when not a delegate.

Format: decimal number, as a string
childkey_take_ratiostring · unit ratio · can be null

ChildkeyTake(hotkey, netuid) / 65535 as stored (0 when unset), a ratio 0..1.

Format: decimal number, as a string
childkey_take_effective_ratiostring · unit ratio · can be null

max(stored, the subnet's floor) / 65535: what the runtime pays (get_childkey_take), a ratio 0..1.

Format: decimal number, as a string
childkey_take_is_flooredboolean

True when the stored take is below the subnet's floor.

alpha_stake_raostring · unit alpha_rao (÷1e9) · can be null

TotalHotkeyAlpha on the subnet, alpha rao.

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

TotalHotkeyAlpha on root (netuid 0): TAO 1:1, rao.

Format: whole number, as a string · on chain: u64
hotkeystring

The child's or parent's hotkey, SS58.

Format: SS58 address
proportion_ratiostring · unit ratio · can be null

The edge's proportion / u64::MAX, a ratio 0..1.

Format: decimal number, as a string
parentsarray of objects

ParentKeys(hotkey, netuid), in the chain's order.

9 fields in parents (each item)
coldkeystring · can be null

Its Owner coldkey, SS58. Null without an Owner entry.

Format: SS58 address
take_ratiostring · unit ratio · can be null

Delegates (the validator take) / 65535, a ratio 0..1. Null when not a delegate.

Format: decimal number, as a string
childkey_take_ratiostring · unit ratio · can be null

ChildkeyTake(hotkey, netuid) / 65535 as stored (0 when unset), a ratio 0..1.

Format: decimal number, as a string
childkey_take_effective_ratiostring · unit ratio · can be null

max(stored, the subnet's floor) / 65535: what the runtime pays (get_childkey_take), a ratio 0..1.

Format: decimal number, as a string
childkey_take_is_flooredboolean

True when the stored take is below the subnet's floor.

alpha_stake_raostring · unit alpha_rao (÷1e9) · can be null

TotalHotkeyAlpha on the subnet, alpha rao.

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

TotalHotkeyAlpha on root (netuid 0): TAO 1:1, rao.

Format: whole number, as a string · on chain: u64
hotkeystring

The child's or parent's hotkey, SS58.

Format: SS58 address
proportion_ratiostring · unit ratio · can be null

The edge's proportion / u64::MAX, a ratio 0..1.

Format: decimal number, as a string

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.