Supra Core API — Public Client Documentation

Chapter 10 — Candles Endpoint

1. Purpose

This chapter documents:

GET /api/v1/candles

The candles endpoint returns bounded historical candle rows for an exact token/quote pair, granularity, network, and scope.

It is intended for:

• price charts;
• market analytics;
• trend widgets;
• historical summaries;
• bots and alerting tools;
• portfolio interfaces.

It is a read-oriented historical data endpoint. It does not provide streaming candles, trading, order placement, wallet signing, write operations, or private account management.

---

2. Endpoint Summary

The response is JSON and can contain an empty array.

---

3. Common Requirements

3.1 HTTPS

Use the HTTPS base supplied for your API access:

<api-base>

3.2 Authentication

Send:

X-API-Key: <api-key>

Common request headers:

Accept: application/json
X-API-Key: <api-key>

Warning: Never expose <api-key> in browser code, frontend chart configuration, screenshots, logs, or support reports.

3.3 JSON parsing

Clients should:

1. inspect the HTTP status;
2. parse the response as JSON;
3. confirm ok: true;
4. handle empty arrays;
5. preserve decimal precision;
6. parse Unix and UTC timestamp fields explicitly.

All examples below use placeholder values and are illustrative.

---

4. GET /api/v1/candles Overview

The candles endpoint returns historical bucketed pair data for:

• one token;
• one quote token;
• one granularity;
• one source scope;
• one venue scope;
• one network.

Each row can include:

• bucket boundaries;
• open price;
• high price;
• low price;
• close price;
• token and quote volume;
• swap, buy, and sell counts;
• first and last represented event context.

OHLC prices are pair-derived and denominated in the requested quote token. They are not automatically true USD market prices.

The endpoint:

• returns newest buckets first;
• is bounded by limit and offset;
• is not a real-time stream;
• can return an empty array;
• can contain missing time buckets;
• can lag recent swaps.

Important: A candle response describes available derived history. It is not a promise that every possible time bucket exists.

4.1 Chart-oriented token history

For a chart-ready chronological response with server-selected granularity, use:

GET /api/v1/chart/token

It requires token and quote, accepts optional network and range, and defaults to range=24h. Supported range values are 24h, 7d, 30d, 90d, 1y, and all. The server maps these respectively to 5min, 15min, 1h, 1h, 12h, and 24h stored candles. 1y means the previous 365 days.

The chart endpoint returns oldest first, uses the aggregate all/all scopes, and returns no more than 2,500 points. If more points are available, meta.truncated is true. It does not reverse the pair or require every candle to be final. Unlike the canonical candles endpoint, it fills presentation gaps in memory after a real price seed exists. Synthetic points carry the previous real close, use zero volume and counts, expose null event/block/transaction evidence, and set synthetic=true, has_events=false, and is_final=false. They are never persisted.

meta distinguishes:

• the requested wall-clock range;
• the first and last returned candle;
• complete available history for the selected pair and granularity.

No matching data returns HTTP 200 with data: [].

The chart response also includes pair-level range change metadata. It does not calculate change from the first and last returned chart points. Instead, current is the latest qualified five-minute pair price at or before the requested end, and baseline is the latest qualified five-minute pair price at or before the requested start. This keeps sparse event-based charts from presenting a short internal interval as the full requested-range change.

baseline_age_seconds reports how far the selected baseline precedes the requested start. A baseline beyond the configured maximum remains visible for diagnostics but produces change_percent=null, change_available=false, and change_reason=baseline_too_distant. Other reasons are current_price_unavailable, baseline_unavailable, invalid_baseline_price, and available. range=all has no baseline and no percentage.

---

5. Request Parameters

All parameters are query-string parameters.

5.1 Required token and quote

Missing token or quote returns a 400 request error.

The price orientation is:

token priced in quote

Reversing the parameters requests a different pair orientation.

