Skip to content
TAO$188.21
BTC0.002927
MCap$2.22B
Vol$86.25M

API reference / Basket funds

Set a validator's basket target

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

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).

Full description

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}). Sets the target, replacing the current one (the earlier one stays in the history). Proof: the body carries the exact message and either the owner coldkey's signature of it or the remark_extrinsic in which the owner coldkey committed to it on chain (for multisig and proxied coldkeys). The message's coldkey line must own the hotkey now (403 NOT_HOTKEY_OWNER), its chain line must be the Bittensor mainnet genesis hash (400 WRONG_CHAIN) and its hotkey line the hotkey in the path (400 HOTKEY_MISMATCH). Each message is accepted once: its nonce must be new for the hotkey (400 NONCE_REUSED) and its issued_at later than the hotkey's newest accepted write (400 STALE_ISSUED_AT). Nothing is stored when any check fails. No sign-in is needed: the proof is the authority. Limits: 30 writes per hour from one IP address (every attempt counts) and 12 per hotkey (counted once the proof is valid); past either, 429 RATE_LIMITED with Retry-After. The answer is never cached (no-store). Each subnet's current generation is recorded with the target, so a later read can tell when a netuid has become another subnet. Answers the new target as GET does. Errors are application/problem+json: INVALID_ADDRESS, INVALID_PROOF, INVALID_TARGET_MESSAGE, WRONG_CHAIN, HOTKEY_MISMATCH, MIX_MISMATCH, EXPIRED, BAD_SIGNATURE, UNWRAPPED_SIGNATURE, INVALID_ID, REMARK_NOT_FOUND, REMARK_MISMATCH, REMARK_TOO_OLD, NONCE_REUSED, STALE_ISSUED_AT (400), NOT_HOTKEY_OWNER (403), RATE_LIMITED (429), UNKNOWN_PARAMETER, SOURCE_TIMEOUT (503), SOURCE_NOT_READY (503), INVALID_MIX, NETUID_NOT_LIVE (400).

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).

Request body

A JSON object with these fields:

mixarray of objects

The target: 1 to 128 entries, each netuid at most once, each bps at least 10, summing to exactly 10000 (400 INVALID_MIX); every netuid but 0 a live subnet now (400 NETUID_NOT_LIVE). Any order: the message lists them in ascending netuid (400 MIX_MISMATCH when its mix line differs).

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

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

bpsinteger · unit bps (÷10000)

Its share in basis points: at least 10; the entries sum to exactly 10000.

messagestring

The exact text the owner coldkey signed (or committed to with a remark): UTF-8, eight lines joined by \n, no trailing newline, in this order: bittensor.ai basket target v1; chain: + the Bittensor mainnet genesis hash (0x2f0555cc76fc2840a25a6ea3b9637146806f1f44b090c175ffde2a7e5ab36c03); hotkey: + the hotkey in the path, SS58; coldkey: + the hotkey's owner coldkey, SS58; mix: + the entries as <netuid>=<bps> joined by commas in ascending netuid (exactly the body's mix), or none to clear; nonce: + 32 random lower-case hex characters, never reused for this hotkey; issued_at: and expires_at: , RFC 3339 UTC in whole seconds with Z, expires_at after issued_at and at most 15 minutes after it. A malformed message is a 400 INVALID_TARGET_MESSAGE.

Pattern: ^bittensor\.ai basket target v1\nchain: 0x[0-9a-f]{64}\nhotkey: [1-9A-HJ-NP-Za-km-z]{46,48}\ncoldkey: [1-9A-HJ-NP-Za-km-z]{46,48}\nmix: (none|[0-9]{1,5}=[0-9]{2,5}(,[0-9]{1,5}=[0-9]{2,5}){0,127})\nnonce: [0-9a-f]{32}\nissued_at: [0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z\nexpires_at: [0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$
signaturestring · can be null

The owner coldkey's signature of the message (0x + 128 hex, sr25519 or ed25519), as a wallet extension's signRaw with type bytes returns it: the signed payload is the message wrapped in <Bytes> and </Bytes>. A signature of the unwrapped message is a 400 UNWRAPPED_SIGNATURE; any other is a 400 BAD_SIGNATURE. With a signature the message must be current: from 60 seconds before issued_at to expires_at (400 EXPIRED). Send this or remark_extrinsic, not both (400 INVALID_PROOF).

Pattern: ^0x[0-9a-fA-F]{128}$
remark_extrinsicstring · can be null

For an owner coldkey that cannot sign messages (a multisig or a proxied account): the extrinsic, as {height}-{index} or its 0x hash, in which the owner coldkey dispatched System.remark_with_event with the remark bittensor.ai basket target v1 sha256: followed by the lower-case hex SHA-256 of the message's UTF-8 bytes. The extrinsic must carry a System.Remarked event whose hash is the BLAKE2b-256 of those remark bytes and whose sender is the coldkey line (400 REMARK_MISMATCH), the coldkey must have owned the hotkey at that block (403 NOT_HOTKEY_OWNER), and the block must be finalized (400 REMARK_NOT_FOUND until it is) and at most 24 hours old (400 REMARK_TOO_OLD). expires_at is not checked on this path, but issued_at may not be in the future (400 EXPIRED). A malformed value is a 400 INVALID_ID.

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

6 headers: Cache-Control, RateLimit-Policy, RateLimit, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
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).

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 · 400 · 401 · 402 · 403 · 404 · 429 · 500 · 502 · 503

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.