Set a validator's basket target
https://api.bittensor.ai/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_ADDRESSotherwise).
Request body
A JSON object with these fields:
- mixarray of objects
The target: 1 to 128 entries, each netuid at most once, each
bpsat least 10, summing to exactly 10000 (400INVALID_MIX); every netuid but 0 a live subnet now (400NETUID_NOT_LIVE). Any order: the message lists them in ascending netuid (400MIX_MISMATCHwhen 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'smix), ornoneto clear;nonce:+ 32 random lower-case hex characters, never reused for this hotkey;issued_at:andexpires_at:, RFC 3339 UTC in whole seconds withZ,expires_atafterissued_atand at most 15 minutes after it. A malformed message is a 400INVALID_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
signRawwith typebytesreturns it: the signed payload is the message wrapped in<Bytes>and</Bytes>. A signature of the unwrapped message is a 400UNWRAPPED_SIGNATURE; any other is a 400BAD_SIGNATURE. With a signature the message must be current: from 60 seconds beforeissued_attoexpires_at(400EXPIRED). Send this orremark_extrinsic, not both (400INVALID_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 dispatchedSystem.remark_with_eventwith the remarkbittensor.ai basket target v1 sha256:followed by the lower-case hex SHA-256 of the message's UTF-8 bytes. The extrinsic must carry aSystem.Remarkedevent whosehashis the BLAKE2b-256 of those remark bytes and whosesenderis the coldkey line (400REMARK_MISMATCH), the coldkey must have owned the hotkey at that block (403NOT_HOTKEY_OWNER), and the block must be finalized (400REMARK_NOT_FOUNDuntil it is) and at most 24 hours old (400REMARK_TOO_OLD).expires_atis not checked on this path, butissued_atmay not be in the future (400EXPIRED). A malformed value is a 400INVALID_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 onGET /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_heightfor 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
generationnames (GET /subnets/generations'start_height): use it, nevergeneration, for heights, ages and dates. Null exactly whengenerationis null (root without a life, no subnet), or transiently when this API cannot read the lives. Root'sgeneration0 starts at 0.- is_current_lifeboolean · can be null
Whether
generationis the slot's current life (true) or an ended one, re-registered since (false). Null exactly whengenerationis null, or transiently when this API cannot read the lives. Root'sgeneration0 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) orremark(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) orclear(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_heightfor 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
generationnames (GET /subnets/generations'start_height): use it, nevergeneration, for heights, ages and dates. Null exactly whengenerationis null (root without a life, no subnet), or transiently when this API cannot read the lives. Root'sgeneration0 starts at 0.- is_current_lifeboolean · can be null
Whether
generationis the slot's current life (true) or an ended one, re-registered since (false). Null exactly whengenerationis null, or transiently when this API cannot read the lives. Root'sgeneration0 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) orremark(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), 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).- 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.
- AMBIGUOUS_CREDENTIALS
- BAD_GATEWAY
- BAD_SIGNATURE
- BILLING_UNAVAILABLE
- BUDGET_EXCEEDED
- CONCURRENCY_LIMIT
- HOTKEY_MISMATCH
- INSUFFICIENT_PERMISSIONS
- INTERNAL_ERROR
- INVALID_ADDRESS
- INVALID_ID
- INVALID_MIX
- INVALID_PARAMETER
- INVALID_PROOF
- INVALID_TARGET_MESSAGE
- MIX_MISMATCH
- NETUID_NOT_LIVE
- NONCE_REUSED
- NOT_HOTKEY_OWNER
- PAYMENT_REQUIRED
- PLAN_REQUIRED
- RATE_LIMITED
- REMARK_MISMATCH
- REMARK_NOT_FOUND
- REMARK_TOO_OLD
- SERVICE_UNAVAILABLE
- SOURCE_BUSY
- SOURCE_NOT_READY
- SOURCE_TIMEOUT
- STALE_ISSUED_AT
- UNAUTHORIZED
- UNKNOWN_PARAMETER
- UNWRAPPED_SIGNATURE
- VALIDATION_ERROR
- WRONG_CHAIN
From the API's published specification, version 1.165.0.