A hotkey's childkey family on one subnet
https://api.bittensor.ai/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), 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_NETUID
- PAYMENT_REQUIRED
- PLAN_REQUIRED
- 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.