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

API reference / Markets

OHLCV candles of a subnet pool

GET/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, 1d or 1w (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_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.

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_fiat members). Omitted: those are null. USD is always served (*_price_usd).

countbackquery· integer · 1 to 5000

Return the countback bars ending at to_time (default: now, the forming bar included), oldest first, up to 5000 (the TradingView datafeed's countback). Use it instead of limit: it cannot be combined with from_time, cursor or limit (400 INVALID_PARAMETER). Fewer bars come back only when the series starts later (meta.interval_first_bucket_time). To read further back, ask again with to_time = the first bar's open_at; meta.page.next_cursor is null on a countback answer.

precisionquery· string

full: the same members with the USD, fiat and BTC prices and volume_usd unrounded, 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

open as a USD price (USD per alpha, not an amount), 6 decimals: the previous bar's close (the series' first bar: its alpha open at 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_method states it), so a TAO/USD move inside a bar is in its range and open_price_usd equals the previous bar's close_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

high as 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_method states it), so a TAO/USD move inside a bar is in its range and open_price_usd equals the previous bar's close_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

low as 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_method states it), so a TAO/USD move inside a bar is in its range and open_price_usd equals the previous bar's close_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

close as 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_method states it), so a TAO/USD move inside a bar is in its range and open_price_usd equals the previous bar's close_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

open in meta.fiat_currency per alpha (a price), 6 decimals: the same per-point rule as open_price_usd with each point also x its UTC day's ECB rate of that currency (on an older data version's answer, _price_usd x the ECB rate at the bucket's close). Null without the currency parameter, and when either rate is missing.

Format: decimal number, as a string
high_price_fiatstring · unit ccy_per_alpha · 6 decimals · can be null

high in meta.fiat_currency per alpha (a price), 6 decimals: the same per-point rule as high_price_usd with each point also x its UTC day's ECB rate of that currency (on an older data version's answer, _price_usd x the ECB rate at the bucket's close). Null without the currency parameter, and when either rate is missing.

Format: decimal number, as a string
low_price_fiatstring · unit ccy_per_alpha · 6 decimals · can be null

low in meta.fiat_currency per alpha (a price), 6 decimals: the same per-point rule as low_price_usd with each point also x its UTC day's ECB rate of that currency (on an older data version's answer, _price_usd x the ECB rate at the bucket's close). Null without the currency parameter, and when either rate is missing.

Format: decimal number, as a string
close_price_fiatstring · unit ccy_per_alpha · 6 decimals · can be null

close in meta.fiat_currency per alpha (a price), 6 decimals: the same per-point rule as close_price_usd with each point also x its UTC day's ECB rate of that currency (on an older data version's answer, _price_usd x the ECB rate at the bucket's close). Null without the currency parameter, and when either rate is missing.

Format: decimal number, as a string
volume_usdstring · unit usd · 2 decimals · can be null

volume_tao_rao in 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 a partial bucket it can be below meta.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_reason says 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 when is_carried is 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), trades and the volumes are 0, first_height / last_height are 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_carried instead.
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 (its open_at plus 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 while meta.final_through is 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 without currency, on a bar without fiat prices, and while meta.fx_unavailable_reason is 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 in meta.fx_days). Equal to fx_day_last when every point inside the bar has the same rate day. Null without currency, on a bar without fiat prices, and while meta.fx_unavailable_reason is 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 while meta.fx_unavailable_reason is 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), 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.