---
title: "Exchange Historical Candles"
method: GET
path: "/gateway/v1/exchange/candles"
tags: ["Exchange"]
---

# Exchange Historical Candles

`GET /gateway/v1/exchange/candles`

Returns persisted OHLCV candles for a covered Bithumb, Upbit, HashKey, bitFlyer, Coinone, or Korbit spot market.

**Intervals:** `5m`, `4h`, and `1w`. bitFlyer is currently reliable for weekly (`1w`) OHLCV only.

**Pagination:** use `from`/`to` to bound the time range and `limit` to cap returned candles. Results are ordered newest first.

**Synthetic candles:** `include_synthetic=true` by default, so carry-forward candles for no-trade intervals are included for continuous charts. Set `include_synthetic=false` for raw exchange-only candles. Sparse Korbit markets may rely on synthetic rows to keep charts continuous.

## Query parameters

- `exchange` 'bithumb' | 'upbit' | 'hashkey' | 'bitflyer' | 'coinone' | 'korbit', required — Exchange identifier
- `pair` string, required — Trading pair in base/quote form, e.g. BTC/KRW
- `interval` '5m' | '4h' | '1w' — Candle interval
- `from` string — Start of time range. Accepts Unix seconds or date string
- `to` string — End of time range. Accepts Unix seconds or date string
- `include_synthetic` boolean — Whether to include carry-forward candles for no-trade intervals. Defaults to true for continuous charts; set false for raw exchange-only candles.
- `limit` integer — Max number of candles to return. Weekly candles allow up to 300 rows for a 5-year chart; intraday intervals are capped at 100.
- `offset` integer — Pagination offset

## Response `200`

OK

- DataResponseExchangeCandleItem
  - `$schema` string, uri — A URL to the JSON Schema for this object.
  - `data` ExchangeCandleItem[], nullable, required
    - `close` number, double, required — Closing price
    - `close_time` integer, required — Candle close time in Unix seconds
    - `exchange` string, required — Exchange identifier
    - `high` number, double, required — Highest price during the interval
    - `interval` string, required — Candle interval
    - `is_synthetic` boolean, required — Whether this candle is a carry-forward row for a no-trade interval
    - `low` number, double, required — Lowest price during the interval
    - `open` number, double, required — Opening price
    - `pair` string, required — Trading pair like BTC/KRW
    - `region` string, required — Exchange market region
    - `timestamp` integer, required — Candle open time in Unix seconds
    - `trade_count` integer — Number of trades in the candle
    - `volume_base` number, double — Trading volume in base currency units
    - `volume_quote` number, double — Trading volume in quote currency units
  - `meta` OffsetMeta, required
    - `cached` boolean, required — Whether this response was served from cache
    - `credits_used` integer, required — Credits deducted for this request
    - `empty_reason` string — Hint explaining why the data array is empty, when applicable
    - `has_more` boolean — Whether more items may exist beyond this response. For offset-paged endpoints, continue with a larger offset. For time-series endpoints without offset/cursor controls, true means the requested time range hit an upstream cap; narrow from/to to continue. Omitted when exhaustion cannot be proven.
    - `limit` integer, required — Maximum number of items returned in this response
    - `offset` integer, required — Number of items skipped (pagination offset)
    - `total` integer — Total number of matching items (before pagination). Omitted when total is unknown.
    - `watermark` integer — Warehouse watermark (Unix seconds) this response was computed at, on warehouse-backed endpoints (e.g. Hyperliquid /trades/aggregate) — rows up to this time come from the warehouse, newer rows from the live tail. Omitted elsewhere.

## Other responses

- `default` — Error

---

[API](https://skmtc.dev/asksurf/apis/asksurf-public-rest-api.md) · [All operations](https://skmtc.dev/asksurf/apis/asksurf-public-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/asksurf/asksurf-public-rest-api/revisions/4153a9cb5145/schema)