Skip to content
TAO$188.40
BTC0.00293
MCap$2.21B
Vol$86.07M

API reference / Subnets

Which mechanism moved a subnet's alpha price, per day or hour

GET/api/v2/subnets/{netuid}/price-attribution
Status
Beta
Auth
API key or OAuth access token
Scope
data:read
Rate limit
plan

Per closed UTC day or hour, oldest first: the pool price's log return (basis points) split into protocol buys (the chain's per-block excess TAO buy and BasketSwapped buys), protocol sells (root-claim sells and BasketSwapped sells), user buys, user sells, cross-subnet moves and a measured residual; the six sum exactly to the log return. Each pool step is chained from its exact pre-step reserves, so the residual is rounding plus coverage.unresolved_trades. Also the TAO each mechanism moved (flows_tao) and the alpha supply (supply_alpha). Only the subnet's CURRENT life is served (meta.life_start_height); history starts at meta.coverage.from_height. Today flows_tao.buyback and supply_alpha.emitted_to_participants are always null (not available yet). from_time / to_time must sit on the grain (whole hours for hour, midnight for day; else 400 INVALID_WINDOW); omitted, the default window. A pinned window that has closed, every bucket final, is cached as settled; without to_time, an answer whose every bucket is final is cached until its next bucket closes (max-age = the seconds to that time). Errors are application/problem+json: INVALID_TIME, INVALID_RANGE, INVALID_WINDOW, UNKNOWN_PARAMETER, NOT_READY (503, inputs still being prepared), SOURCE_TIMEOUT (503), SOURCE_NOT_READY (503).

Beta: this route may change with one release's notice in the v2 changelog; additive changes need none (x-stability: beta).

Path parameters

netuidpath, required· integer · 0 to 65535

Subnet slot (0 = root).

Query parameters

from_timequery· string (date-time)

Window start, inclusive (RFC 3339, on the grain).

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

Window end, exclusive (RFC 3339, on the grain).

Format: date and time, ISO 8601 in UTC
grainquery· enum · one of day, hour · default day

Bucket width: day (default) or hour.

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 window and its buckets.

netuidinteger · unit id

The subnet slot.

grainenum

Bucket width.

One of: day, hour
start_timestring (date-time)

Window start after defaults and clamping, RFC 3339 UTC.

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

Window end (exclusive) after defaults and clamping, RFC 3339 UTC.

Format: date and time, ISO 8601 in UTC
bucketsarray of objects

Closed, available buckets in the window, ascending; a bucket not closed yet is left out, never served partial.

11 fields in buckets (each item)
start_timestring (date-time)

Bucket start (inclusive), RFC 3339 UTC.

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

Bucket end (exclusive), RFC 3339 UTC.

Format: date and time, ISO 8601 in UTC
open_heightinteger · unit block · can be null

Last block before start_time: price_open's block.

close_heightinteger · unit block · can be null

Last block before end_time: price_close's block.

price_openstring · unit tao_per_alpha · 18 decimals · can be null

Pool price SubnetTAO / SubnetAlphaIn at open_height, TAO per alpha (end-of-block reserves).

Format: decimal number, as a string
price_closestring · unit tao_per_alpha · 18 decimals · can be null

Pool price at close_height, TAO per alpha.

Format: decimal number, as a string
log_return_bpsstring · unit bps (÷10000) · 2 decimals · can be null

ln(price_close / price_open) × 10,000. Log returns add: a window's return is the sum of its buckets', and so is each component.

Format: decimal number, as a string · can be negative
components_bpsobject

log_return_bps split by mechanism, basis points.

6 fields in components_bps
protocol_buystring · unit bps (÷10000) · 2 decimals · can be null

Chain buys: each block's excess TAO (SubnetExcessTao) buying alpha from the pool, Σ 2·ln(1 + E/y) per block, exact; and BasketSwapped buys. Null while the bucket's protocol inputs aren't available yet: unknown, never 0.

Format: decimal number, as a string · can be negative
protocol_sellstring · unit bps (÷10000) · 2 decimals · can be null

