Get Perp Chart
Fetch OHLC candles for a perpetual market from a supported DEX (Gains Network, Lighter), normalized to a single shape regardless of upstream.
Query Details
Returns OHLC candles for the requested market and period. Same param/response shape asGET /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 withh < lor 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.
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 indata is a candle:
{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:
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
traceIdincluded in every log line for that request.
Query Parameters
Upstream DEX to query.
gains, lighter 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).
Candle width.
1m, 5m, 15m, 30m, 1h, 4h, 1d, 1w Range start (inclusive). UNIX seconds, UNIX milliseconds, or ISO date string.
Range end (inclusive). Same unit handling as from. Must be greater than from.
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.