A quote symbol containing USD, USDC, USDT, or similar text still identifies an on-chain quote asset. It does not automatically turn the candle series into off-chain USD history.

5.2 Time filtering

from and to filter by the candle's bucket start time.

The boundaries are inclusive:

bucket_start_unix >= from
bucket_start_unix <= to

If from is greater than to, the request returns 400.

5.3 Scope matching

Scope filters are exact.

The defaults are:

source_scope=all
dex_scope=all

Requesting a scope that has no matching candles can return data: [].

---

6. Supported Granularities

The currently supported values are:

If granularity is omitted, the default is 5min. The deprecated input alias 1d is normalized to 24h, and the response reports 24h. The removed 1min value is rejected.

Unsupported values return a 400 request error.

Use the value exactly as documented:

<granularity>

Do not invent alternatives such as 60s, hour, or daily.

range describes the requested chart span; granularity describes one stored candle bucket. Calendar granularities use real UTC calendar boundaries rather than fixed approximations for months or years.

---

7. Basic Curl Example

curl -sS \
  -H 'Accept: application/json' \
  -H 'X-API-Key: <api-key>' \
  '<api-base>/api/v1/candles?token=<token-address>&quote=<quote-token-address>&granularity=<granularity>&limit=<limit>&offset=<offset>'

Example with a Unix bucket-start range:

curl -sS \
  -H 'Accept: application/json' \
  -H 'X-API-Key: <api-key>' \
  '<api-base>/api/v1/candles?token=<token-address>&quote=<quote-token-address>&granularity=<granularity>&from=<from-unix>&to=<to-unix>&limit=<limit>&offset=<offset>'

Replace placeholders only inside your protected backend environment.

Chart-oriented example:

curl -sS \
  -H 'Accept: application/json' \
  -H 'X-API-Key: <api-key>' \
  '<api-base>/api/v1/chart/token?token=<token-address>&quote=<quote-token-address>&range=<range>'

---

8. Response Example

The following JSON is illustrative and intentionally shortened:

{
  "ok": true,
  "data": [
    {
      "network": "mainnet",
      "token_metadata": "<token-address>",
      "token_symbol": "<token-symbol>",
      "quote_token_metadata": "<quote-token-address>",
      "quote_token_symbol": "<quote-token-symbol>",
      "granularity": "<granularity>",
      "bucket_start_unix": 1234567800,
      "bucket_start_utc": "<iso-utc-timestamp>",
      "bucket_end_unix": 1234567859,
      "bucket_end_utc": "<iso-utc-timestamp>",
      "open_price": "<decimal-string>",
      "high_price": "<decimal-string>",
      "low_price": "<decimal-string>",
      "close_price": "<decimal-string>",
      "volume_token": "<decimal-string>",
      "volume_quote": "<decimal-string>",
      "swaps_count": 4,
      "buy_count": 2,
      "sell_count": 2,
      "first_event_time_unix": 1234567805,
      "first_event_time_utc": "<iso-utc-timestamp>",
      "last_event_time_unix": 1234567840,
      "last_event_time_utc": "<iso-utc-timestamp>",
      "first_block_height": 123,
      "last_block_height": 123,
      "first_tx_hash": "<tx-hash>",
      "last_tx_hash": "<tx-hash>",
      "is_final": true
    }
  ],
  "meta": {
    "api_version": "v1",
    "endpoint": "candles",
    "network": "mainnet",
    "token": "<token-address>",
    "quote": "<quote-token-address>",
    "granularity": "<granularity>",
    "source_scope": "all",
    "dex_scope": "all",
    "limit": 100,
    "offset": 0,
    "count": 1
  }
}

Decimal fields can be returned as strings. Event context fields can be nullable.

Important: Preserve numeric precision and do not convert every OHLCV value directly to a low-precision float.

---

9. Candle Field Guide

9.1 Token

token_metadata identifies the token being priced.

token_symbol is a display label and can be nullable.

9.2 Quote

quote_token_metadata identifies the asset in which the price is expressed.

