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

API reference / Subnets

Chart marks of a subnet

GET/api/v2/subnets/{netuid}/marks
Status
Stable
Auth
API key or OAuth access token
Scope
data:read
Rate limit
plan

Everything a subnet's price chart marks in one window, in one call.

Full description

Everything a subnet's price chart marks in one window, in one call: the subnet's registration (subnet-registration), owner hotkey changes (subnet-owner-change) and identity changes (identity-change), each scoped by the event's netuid argument; its whale trades (whale-trade: buys, sells and swaps whose TAO is at least max(min_tao_rao, min_pool_ratio x the pool's TAO reserve)); and its large liquidity changes (liquidity-event, the same threshold). data.events, data.trades and data.liquidity, each oldest first; accounts SS58. One life: the marks start at the first block of the subnet life live at the window's end (meta.life_start_height; its own registration mark kept), never the previous life's. Each kind holds at most limit_per_kind rows, the oldest of the window, with meta.truncated.<kind> true when there were more (never a silent cut); meta.kind_coverage.<kind> says which heights each kind's source covers. The window [from_time, to_time) must sit on the grain: whole minutes for a window of up to 1 day, whole hours above, at most 400 days (a fixed URL set that caches across charts); otherwise a 400 INVALID_WINDOW naming from_time / to_time. Caching: a window that ended before the indexed head (meta.settled), at a finalized block, whose every kind's coverage spans the window's blocks is cached as settled (an hour, a day stale-while-revalidate); any other window, and every answer with include=names, follows the head. Errors are application/problem+json: INVALID_WINDOW, INVALID_TIME, INVALID_RANGE, INVALID_KIND, INVALID_AMOUNT, INVALID_RATIO, INVALID_LIMIT, INVALID_INCLUDE, UNKNOWN_PARAMETER, NOT_READY (503), SOURCE_TIMEOUT (503), SOURCE_NOT_READY (503).

Path parameters

netuidpath, required· integer · 0 to 65535

Subnet slot (0 = root).

Query parameters

from_timequery, required· string (date-time)

The window's start, inclusive (RFC 3339), on the grain.

Format: date and time, ISO 8601 in UTC
to_timequery, required· string (date-time)

The window's end, exclusive (RFC 3339), on the grain; after from_time, at most 400 days later.

Format: date and time, ISO 8601 in UTC
kindsquery· string

A comma list (or the parameter repeated) of subnet-registration, subnet-owner-change, identity-change, whale-trade, liquidity-event. Default: all of them. Anything else is a 400 INVALID_KIND.

min_tao_raoquery· string

Whale trades and liquidity changes: the minimum TAO moved, rao (a decimal integer). Default 50 TAO (50000000000). A row must also reach min_pool_ratio of the pool's TAO reserve.

min_pool_ratioquery· string

Whale trades and liquidity changes: the minimum TAO moved as a fraction of the pool's TAO reserve, 0..1. Default 0.01 (1 %).

limit_per_kindquery· integer · 1 to 1000

Rows per kind, 1..1000 (default 1000): the oldest of the window. A very small value can be slow on a long window (a known data-source plan issue; the default is fast).

includequery· string

names adds the top-level included.names: every distinct account on the page (accounts in data at any depth, event args included) keyed by its SS58 address, each {identity: {name} | null, label: {text, source, confidence, verified, inferred, as_of} | null}; the on-chain identity and the off-chain label are kept apart, and a label is never a chain fact. A missing key means 'not looked up', null means 'none'. At most 500 accounts (included.names_truncated). Still one call (the data source sideloads them in the same statement); an answer with names is cached as a head answer (names follow the head). 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 marks, by source.

eventsarray of objects

Chain events (every *-registration / *-change / runtime-upgrade kind asked for).

6 fields in events (each item)
kindstring

runtime-upgrade (System.CodeUpdated), subnet-registration (SubtensorModule.NetworkAdded), subnet-deregistration (NetworkRemoved), subnet-owner-change (SubnetOwnerHotkeySet) or identity-change (SubnetIdentitySet). On a subnet chart the event's netuid argument is the chart's. New values may be added; show an unknown value as is (or generically).

