Chart marks of a subnet
https://api.bittensor.ai/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 400INVALID_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 reachmin_pool_ratioof 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
namesadds the top-levelincluded.names: every distinct account on the page (accounts indataat 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 400INVALID_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-upgradekind asked for).6 fields in events (each item)
- kindstring
runtime-upgrade(System.CodeUpdated),subnet-registration(SubtensorModule.NetworkAdded),subnet-deregistration(NetworkRemoved),subnet-owner-change(SubnetOwnerHotkeySet) oridentity-change(SubnetIdentitySet). On a subnet chart the event'snetuidargument is the chart's. New values may be added; show an unknown value as is (or generically).- idstring · unit id
height-indexof 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_indexof 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,sellorswap(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
- 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-indexof 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, orremove(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
- 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), 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).- 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-revalidateandstale-if-error;no-storewithX-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, withX-BTAI-Stale-As-Of,Age(its seconds since then) andWarning: 110 - "Response is Stale", andCache-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.
- AMBIGUOUS_CREDENTIALS
- BAD_GATEWAY
- BILLING_UNAVAILABLE
- BUDGET_EXCEEDED
- CONCURRENCY_LIMIT
- INSUFFICIENT_PERMISSIONS
- INTERNAL_ERROR
- INVALID_AMOUNT
- INVALID_INCLUDE
- INVALID_KIND
- INVALID_LIMIT
- INVALID_NETUID
- INVALID_RANGE
- INVALID_RATIO
- INVALID_TIME
- INVALID_WINDOW
- NOT_READY
- PAYMENT_REQUIRED
- PLAN_REQUIRED
- RATE_LIMITED
- REPEATED_PARAMETER
- SERVICE_UNAVAILABLE
- SOURCE_BUSY
- SOURCE_NOT_READY
- SOURCE_TIMEOUT
- UNAUTHORIZED
- UNKNOWN_PARAMETER
- VALIDATION_ERROR
From the API's published specification, version 1.165.0.