Skip to content
TAO$188.27
BTC0.002928
MCap$2.22B
Vol$86.25M

API reference / Trades

Trades across subnets

GET/api/v2/trades
Status
Stable
Auth
API key or OAuth access token
Scope
data:read
Rate limit
plan

Pool trades, newest first.

Full description

Pool trades, newest first (order=desc, the default) or oldest first (order=asc): buys, sells, swaps between subnets (one row carrying both pools), basket claims and rebalancing, registrations, and the alpha sold (or bought back) to pay a transaction fee charged in alpha (fee: classified up to meta.coverage.fee_classified_to_height, which trails the head; above it such a swap still reads as a sell until it is classified). Each row has the block, event and extrinsic, the amounts gross of the fee, the execution price and the pool's price and TAO reserve after the block (prices with 12 decimals), each pool leg's swap fee (swap_fees: sell before buy, in alpha for a sell leg and TAO for a buy leg; an amount still being sized is null and keeps the page from being cached as settled), the TAO amount in USD at the trade's own minute (value_usd), and the coldkey, hotkey and signer. side filters (a comma list; omitted or all = every side); from_time / to_time bound the time (half-open), from_height / to_height the block height (both inclusive); given together, a trade must match both. Pages continue in order through meta.page.next_cursor, which is null on the last page. Exact inside meta.coverage: older trades are not served yet. Across subnets: every subnet's trades in one feed (the whale tape), or those of the netuids set (a row matches by its netuid or its counterpart_netuid); min_tao_rao keeps trades of at least that size. Same order, keyset and coverage as the per-subnet feed: (height, event_index, netuid). Errors are application/problem+json: INVALID_NETUID, INVALID_AMOUNT, INVALID_SIDE, INVALID_ORDER, INVALID_TIME, INVALID_HEIGHT, INVALID_RANGE (from_time not before to_time, or from_height above to_height), INVALID_LIMIT, INVALID_CURSOR, UNKNOWN_PARAMETER, NOT_READY (503, the trade history has no coverage yet), SOURCE_TIMEOUT (503), SOURCE_NOT_READY (503).

Query parameters

netuidsquery· string

Only trades on these subnets: a row matches by its netuid or its counterpart_netuid (a swap on either side). A comma list (or the parameter repeated) of subnets, each 0..65535, as many as needed; duplicates are ignored. Anything else is a 400 INVALID_NETUID. Omitted: every subnet.

min_tao_raoquery· string

Only rows that moved at least this much TAO (tao_rao), in rao: a decimal integer, e.g. 100000000000 for 100 TAO. Rows without a TAO amount (tao_rao null) never match. Anything else is a 400 INVALID_AMOUNT.

sidequery· string

all (the default: every side, fee included) or a comma list of buy, sell, swap, basket_claim, basket_swap, registration, fee, other (OR; buy,sell,swap leaves the fee rows out). fee rows exist only up to meta.coverage.fee_classified_to_height: above it a fee paid in alpha is still a sell. Anything else is a 400 INVALID_SIDE.

from_timequery· string (date-time)

Only trades at or after this time (RFC 3339).

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

Only trades before this time (RFC 3339).

Format: date and time, ISO 8601 in UTC
from_heightquery· integer · 0 to 2147483647

Only trades at or above this block height (inclusive). Not an integer 0..2147483647: a 400 INVALID_HEIGHT; above to_height: a 400 INVALID_RANGE.

to_heightquery· integer · 0 to 2147483647

Only trades at or below this block height (inclusive). Not an integer 0..2147483647: a 400 INVALID_HEIGHT.

orderquery· enum · one of desc, asc · default desc

desc (newest first, the default) or asc (oldest first), on (height, event_index, netuid).

limitquery· integer · default 50 · 1 to 1000

Page size, 1..1000 (default 50).

cursorquery· string · up to 200 characters

meta.page.next_cursor of the previous page, passed back unchanged with the same other parameters. It is opaque and bound to them: a cursor used with different parameters, or altered, is a 400 INVALID_CURSOR.

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

Trades in order by (height, event_index, netuid), newest first by default; [] when there are none.

heightinteger · unit block

Block of the trade.

event_indexinteger · unit id

Index of the trade's event in the block; never null. (height, event_index) identifies the row, with netuid for a basket claim that credits several subnets in one event.

extrinsic_indexinteger · unit id · can be null

Index of the extrinsic in the block; null for a trade made by a block hook.

timestring (date-time)

Timestamp of the block, RFC 3339 UTC with milliseconds.

Format: date and time, ISO 8601 in UTC
sidestring