idstring · unit id

height-index of the event (unique, stable).

Format: block and index, such as 4200000-3
heightinteger · unit block

The block of the event.

timestring (date-time) · can be null

The block's time (RFC 3339 UTC, milliseconds). Null only for block 0.

Format: date and time, ISO 8601 in UTC
eventobject

The event's pallet and name.

2 fields in event
palletstring

The pallet, as in the runtime metadata (e.g. SubtensorModule).

namestring

The event, as in the runtime metadata (PascalCase, e.g. StakeAdded).

argsobject · can be null

The event's arguments, named and rendered as on /events (accounts SS58). Null: none.

tradesarray of objects

Whale trades (whale-trade; always [] on the TAO chart).

12 fields in trades (each item)
kindstring

Always whale-trade. New values may be added; show an unknown value as is (or generically).

idstring · unit id

height-event_index of the trade's event.

Format: block and index, such as 4200000-3
heightinteger · unit block

The block of the trade.

timestring (date-time) · can be null

The block's time (RFC 3339 UTC, milliseconds). Null only for block 0.

Format: date and time, ISO 8601 in UTC
sidestring

buy, sell or swap (as on /trades). New values may be added; show an unknown value as is (or generically).

netuidinteger · unit id

The subnet (the chart's).

tao_raostring · unit rao (÷1e9)

The TAO the trade moved, rao: at least max(meta.thresholds.min_tao_rao, ratio x reserve).

Format: whole number, as a string · on chain: u64
alpha_raostring · unit alpha_rao (÷1e9)

The alpha the trade moved, alpha rao.

Format: whole number, as a string · on chain: u64
tao_reserve_raostring · unit rao (÷1e9) · can be null

The pool's TAO reserve after that block, rao. Null when unknown (the ratio is then null).

Format: whole number, as a string · on chain: u64
pool_share_ratiostring · unit ratio · 6 decimals · can be null

tao_rao / tao_reserve_rao, a fraction with 6 decimals. Null without a reserve.

Format: decimal number, as a string
coldkeystring · can be null

The coldkey whose stake moved, SS58. Null when unknown.

Format: SS58 address
signerstring · can be null

The extrinsic's signer, SS58. Null for a trade without one.

Format: SS58 address
liquidityarray of objects

Liquidity changes (liquidity-event; always [] on the TAO chart).

13 fields in liquidity (each item)
kindstring

Always liquidity-event. New values may be added; show an unknown value as is (or generically).

idstring · unit id

height-index of the event (unique, stable).

Format: block and index, such as 4200000-3
heightinteger · unit block

The block of the event.

timestring (date-time) · can be null

The block's time (RFC 3339 UTC, milliseconds). Null only for block 0.

Format: date and time, ISO 8601 in UTC
variantstring

add, or remove (LiquidityRemoved, or a LiquidityModified with a negative TAO change). New values may be added; show an unknown value as is (or generically).

eventobject

The Swap event.

2 fields in event
palletstring

The pallet, as in the runtime metadata (e.g. SubtensorModule).

namestring

The event, as in the runtime metadata (PascalCase, e.g. StakeAdded).

netuidinteger · unit id

The subnet (the chart's).

tao_raostring · unit rao (÷1e9)

The TAO the change moved (absolute), rao.

Format: whole number, as a string · on chain: u64
alpha_raostring · unit alpha_rao (÷1e9)

The alpha the change moved (absolute), alpha rao.

Format: whole number, as a string · on chain: u64
tao_reserve_raostring · unit rao (÷1e9) · can be null

The pool's TAO at or before that block, rao. Null when unknown.

Format: whole number, as a string · on chain: u64
pool_share_ratiostring · unit ratio · 6 decimals · can be null

tao_rao / tao_reserve_rao, a fraction with 6 decimals. Null without a reserve.

Format: decimal number, as a string
coldkeystring · can be null

The liquidity provider's coldkey, SS58. Null when the event names none.

Format: SS58 address
position_idstring · can be null

The Swap position id, as the event states it. Null: none.

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.