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

API reference / Basket funds

A validator's basket target

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

A validator's target allocation for its basket fund: how it says it intends to split the fund across subnets (netuid 0 is the share kept as TAO). It is published by the hotkey's owner coldkey and stored by bittensor.ai: the validator's stated intent, never what the chain holds (the fund's holdings are on GET /baskets/{hotkey}). Each entry says whether the subnet at its netuid is still the one the target was set for (stale_generation) and whether its share is above the chain's basket concentration cap (above_concentration_cap); owner_changed says the hotkey has a different owner now, and owner_swap_pending that its owner has a pending coldkey swap. A flag is null when it cannot be read right now. proof lets anyone verify the target independently. include=history adds the earlier accepted writes, newest first (at most 20). Cached as the head: the next request after a successful write gets the new target (a client or shared cache may keep the previous answer for its max-age). Errors are application/problem+json: INVALID_ADDRESS, INVALID_INCLUDE, UNKNOWN_PARAMETER, TARGET_NOT_FOUND (404: the hotkey has no target).

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 validator's hotkey: SS58, or 0x + 64 hex (400 INVALID_ADDRESS otherwise).

Query parameters

includequery· string

history adds data.history, the earlier accepted writes. Anything else is a 400 INVALID_INCLUDE.

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 target and its flags.

hotkeystring

The validator's hotkey, SS58.

Format: SS58 address
statusstring

Always target: this is what the validator says it aims for, published by its owner coldkey; the fund's actual holdings are on GET /baskets/{hotkey}. New values may be added; show an unknown value as is (or generically).

mixarray of objects

The target's entries, in ascending netuid.

7 fields in mix (each item)
netuidinteger · unit id

The subnet; 0 is the TAO slot (the share kept as TAO on root).

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. The subnet's life when the target was set: netuid is a reused slot. 0 for netuid 0. Null when it was not known then.

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.

bpsinteger · unit bps (÷10000)

The target share in basis points (the entries sum to 10000).

stale_generationboolean · can be null

True when the subnet at this netuid is no longer the one the target was set for (it was dissolved, or replaced by a new subnet): the entry no longer means what the validator stated. False for netuid 0. Null when it cannot be told right now.

above_concentration_capboolean · can be null

True when the share is above the chain's basket concentration cap (SubtensorModule.BasketConcentrationCap, the most of a fund's value one holding may reach through a basket buy): the fund cannot buy up to it. Null for netuid 0 (the TAO slot is never bought) and when the cap cannot be read right now.

set_atstring (date-time)

When the target was accepted, RFC 3339 UTC.

Format: date and time, ISO 8601 in UTC
issued_atstring (date-time)

The message's issued_at, RFC 3339 UTC.

Format: date and time, ISO 8601 in UTC
set_by_coldkeystring

The coldkey that proved the target: the hotkey's owner then, SS58.

Format: SS58 address
proofobject

The message and its signature or remark, to verify it yourself.

4 fields in proof
kindstring

signature (the owner coldkey signed the message) or remark (the owner coldkey dispatched an on-chain remark committing to it). New values may be added; show an unknown value as is (or generically).

messagestring

The exact message that was proven, as sent.

signaturestring · can be null

The signature of the <Bytes>-wrapped message, 0x hex (lower case). Null for a remark.

remark_extrinsicstring · unit id · can be null

The remark's extrinsic, {height}-{index}. Null for a signature.

Format: block and index, such as 4200000-3
owner_changedboolean · can be null

True when the hotkey's owner now is not set_by_coldkey (a coldkey or hotkey swap since): the target was set by a previous owner. Null when the owner cannot be read right now.

owner_swap_pendingboolean · can be null

True when the hotkey's current owner coldkey has a pending coldkey swap (see GET /coldkey-swaps/pending): control may move to another key soon. Null when it cannot be read right now.

historyarray of objects · optional

Only with include=history (absent otherwise): the earlier accepted writes, newest first, at most 20.

6 fields in history (each item)
actionstring

set (a target, later replaced) or clear (the owner removed the target). New values may be added; show an unknown value as is (or generically).

mixarray of objects

The target's entries; empty for a clear.

5 fields in mix (each item)
netuidinteger · unit id

The subnet; 0 is the TAO slot.

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. The subnet's life when that target was set; null when it was not known then.

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.

bpsinteger · unit bps (÷10000)

The share in basis points.

set_atstring (date-time)

When it was accepted, RFC 3339 UTC.

Format: date and time, ISO 8601 in UTC
issued_atstring (date-time)

The message's issued_at, RFC 3339 UTC.

Format: date and time, ISO 8601 in UTC
set_by_coldkeystring

The owner coldkey that proved it, SS58.

Format: SS58 address
proofobject

The message and its signature or remark.

4 fields in proof
kindstring

signature (the owner coldkey signed the message) or remark (the owner coldkey dispatched an on-chain remark committing to it). New values may be added; show an unknown value as is (or generically).

messagestring

The exact message that was proven, as sent.

signaturestring · can be null

The signature of the <Bytes>-wrapped message, 0x hex (lower case). Null for a remark.

remark_extrinsicstring · unit id · can be null

The remark's extrinsic, {height}-{index}. Null for a signature.

Format: block and index, such as 4200000-3

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.