buy (TAO into the pool, alpha out), sell (alpha in, TAO out), swap (alpha of netuid into alpha of counterpart_netuid, one row for both pools), basket_claim, basket_swap (basket rebalancing), registration, fee (alpha the transaction-fee extension sold, or bought back, to pay a fee charged in alpha, before or after the call's dispatch) or other. A fee row needs the call-path trace: it is classified only up to meta.coverage.fee_classified_to_height (~1.8 days behind the head on 2026-10-01). Above that height a fee paid in alpha still reads as a sell, and it becomes a fee row once the trace reaches it, so rows above it can still change side. Clients must accept values not documented yet.

netuidinteger · unit id

The pool: buy/sell/registration, the subnet traded; swap, the origin (sold) subnet.

counterpart_netuidinteger · unit id · can be null

Swap: the destination (bought) subnet. Null on every other side.

parent_event_indexinteger · unit id · can be null

Set on the extra legs of a multi-leg operation (e.g. a hotkey transfer across several subnets): the event_index of the leg it belongs with; group by it to show one action. Null on single-leg rows.

tao_raostring · unit rao (÷1e9) · can be null

TAO into (buy) or out of (sell) the pool, in rao. On a swap, the TAO that passed between the two pools. Null when the trade moved no TAO (a basket claim credited in alpha).

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

Alpha of netuid out of (buy) or into (sell, swap) the pool, gross of the fee, in alpha rao. Null when not recorded for the side.

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

Swap: alpha of counterpart_netuid received, in alpha rao. Null on every other side.

Format: whole number, as a string · on chain: u64
execution_price_taostring · unit tao_per_alpha · 12 decimals · can be null

tao_rao / alpha_rao from the gross amounts (TAO per alpha), 12 decimals. Null when either is null or 0.

Format: decimal number, as a string · can be negative
pool_price_taostring · unit tao_per_alpha · 12 decimals · can be null

The pool's runtime price (TAO per alpha) after the block, 12 decimals. Null when unknown.

Format: decimal number, as a string · can be negative
counterpart_pool_price_taostring · unit tao_per_alpha · 12 decimals · can be null

Swap: the destination pool's runtime price after the block (TAO per alpha), 12 decimals. Null otherwise.

Format: decimal number, as a string · can be negative
tao_reserve_raostring · unit rao (÷1e9) · can be null

The pool's TAO reserve (SubnetTAO) after the block, in rao. Null when unknown.

Format: whole number, as a string · on chain: u64
swap_feesarray of objects

Each pool leg's swap fee, as its own StakeRemoved (sell leg) / StakeAdded (buy leg) event states it, sell before buy, zero fees kept: one entry on a buy or sell row, two on a swap (the sell leg on netuid, the buy leg on counterpart_netuid, also when they are equal), [] on every other side. A swap fee is not a transaction fee (that is the extrinsic's tx_fee). An entry's amount_rao can be null while the trade derivation is still sizing that row (filled in place, never 0): such a page is never cached as settled.

4 fields in swap_fees (each item)
legenum

The pool leg: sell (alpha into the pool, its StakeRemoved) or buy (TAO into the pool, its StakeAdded). A swap row has both, sell first.

One of: sell, buy
assetstring

What the fee was taken in, naming amount_rao's denomination: alpha of netuid (a sell leg) or tao (a buy leg). New values may be added; show an unknown value as is (or generically).

netuidinteger · unit id · can be null

The leg's subnet: the pool the leg traded against (on a swap, netuid for the sell leg and counterpart_netuid for the buy leg). Null when the source does not name it.

amount_raostring · unit rao (÷1e9) · can be null

The fee in the leg's asset's base unit (decimal string): rao when asset is tao, alpha rao of netuid when asset is alpha (a mixed-denomination field: x-unit keeps rao as the 1e9 scale and asset names the denomination; never add an alpha amount to TAO). 0 when the chain charged none. Null = not yet sized (the row's fee isn't available yet; filled in place, never 0): a page holding one is not final.

Format: whole number, as a string · on chain: u64
value_usdstring · unit usd · 2 decimals · can be null

tao_rao in USD at the latest TAO/USD price at or before the block's time (within the price's resolution plus 10 minutes), 2 decimals; an amount: event rows are valued when they happened, not at meta.at. Null when tao_rao is null or no such price exists.

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

The coldkey whose stake moved (the beneficiary), SS58. Null for a trade without a staking event (the signer is then the account).

Format: SS58 address
hotkeystring · can be null

The hotkey the stake sits on, SS58. Null when the trade has none.

Format: SS58 address
signerstring · can be null

The extrinsic's signer, SS58: who signed, not necessarily whose stake moved (a proxy, an EVM caller). Null for a block hook or an EVM-originated call without a substrate signer.

Format: SS58 address
extrinsic_hashstring · can be null

Hash of the extrinsic, 0x + 64 lower-case hex. Null for a block hook.

Format: 32-byte hex: 0x and 64 hex digits
generationinteger · unit id · can be null · beta

Opaque life id (the life's registration identifier), NOT a block height; use life_start_height for the first block. The life of the row's subnet (netuid) at its block (the life the candles key on). Null when no life is recorded, and on an older data version's answer.

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.

counterpart_generationinteger · unit id · can be null · beta

On a swap, the life of the destination subnet (counterpart_netuid) at the row's block; null on every other side, and on an older data version's answer.

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.