quote_token_symbol is a display label and can be nullable.

Do not compare candles with different quote tokens as if they used the same unit.

9.3 Granularity

granularity identifies the bucket interval:

• 5min;
• 15min;
• 1h;
• 12h;
• 24h;
• 7d;
• 1mo;
• 3mo;
• 6mo;
• 1y.

9.4 Bucket start

bucket_start_unix is the bucket start as a Unix timestamp in seconds.

bucket_start_utc is the corresponding UTC timestamp string.

9.5 Bucket end

bucket_end_unix is the bucket end as a Unix timestamp in seconds.

bucket_end_utc is the corresponding UTC timestamp string.

Use the supplied boundaries rather than recomputing them with local timezone rules.

9.6 Open

open_price is the first represented price in the bucket.

9.7 High

high_price is the highest represented price in the bucket.

9.8 Low

low_price is the lowest represented price in the bucket.

9.9 Close

close_price is the last represented price in the bucket.

9.10 Volume

volume_token is the represented bucket volume in token units.

volume_quote is the represented bucket volume in quote-token units.

Always identify the unit before displaying or aggregating volume.

9.11 Activity counts

Current candle rows include:

• swaps_count;
• buy_count;
• sell_count.

These are bucket activity counts. They do not represent unique users.

9.12 First and last event time

The endpoint can include:

• first_event_time_unix;
• first_event_time_utc;
• last_event_time_unix;
• last_event_time_utc.

These identify the first and last represented event times inside the bucket.

They can be null.

9.13 First and last block

The endpoint can include:

• first_block_height;
• last_block_height.

They provide public chain-position context when available.

9.14 First and last transaction

The endpoint can include:

• first_tx_hash;
• last_tx_hash.

They can be nullable.

9.15 Nullable fields

Preserve null rather than replacing it with zero or an invented value.

9.16 Finality

is_final is a JSON boolean copied from the persisted candle. The endpoint does not filter out non-final rows.

---

10. OHLCV Interpretation

OHLCV means:

• open — first price represented in the bucket;
• high — highest price represented in the bucket;
• low — lowest price represented in the bucket;
• close — last price represented in the bucket;
• volume — represented activity volume for the bucket.

10.1 Price orientation

All price fields use:

token / quote

Do not invert a price unless your application explicitly performs decimal-safe reciprocal calculation.

These are pair prices for the selected quote asset. They are not universal USD prices, and an external market display can differ because it uses different sources, routes, filters, or valuation rules.

10.2 Volume orientation

Use field names:

• volume_token;
• volume_quote.

Do not add token volume and quote volume together. They use different units.

10.3 Candle validation

A client can apply basic non-destructive checks:

high >= open
high >= close
low <= open
low <= close
bucket_start_unix <= bucket_end_unix

If a check fails, preserve the original response for a redacted support report and avoid silently rewriting it.

10.4 Counts and volume

Do not assume each represented swap contributes the same volume.

Do not infer unique traders from swaps_count.

---

11. Timestamp and Bucket Handling

11.1 Unix timestamps

Fields ending in _unix are Unix seconds.

Parse them as integers.

11.2 UTC strings

Fields ending in _utc are UTC timestamp strings.

Display a local timezone only after parsing the UTC value correctly.

11.3 Do not assume local timezone

Chart code should not interpret a UTC string as browser-local time before parsing it.

Recommended flow:

parse UTC or Unix value
store canonical instant
convert to display timezone
label the displayed timezone

11.4 Chart library conversion

Some chart libraries expect:

• Unix seconds;
• Unix milliseconds;
• ISO strings;
• JavaScript date objects.

Confirm the expected unit. Multiplying seconds by 1000 is appropriate only when the library requires milliseconds.

11.5 Missing buckets

The response does not guarantee one row for every possible interval.

Missing buckets can occur when:

• no represented activity exists;
• a bucket is not yet available;
• the selected pair or scope has incomplete history.