Protocol sells: root-dividend claims sold on this pool (claim_root's pool steps) and BasketSwapped sells, each chained from its exact pre-step reserves. Null while the bucket's protocol inputs aren't available yet: unknown, never 0.

Format: decimal number, as a string · can be negative
user_buystring · unit bps (÷10000) · 2 decimals · can be null

Stakes (owner buybacks included), each pool step chained from its exact pre-step reserves.

Format: decimal number, as a string · can be negative
user_sellstring · unit bps (÷10000) · 2 decimals · can be null

Unstakes, alpha-paid transaction fees included, the same way.

Format: decimal number, as a string · can be negative
cross_subnetstring · unit bps (÷10000) · 2 decimals · can be null

Stake moved between this subnet and another: the leg on this pool. Never counted in user_buy / user_sell.

Format: decimal number, as a string · can be negative
residualstring · unit bps (÷10000) · 2 decimals · can be null

log_return_bps minus the five components above (all quantized to 2 decimals first), so the six sum exactly: rounding and pool steps without pre-step reserves (coverage.unresolved_trades). Measured, never absorbed. Null while the bucket's protocol inputs aren't available yet: unknown, never 0.

Format: decimal number, as a string · can be negative
flows_taoobject

TAO moved by each mechanism.

8 fields in flows_tao
injectedstring · unit tao · 9 decimals · can be null

SubnetTaoInEmission added with its matching alpha: price-neutral (both reserves grow in proportion), so it has no component. Null while the bucket's protocol inputs aren't available yet: unknown, never 0.

Format: decimal number, as a string
protocol_buystring · unit tao · 9 decimals · can be null

Excess TAO the chain swapped into the pool, plus BasketSwapped buys. Null while the bucket's protocol inputs aren't available yet: unknown, never 0.

Format: decimal number, as a string
protocol_sellstring · unit tao · 9 decimals · can be null

TAO paid out of the pool by protocol sells. Null while the bucket's protocol inputs aren't available yet: unknown, never 0.

Format: decimal number, as a string · can be negative
user_buystring · unit tao · 9 decimals · can be null

TAO staked into the pool (behind components_bps.user_buy).

Format: decimal number, as a string
user_sellstring · unit tao · 9 decimals · can be null

TAO unstaked out of the pool (behind components_bps.user_sell).

Format: decimal number, as a string
buybackstring · unit tao · 9 decimals · can be null

Of user_buy, TAO the subnet owner spent on buybacks (AddStakeBurn). Always null for now: the split isn't available yet (its TAO stays in user_buy).

Format: decimal number, as a string
cross_subnet_buystring · unit tao · 9 decimals · can be null

TAO that entered this pool as the buy leg of stake moved in from another subnet.

Format: decimal number, as a string
cross_subnet_sellstring · unit tao · 9 decimals · can be null

TAO that left this pool as the sell leg of stake moved out to another subnet.

Format: decimal number, as a string
supply_alphaobject

Alpha supply and issuance.

6 fields in supply_alpha
alpha_instring · unit alpha · 9 decimals · can be null

Pool alpha reserve (SubnetAlphaIn) at the close block.

Format: decimal number, as a string
alpha_outstring · unit alpha · 9 decimals · can be null

Alpha outside the pool (SubnetAlphaOut) read at alpha_out_as_of_height.

Format: decimal number, as a string
alpha_out_as_of_heightinteger · unit block · can be null

Block alpha_out was read at.

emitted_to_participantsstring · unit alpha · 9 decimals · can be null

Alpha emitted to miners, validators, the owner and root stakers during the bucket. Always null for now (not available yet).

Format: decimal number, as a string
burnedstring · unit alpha · 9 decimals · can be null

Alpha burned (AlphaBurned). Does not touch the reserves.

Format: decimal number, as a string
recycledstring · unit alpha · 9 decimals · can be null

Alpha recycled (AlphaRecycled). Does not touch the reserves.

Format: decimal number, as a string
coverageobject

Input coverage and the residual's share.

6 fields in coverage
blocksinteger · unit blocks · can be null

Blocks in the bucket: close_height - open_height. Null when a boundary block is missing.

excess_samplesinteger · unit count

Protocol samples inside the bucket.

protocol_basisstring · can be null

Where protocol_buy / protocol_sell came from: exact_per_block (the per-block SubnetExcessTao and the root-claim pool steps). Null when the protocol side is.

residual_sharestring · unit ratio · 4 decimals · can be null

|residual| / the sum of the six components' absolute values: the share of the bucket's gross movement left unexplained. Null when the residual is, or when nothing moved.

Format: decimal number, as a string
is_finalboolean

True when every input is present, so the bucket will not change.

unresolved_tradesinteger · unit count

Pool steps in the bucket whose price impact could not be attributed (no pre-step reserves), so it stays in residual. 0 on a clean bucket.

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.