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

API reference / Hotkeys

A hotkey's current commitment pointers on every subnet

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

One row per typed pointer in the hotkey's current commitment on each subnet, by netuid, then ordinal, keyset-paged through meta.page.next_cursor. Typed pointers decoded from hotkeys' current on-chain commitments (Commitments.set_commitment): Hugging Face models and datasets, GitHub repositories and gists, URLs, IPFS content ids, buckets, commit ids, content hashes, JSON, opaque text, timelocked fields (never decrypted). Nothing a pointer names is fetched. Rendering: value is untrusted text written on chain by the hotkey: render it escaped, as plain text. Only display link may be clickable, and link carries the URL exactly then; a URL not assessed yet has no link until it passes, and a pointer whose URL is assessed malicious is not served. Cached 5 minutes (slow class). Errors are application/problem+json: INVALID_ADDRESS, INVALID_LIMIT, INVALID_CURSOR, UNKNOWN_PARAMETER, SOURCE_TIMEOUT (503), SERVICE_UNAVAILABLE (503), SOURCE_NOT_READY (503: commitments are not served on this deployment yet).

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. Anything else: 400 INVALID_ADDRESS.

Query parameters

limitquery· integer · default 200 · 1 to 500

Pointers per page, 1..500 (default 200). Anything else is a 400 INVALID_LIMIT.

cursorquery· string · up to 200 characters

meta.page.next_cursor of the previous page, sent back with the same other parameters (a cursor is bound to them; altered or foreign: 400 INVALID_CURSOR).

Response

data is a list of objects 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 pointers in the hotkey's current commitment on each subnet, by netuid, then ordinal.

netuidinteger · unit id

Subnet slot the commitment is on.

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 life the commitment was set in (a value set before a re-registration belongs to the earlier life, until the hotkey commits again). Null when the source states none.

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.

hotkeystring

The committing hotkey, SS58 (prefix 42).

ordinalinteger · unit id

The pointer's position in the hotkey's current commitment (0-based). A gap means a pointer whose URL is assessed malicious: it is not served.

field_indexinteger · unit id

The commitment field the pointer came from (0-based).

pointer_kindstring

What the pointer is: hf_model / hf_dataset (a Hugging Face model or dataset id), github_repo, gist, url (any other http(s) URL), ipfs_cid, r2_or_s3_bucket (an object-storage bucket), commit_sha (40 hex), content_hash, json (a JSON object with no recognised pointer), opaque (text or bytes with no recognised pointer), timelocked (a timelock-encrypted field, never decrypted: value null). New values may be added; show an unknown value as is (or generically).

valuestring · can be null

The pointer, normalised (owner/name[@revision] for Hugging Face, the repository URL[@revision], the canonical URL, alg:hex or hex for a hash, the text for opaque / json), at most 300 characters, e-mail addresses redacted. Untrusted text written on chain by the hotkey: render it escaped, as plain text, never as a link or markup (only link may be clickable). Null only for timelocked.

revisionstring · can be null

The revision, branch or commit a Hugging Face or GitHub pointer names; null otherwise.

basisstring

How the pointer was read: generic (a whole field or an unambiguous token), json (a value in a JSON object), subnet_format (the subnet's documented commitment format), chain_hash (a hash field of the commitment itself), chain_timelock (a timelocked field). New values may be added; show an unknown value as is (or generically).

canonical_urlstring · can be null

http(s) pointers: the normalised URL (the key POST /links/verdicts assesses); null for other kinds. Plain text: it may be rendered clickable only when display is link (then link carries it).

verdictstring · can be null

http(s) pointers: the URL's safety assessment, safe, suspicious or unknown (not assessed yet); null for other kinds. New values may be added; show an unknown value as is (or generically).

displaystring

How to render the pointer: link (an http(s) pointer assessed safe: the only value that may be clickable), text (any other kind, or a URL not assessed yet), text_warning (assessed suspicious: text with a warning). New values may be added; show an unknown value as is (or generically).

target_statusstring · can be null

Hugging Face pointers: ok, not_found, moved or unlisted, from tracked model and dataset metadata (nothing is fetched for this list); null when the repository is not tracked, or another kind. New values may be added; show an unknown value as is (or generically).

set_heightinteger · unit block

The block of the commitment's last change.

set_atstring (date-time) · can be null

That block's time, RFC 3339 UTC; null when not known.

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

When this pointer was first decoded, RFC 3339 UTC.

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

The last complete read of the subnet's commitments, RFC 3339 UTC.

Format: date and time, ISO 8601 in UTC

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.