GET /api/v1/candles returns only persisted event buckets and never creates carry-forward rows.

GET /api/v1/chart/token applies the API's documented presentation-only carry-forward policy. It never invents a price before a real seed exists and never treats a synthetic point as new market evidence.

11.6 Ordering

Rows are returned newest first by bucket start.

Many chart libraries expect oldest first. Reverse the page or sort safely in the client before rendering.

---

12. Pagination

The endpoint uses limit and offset.

It does not currently use page_token.

12.1 Basic loop

limit = <limit>
offset = 0

repeat:
    page = request candles with limit and offset
    append page.data

    if length(page.data) == 0:
        stop

    if length(page.data) < limit:
        stop

    offset = offset + limit

12.2 Start at offset zero

For the newest page:

offset=0

12.3 Avoid massive tight loops

Do not download all available history repeatedly.

Prefer:

• a bounded date range;
• the granularity required by the visible chart;
• cached historical pages;
• incremental updates;
• pauses between large page requests.

12.4 Changing history

Offset pagination does not create an immutable snapshot.

If new candles appear while paging, positions can shift. Use bucket identity and timestamps to deduplicate safely.

---

13. Empty Candles and Gaps

13.1 Pair is not available

The requested token/quote pair might not be represented.

13.2 Quote is not supported

A token can have candles for one quote but not another.

Do not silently substitute a different quote.

13.3 No activity in a bucket

There may be no candle for an interval with no represented swaps.

The canonical endpoint leaves that interval absent. The chart endpoint can represent it with a synthetic carry-forward point after a prior real close exists.

13.4 Candle is not available yet

Recent activity can exist before the corresponding derived bucket becomes available.

13.5 Filters are too narrow

An exact scope or time range can return no rows.

13.6 Offset is beyond results

An offset beyond available history returns an empty array.

13.7 Data can be stale

The newest returned bucket can be older than expected.

13.8 UI recommendation

Prefer:

No candle data yet for this selection.

Do not display:

API broken.

unless the request actually failed.

---

14. Freshness and Chart UX

Candles are indexed and derived historical market data.

Recent swaps can appear later in candle history.

14.1 Not a real-time feed

Do not promise real-time candles unless future public documentation explicitly introduces that contract.

14.2 Freshness indicators

The response separates the selected page or historical range from the latest stored market row:

• returned_data_as_of_* describes the newest event returned in data;
• market_data_as_of_* describes the newest stored event for the same pair, scope, and granularity without range or offset filtering;
• market_last_trade_age_seconds and market_last_trade_stale apply only to that latest stored market event;
• market_last_trade_stale_after_seconds is one environment-configured last-trade threshold, independent of the requested candle granularity.

Therefore a historical range or non-zero offset can have an old returned_data_as_of_* without making current market activity stale. The default threshold is 120 seconds unless the environment configures another positive value. These fields measure the age of the latest stored trade represented by the requested market. They are not an indexer watermark or ingestion-health signal and do not prove that no newer upstream activity is pending.

14.3 Health boundary

A successful health response does not guarantee candle data freshness.

14.4 Chart states

Support distinct UI states:

• loading;
• loaded with data;
• loaded with no data;
• stale or last known;
• temporarily unavailable;
• authentication issue;
• rate limited.

14.5 Cached display

If a temporary request fails, a chart can show cached data with:

Last updated: <iso-utc-timestamp>

Do not label cached data as live.

---

15. Numeric Precision

OHLCV values can require high precision.

Illustrative response fields:

{
  "open_price": "0.000123456789",
  "high_price": "0.000125000001",
  "low_price": "0.000120000009",
  "close_price": "0.000124999999",
  "volume_token": "123456789.123456",
  "volume_quote": "15234.56789012"
}

Recommended handling:

• preserve strings where returned as strings;
• use arbitrary-precision decimal arithmetic;
• avoid unsafe float-only pipelines;
• retain original values for analytics;
• round only in the display layer;
• label token and quote units.

