Trades across subnets
https://api.bittensor.ai/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
netuidor itscounterpart_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 400INVALID_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.100000000000for 100 TAO. Rows without a TAO amount (tao_raonull) never match. Anything else is a 400INVALID_AMOUNT.- sidequery· string
all(the default: every side,feeincluded) or a comma list ofbuy,sell,swap,basket_claim,basket_swap,registration,fee,other(OR;buy,sell,swapleaves thefeerows out).feerows exist only up tometa.coverage.fee_classified_to_height: above it a fee paid in alpha is still asell. Anything else is a 400INVALID_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; aboveto_height: a 400INVALID_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) orasc(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_cursorof 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 400INVALID_CURSOR.- 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 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, withnetuidfor 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 ofnetuidinto alpha ofcounterpart_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) orother. Afeerow needs the call-path trace: it is classified only up tometa.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 asell, and it becomes afeerow 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_indexof 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
netuidout 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_netuidreceived, 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_raofrom 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
buyorsellrow, two on aswap(the sell leg onnetuid, the buy leg oncounterpart_netuid, also when they are equal),[]on every other side. A swap fee is not a transaction fee (that is the extrinsic'stx_fee). An entry'samount_raocan 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) orbuy(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:alphaofnetuid(a sell leg) ortao(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,
netuidfor the sell leg andcounterpart_netuidfor 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
assetistao, alpha rao ofnetuidwhenassetisalpha(a mixed-denomination field:x-unitkeepsraoas the 1e9 scale andassetnames the denomination; never add an alpha amount to TAO).0when 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_raoin 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 atmeta.at. Null whentao_raois 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
signeris 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_heightfor 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
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.- 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), 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_CURSOR
- INVALID_HEIGHT
- INVALID_INCLUDE
- INVALID_LIMIT
- INVALID_NETUID
- INVALID_ORDER
- INVALID_RANGE
- INVALID_SIDE
- INVALID_TIME
- 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.