OHLCV candles of a subnet pool
https://api.bittensor.ai/api/v2/subnets/{netuid}/candles- Status
- Stable
- Auth
- API key or OAuth access token
- Scope
data:read- Rate limit
plan
Price candles of one subnet's pool, oldest first, labelled by open_at.
Full description
Price candles of one subnet's pool, oldest first, labelled by open_at. Intervals 1m, 5m, 15m, 30m, 1h, 4h, 1d and 1w; buckets are UTC-aligned from a Monday origin (2000-01-03T00:00Z), so a 4h bucket opens at 00, 04, ... 20 UTC and a 1w bucket on a Monday. They stop at a generation boundary: the default is the slot's current generation, generation= selects an earlier one. With from_time, pages forward (newer buckets) through meta.page.next_cursor; without it, the first page is the latest limit buckets before to_time (or now) and the cursor pages back to older ones; the cursor ends (null) when no further page exists. Rows are oldest first on every page. The series is continuous: a bucket without swaps carries the previous close, or the pool's state before it (is_carried: true, trades 0), even on a pool that never swapped, and no bucket before meta.coverage or the generation's start is served. A bucket that began before meta.coverage.from_height is flagged partial (its first_height can be below from_height). Each bucket also carries its OHLC as USD prices (open_price_usd..close_price_usd, USD per alpha) and its volume in USD, all at TAO/USD at the bucket's close; with currency, the same OHLC in that currency (open_price_fiat..close_price_fiat, meta.fiat_currency). Errors are application/problem+json: INVALID_INTERVAL, INVALID_CURRENCY, INVALID_LIMIT, INVALID_TIME, INVALID_RANGE, INVALID_WINDOW, INVALID_CURSOR, SUBNET_NOT_FOUND (404), UNKNOWN_PARAMETER, SOURCE_NOT_READY (503). from_time and to_time must sit on a bucket boundary of interval (UTC from the Monday 2000-01-03 origin: whole hours for 1h, 00/04/../20 UTC for 4h, midnight for 1d, a Monday midnight for 1w); otherwise a 400 INVALID_WINDOW. One URL per window is what lets every viewer of a closed window share one cached answer. With interval=1d, meta.final_through_day is the key to cache closed days by: the bars of the days through it never change again (but by an announced rerun), so pass to_time = the end of that day for a page that never changes; null for every other interval and on an older data version's answer. countback returns the N bars ending at to_time in one call (up to 5,000). Finality and caching: a bar is final once it can no longer change (it ends at or before meta.final_through). A page whose every bar is final and whose window is fixed (an explicit to_time at or before meta.final_through and generation given, or a cursor page back) is served Cache-Control: public, max-age=31536000, immutable with an ETag; any other page keeps a short lifetime, as the forming bar changes every block. With currency, each bar's fx_source / fx_day_first / fx_day_last and meta.fx_days (each rate's day, value and publisher) name the reference rates used (null with meta.fx_unavailable_reason while not available). A bar without a price of its own is carried (is_carried, carried_reason): its open, high, low and close are the previous close and its volumes 0.
Path parameters
- netuidpath, required· integer · 0 to 65535
Subnet slot (0 = root).
Query parameters
- intervalquery· enum · one of 1m, 5m, 15m, 30m, 1h, 4h, 1d, 1w · default 1h
Bucket width:
1m,5m,15m,30m,1h,4h,1dor1w(UTC, weeks start Monday).- from_timequery· string (date-time)
Start of the window, inclusive (RFC 3339).
- Format: date and time, ISO 8601 in UTC
- to_timequery· string (date-time)
End of the window, exclusive (RFC 3339). Default: now.
- Format: date and time, ISO 8601 in UTC
- generationquery· integer · 0 to 2147483647
Subnet lifetime (its registration block); default the slot's current one.
- limitquery· integer · default 100 · 1 to 1000
Page size, 1..1000.
- 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.- currencyquery· enum · one of AED, ARS, AUD, BGN, BRL, CAD, CHF, CNY, COP, CZK, DKK, EUR, GBP, HKD, HUF, IDR, ILS, INR, ISK, JPY, KES, KRW, MXN, MYR, NGN, NOK, NZD, PHP, PKR, PLN, RON, SEK, SGD, THB, TRY, TWD, UAH, VND, ZAR
Also price the OHLC in this currency (ISO 4217, upper case; the
*_price_fiatmembers). Omitted: those are null. USD is always served (*_price_usd).- countbackquery· integer · 1 to 5000
Return the
countbackbars ending atto_time(default: now, the forming bar included), oldest first, up to 5000 (the TradingView datafeed'scountback). Use it instead oflimit: it cannot be combined withfrom_time,cursororlimit(400INVALID_PARAMETER). Fewer bars come back only when the series starts later (meta.interval_first_bucket_time). To read further back, ask again withto_time= the first bar'sopen_at;meta.page.next_cursoris null on acountbackanswer.- precisionquery· string
full: the same members with the USD, fiat and BTC prices andvolume_usdunrounded, as decimal strings. Accepted only from service integrations; for any other caller this parameter does not exist.
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.
Candles, oldest first: a continuous series of UTC buckets (a bucket without swaps is carried, is_carried), never before meta.coverage or the generation's start; [] when the window has none.
- open_atstring (date-time)
Start of the bucket, RFC 3339 UTC.
- Format: date and time, ISO 8601 in UTC
- openstring · unit tao_per_alpha · 9 decimals
Price (TAO per alpha) entering the bucket: the previous block's close, same subnet life; 9 decimals.
- Format: decimal number with 9 places, as a string
- highstring · unit tao_per_alpha · 9 decimals
Highest price (TAO per alpha) in the bucket, 9 decimals.
- Format: decimal number with 9 places, as a string
- lowstring · unit tao_per_alpha · 9 decimals
Lowest price (TAO per alpha) in the bucket, 9 decimals.
- Format: decimal number with 9 places, as a string
- closestring · unit tao_per_alpha · 9 decimals
Price (TAO per alpha) after the bucket's last block, as the runtime reports it; 9 decimals.
- Format: decimal number with 9 places, as a string
- open_price_usdstring · unit usd_per_alpha · 6 decimals · can be null
openas a USD price (USD per alpha, not an amount), 6 decimals: the previous bar's close (the series' first bar: its alphaopenat the TAO/USD rate just before it), where each point is the alpha price in TAO x TAO/USD at that point's close (per-minute products at every interval, hourly before 2024-04-11 for TAO's composite;meta.fiat_methodstates it), so a TAO/USD move inside a bar is in its range andopen_price_usdequals the previous bar'sclose_price_usd. On an older data version's answer the four are the TAO prices x one TAO/USD rate at the bucket's close. Null when no TAO/USD price exists.- Format: decimal number, as a string
- high_price_usdstring · unit usd_per_alpha · 6 decimals · can be null
highas a USD price (USD per alpha, not an amount), 6 decimals: the highest point of the bar, the open included, where each point is the alpha price in TAO x TAO/USD at that point's close (per-minute products at every interval, hourly before 2024-04-11 for TAO's composite;meta.fiat_methodstates it), so a TAO/USD move inside a bar is in its range andopen_price_usdequals the previous bar'sclose_price_usd. On an older data version's answer the four are the TAO prices x one TAO/USD rate at the bucket's close. Null when no TAO/USD price exists.- Format: decimal number, as a string
- low_price_usdstring · unit usd_per_alpha · 6 decimals · can be null
lowas a USD price (USD per alpha, not an amount), 6 decimals: the lowest point of the bar, the open included, where each point is the alpha price in TAO x TAO/USD at that point's close (per-minute products at every interval, hourly before 2024-04-11 for TAO's composite;meta.fiat_methodstates it), so a TAO/USD move inside a bar is in its range andopen_price_usdequals the previous bar'sclose_price_usd. On an older data version's answer the four are the TAO prices x one TAO/USD rate at the bucket's close. Null when no TAO/USD price exists.- Format: decimal number, as a string
- close_price_usdstring · unit usd_per_alpha · 6 decimals · can be null
closeas a USD price (USD per alpha, not an amount), 6 decimals: the bar's last point, where each point is the alpha price in TAO x TAO/USD at that point's close (per-minute products at every interval, hourly before 2024-04-11 for TAO's composite;meta.fiat_methodstates it), so a TAO/USD move inside a bar is in its range andopen_price_usdequals the previous bar'sclose_price_usd. On an older data version's answer the four are the TAO prices x one TAO/USD rate at the bucket's close. Null when no TAO/USD price exists.- Format: decimal number, as a string
- open_price_fiatstring · unit ccy_per_alpha · 6 decimals · can be null
openinmeta.fiat_currencyper alpha (a price), 6 decimals: the same per-point rule asopen_price_usdwith each point also x its UTC day's ECB rate of that currency (on an older data version's answer,_price_usdx the ECB rate at the bucket's close). Null without thecurrencyparameter, and when either rate is missing.- Format: decimal number, as a string
- high_price_fiatstring · unit ccy_per_alpha · 6 decimals · can be null
highinmeta.fiat_currencyper alpha (a price), 6 decimals: the same per-point rule ashigh_price_usdwith each point also x its UTC day's ECB rate of that currency (on an older data version's answer,_price_usdx the ECB rate at the bucket's close). Null without thecurrencyparameter, and when either rate is missing.- Format: decimal number, as a string
- low_price_fiatstring · unit ccy_per_alpha · 6 decimals · can be null
lowinmeta.fiat_currencyper alpha (a price), 6 decimals: the same per-point rule aslow_price_usdwith each point also x its UTC day's ECB rate of that currency (on an older data version's answer,_price_usdx the ECB rate at the bucket's close). Null without thecurrencyparameter, and when either rate is missing.- Format: decimal number, as a string
- close_price_fiatstring · unit ccy_per_alpha · 6 decimals · can be null
closeinmeta.fiat_currencyper alpha (a price), 6 decimals: the same per-point rule asclose_price_usdwith each point also x its UTC day's ECB rate of that currency (on an older data version's answer,_price_usdx the ECB rate at the bucket's close). Null without thecurrencyparameter, and when either rate is missing.- Format: decimal number, as a string
- volume_usdstring · unit usd · 2 decimals · can be null
volume_tao_raoin USD, 2 decimals; an amount: each point's TAO volume x that point's TAO/USD, summed (on an older data version's answer, the whole volume x TAO/USD at the bucket's close). Null when no TAO/USD price exists.- Format: decimal number, as a string
- volume_tao_raostring · unit rao (÷1e9)
TAO into plus out of the pool by extrinsic swap steps (each counted once), in rao.
- Format: whole number, as a string · on chain: u64
- buy_volume_tao_raostring · unit rao (÷1e9)
TAO into the pool by buys (TAO in, alpha out), in rao.
- Format: whole number, as a string · on chain: u64
- sell_volume_tao_raostring · unit rao (÷1e9)
TAO out of the pool by sells (alpha in, TAO out), in rao.
- Format: whole number, as a string · on chain: u64
- volume_alpha_raostring · unit alpha_rao (÷1e9)
Alpha into plus out of the pool, in alpha rao.
- Format: whole number, as a string · on chain: u64
- tradesinteger · unit count
Number of swap steps in the bucket.
- pool_tao_raostring · unit rao (÷1e9) · can be null
TAO reserve of the pool at the bucket's close, in rao.
- Format: whole number, as a string · on chain: u64
- pool_alpha_raostring · unit alpha_rao (÷1e9) · can be null
Alpha reserve (alpha in) of the pool at the bucket's close, in alpha rao.
- Format: whole number, as a string · on chain: u64
- first_heightinteger · unit block · can be null
First block of the bucket with a pool record; null on a carried bucket (
is_carried). On apartialbucket it can be belowmeta.coverage.from_height(the bucket began before coverage).- last_heightinteger · unit block · can be null
Last block of the bucket processed so far; null on a carried bucket (
is_carried).- is_carriedboolean · optional · beta
True when the bar has no price of its own: open, high, low and close are the close before it (the previous bar's; for a page's first bar, the last price before it) and the volumes are 0 (
carried_reasonsays why). The series is continuous, so a quiet bucket is a carried bar, never a gap.- carried_reasonstring · can be null · beta
Why the bar is carried:
no_trades(no swap and no pool change in the bucket),no_source_data(no price was recorded for the bucket),coarser_source(a minute bar inside an hour whose prices are known only hourly: before 2024-04-11 12:00 UTC the TAO/USD series is hourly). Null exactly whenis_carriedis false. New values may be added; treat unknown values as unavailable.- carriedboolean · deprecated
True when the bucket has no swap and no pool change recorded: open, high, low and close are the previous bucket's close (for the first bucket of a page, the pool's price and reserves just before it),
tradesand the volumes are 0,first_height/last_heightare null. The series is continuous, so a quiet hour is a carried bucket, never a gap, even on a pool that never swapped. Deprecated: use is_carried; sunset 2027-02-15.- Deprecated since 2026-10-17, removed after 2027-02-15. Use
is_carriedinstead. - closedboolean
False while the bucket is still forming (its end is after
meta.at).- partialboolean
True when the bucket began before
meta.coverage.from_height(its volume, trade count and open miss the blocks before coverage) or before the life's first block (meta.life_start_height: the life's first bucket covers only its own blocks), so it is not a whole bucket. False otherwise.- finalboolean · optional · beta
True when the bar can no longer change: it ends at or before
meta.final_through(itsopen_atplus the interval). A final bar is safe to cache for good. False while the bar is forming or may still be corrected, and on every bar whilemeta.final_throughis null.- fx_sourcestring · can be null · beta
Who published the reference rate of the bar's last price point, the one that priced the fiat close (for example
ecb). Null withoutcurrency, on a bar without fiat prices, and whilemeta.fx_unavailable_reasonis set. New values may be added; show an unknown value as is (or generically).- fx_day_firststring (date) · can be null · beta
The earliest UTC rate day among the price points inside this bar (each point is priced at the latest reference rate published on or before its day). The fiat open is not one of them: it is the previous point's close at that point's rate, so its rate day is the previous bar's
fx_day_last(for the page's first bar, the rate in force before the page, listed inmeta.fx_days). Equal tofx_day_lastwhen every point inside the bar has the same rate day. Null withoutcurrency, on a bar without fiat prices, and whilemeta.fx_unavailable_reasonis set.- Format: date, YYYY-MM-DD
- fx_day_laststring (date) · can be null · beta
The latest UTC rate day among the price points inside this bar (each point is priced at the latest reference rate published on or before its day); the fiat close's rate day. Null without
currency, on a bar without fiat prices, and whilemeta.fx_unavailable_reasonis set.- Format: date, YYYY-MM-DD
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_CURRENCY
- INVALID_CURSOR
- INVALID_GENERATION
- INVALID_INTERVAL
- INVALID_LIMIT
- INVALID_NETUID
- INVALID_RANGE
- INVALID_TIME
- INVALID_WINDOW
- PAYMENT_REQUIRED
- PLAN_REQUIRED
- RATE_LIMITED
- REPEATED_PARAMETER
- SERVICE_UNAVAILABLE
- SOURCE_BUSY
- SOURCE_NOT_READY
- SOURCE_TIMEOUT
- SUBNET_NOT_FOUND
- UNAUTHORIZED
- UNKNOWN_PARAMETER
- VALIDATION_ERROR
From the API's published specification, version 1.165.0.