Warning: Binary floating-point conversion can alter small prices and large volumes.

15.1 Integer fields

Counts, Unix timestamps, and block heights can be JSON integers.

Do not assume every numeric-looking field uses the same JSON type.

---

16. Error Handling for Candles

Refer to the public errors and rate limits chapter for full retry and redaction guidance.

If a future response includes <request-id>, preserve it in safe diagnostics without assuming it is always present.

---

17. Chart Integration Tips

17.1 Cache historical candles

Past buckets usually do not need to be downloaded on every chart refresh.

Cache them in your backend and request only the recent range needed for updates.

17.2 Request the necessary granularity

Match granularity to the chart:

• short interval for detailed recent views;
• wider interval for long history.

Do not fetch every granularity when only one is visible.

17.3 Request the necessary range

Use from and to to bound history.

17.4 Use pagination safely

Use limit and offset, stop on empty or short pages, and avoid high-concurrency history downloads.

17.5 Debounce reloads

When users change token, quote, granularity, or date range:

• wait briefly before requesting;
• cancel obsolete requests;
• ignore responses for an older selection.

17.6 Handle gaps

Use canonical candles when the client needs only event-backed buckets. Use chart/token when the client needs the server-defined continuous presentation series. Synthetic chart points already contain zero activity and null chain evidence; do not reinterpret them as trades or persist them as canonical candles.

17.7 Show clear states

Display:

• loading;
• no candle data yet;
• stale data;
• temporary error;
• authentication issue;
• rate-limit wait.

17.8 Keep the key off the frontend

Recommended flow:

browser or mobile chart
    -> your backend
    -> Supra Core

The backend stores <api-key>, applies caching, and returns only required public data.

17.9 Preserve precision

Keep decimal-safe values through analytics and format them only at the final UI layer.

---

18. Common Mistakes

18.1 Assuming page_token exists

Use limit and offset.

18.2 Treating empty candles as an outage

An empty array can be a valid response.

18.3 Parsing every numeric field as a low-precision float

Preserve decimal strings.

18.4 Assuming local timezone

Parse Unix and UTC fields explicitly.

18.5 Assuming candles are real-time

They are derived historical data and can lag.

18.6 Mixing token and quote units

Check field names before aggregating or displaying volume.

18.7 Polling full history repeatedly

Cache stable history and request bounded updates.

18.8 Assuming health means candle freshness

Inspect the latest candle and event timestamps.

18.9 Exposing the API key in frontend chart code

Use a protected backend.

18.10 Reversing token and quote unintentionally

Pair orientation changes price meaning.

18.11 Treating synthetic chart points as trades

Synthetic chart points carry the previous close for presentation and contain no market event.

18.12 Rendering newest-first rows without reordering

Confirm the order required by the chart library.

---

19. Scope and Data Exposure

Clients can rely on the documented candle fields, bucket boundaries, timestamps, freshness semantics, pagination, and HTTP behavior. Candle generation and maintenance are outside the response contract.

---

20. Chapter Summary

GET /api/v1/candles returns bounded historical OHLCV rows for an exact token/quote pair, granularity, scope, and network.

Reliable clients should:

• authenticate with X-API-Key;
• use HTTPS and parse JSON defensively;
• provide exact <token-address> and <quote-token-address> values;
• use a supported <granularity>;
• apply optional Unix from and to bucket-start filters;
• paginate with limit and offset;
• not assume page_token;
• expect newest-first rows;
• understand open, high, low, close, and volume units;
• parse bucket and event timestamps explicitly;
• preserve decimal precision;
• handle empty arrays and missing buckets;
• avoid promising real-time behavior;
• display stale or last-updated context;
• cache historical data and avoid repeated full-history polling;
• keep <api-key> outside frontend and mobile code.

The candles endpoint provides public historical chart data. It is not a streaming, trading, wallet, or account management interface.