Which mechanism moved a subnet's alpha price, per day or hour
https://api.bittensor.ai/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) orhour.
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_bpssplit 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_bpsminus 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 inuser_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_outwas 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_sellcame from:exact_per_block(the per-block SubnetExcessTao and the root-claim pool steps). Null when the protocol side is.- 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), 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_NETUID
- INVALID_PARAMETER
- INVALID_RANGE
- 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.