A hotkey's stakers per pool and its largest wallets
https://api.bittensor.ai/api/v2/hotkeys/{hotkey}/staker-summary- Status
- Beta
- Auth
- API key or OAuth access token
- Scope
data:read- Rate limit
plan
A validator's stakers summary in one call. Per pool at as_of_day's end, largest first: the staker count with its 7- and 30-day change (null while those days are not available yet), the stakers' alpha, the largest coldkey's and the 10 largest coldkeys' share of it, the Owner coldkey's share (at meta.at) and the coldkeys with a live share key now; plus wallets_total and the largest wallets (coldkey, identity_name, is_owner, total_tao_rao at each subnet's closing price, netuids). Its per-staker rows are /api/v2/hotkeys/{hotkey}/stakers. wallets (0..100, default 50) caps the wallet list; netuids narrows the pools. The day counts change once a day and the head members slowly: cached 300 s. Errors are application/problem+json: INVALID_ADDRESS, INVALID_NETUID, UNKNOWN_PARAMETER, NOT_READY (503, the staker figures are not available yet), 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
- netuidsquery· string
Only these pools. A comma list (or the parameter repeated) of subnets, each 0..65535, as many as needed; duplicates are ignored. Anything else is a 400
INVALID_NETUID.- walletsquery· integer · 0 to 100
How many of the largest wallets, 0..100. Default: 50.
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, its pools and its largest wallets.
- 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
- owner_coldkeystring · can be null
The hotkey's Owner coldkey, SS58. Null without an Owner entry.
- Format: SS58 address
- as_of_daystring (date) · can be null
The day the pools and wallets are counted at. Null before any is available.
- Format: date, YYYY-MM-DD
- wallets_totalinteger · unit count
Coldkeys holding alpha above 0 on the hotkey (any pool).
- poolsarray of objects
Its pools at
as_of_day, largest first;[]when none.9 fields in pools (each item)
- netuidinteger · unit id
The subnet slot.
- staker_countinteger · unit count
Coldkeys holding alpha above 0 in the pool at the day's end.
- staker_count_change_7dinteger · unit count · can be null
staker_countminus its value 7 days earlier. Null while that day isn't available.- can be negative
- staker_count_change_30dinteger · unit count · can be null
staker_countminus its value 30 days earlier. Null while that day isn't available.- can be negative
- alpha_raostring · unit alpha_rao (÷1e9)
The stakers' alpha in the pool at the day's end, alpha rao.
- Format: whole number, as a string · on chain: u64
- nominators_liveinteger · unit count · can be null
Coldkeys with a live share key in the pool now (positions whose alpha rounds to 0 included).
- walletsarray of objects
The largest wallets by
total_tao_rao, at mostwalletsof them (at most 100 are kept).5 fields in wallets (each item)
- coldkeystring
The coldkey, SS58.
- Format: SS58 address
- identity_namestring · can be null
Its on-chain identity name. Null without one.
- is_ownerboolean
True for the hotkey's Owner coldkey.
- total_tao_raostring · unit rao (÷1e9)
Its positions on the hotkey at
as_of_day's end, each at its subnet's closing price, summed, rao of TAO.- Format: whole number, as a string · on chain: u64
- netuidsarray of values
The subnets it holds a position on through the hotkey.
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
- INVALID_PARAMETER
- NOT_READY
- 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.