Skip to main content
GET
Get perp OHLCV history

Query Details

Returns OHLC candles for the requested market and period. Same param/response shape as GET /2/market/ohlcv-history and GET /2/token/ohlcv-history, so a single client can render both spot and perp charts.
  • Market identifier is dex + market (perp has no pool address).
  • Market mappings are cached server-side for 5 minutes.
  • Candles are sorted ascending by t. Duplicate timestamps and rows with h < l or non-finite values are dropped.
  • Empty result sets are not errors — data: [] with HTTP 200 is returned when the upstream has no data for the range.
Timestamps accept seconds, milliseconds, or ISO date strings — milliseconds are auto-detected for numeric values above 1e12.
Note on Lighter: Only USD-quoted perps are supported (e.g., BTC/USD, SOL/USD, HYPE/USD).
Note on Gains: Crypto, forex, stocks, and commodities are supported. Quote can be non-USD (e.g., USD/JPY, EUR/CHF).

Query Parameters

Response

Each entry in data is a candle: Note: candle shape matches spot OHLCV endpoints ({t, o, h, l, c}). Perp has no v field — volume is not reported by the upstream DEXes.

Usage Examples

  • Lighter BTC/USD, 1-minute candles for the last hour:
  • Gains USD/JPY, 5-minute candles, last 200 candles only:
Response:

Errors

Notes

  • Market mappings (Gains pairs, Lighter orderBookDetails) are fetched lazily on first request per process and cached for 5 minutes.
  • Upstream requests have a 10s timeout.
  • Each request is traced server-side with a short traceId included in every log line for that request.

Query Parameters

dex
enum<string>
required

Upstream DEX to query.

Available options:
gains,
lighter
market
string
required

Human-readable pair in BASE/QUOTE format (e.g., BTC/USD, ETH/USD, USD/JPY). Case-insensitive — internally uppercased. Lighter only supports USD-quoted perps; Gains supports crypto, forex, stocks and commodities (quote may be non-USD).

period
enum<string>

Candle width.

Available options:
1m,
5m,
15m,
30m,
1h,
4h,
1d,
1w
from

Range start (inclusive). UNIX seconds, UNIX milliseconds, or ISO date string.

to

Range end (inclusive). Same unit handling as from. Must be greater than from.

amount
number

Max number of candles to return (capped at 2000). When the range yields more candles than amount, only the most recent amount are returned.

Response

Perp OHLCV history response. Candles sorted ascending by t. Duplicate timestamps and rows with h < l or non-finite values are dropped. Empty result sets are not errors — data: [] with HTTP 200 is returned when the upstream has no data for the range.

data
object[]
required