Skip to main content
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.
Timestamps accept seconds, milliseconds, or ISO date strings — milliseconds are auto-detected for numeric values above 1e12.

​
Query Parameters

​
dex
string
required
Upstream DEX to query. One of 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 USD-quoted perps (e.g., BTC/USD, SOL/USD, HYPE/USD).
  • Gains: crypto, forex, stocks, and commodities. Quote can be non-USD (e.g., USD/JPY, EUR/CHF).
A 404 is returned with example pair names when the market is not found for the chosen DEX.
​
period
string
default:"5m"
Candle width. One of 1m, 5m, 15m, 30m, 1h, 4h, 1d, 1w.
​
from
number | string
Range start (inclusive). UNIX seconds, UNIX milliseconds, or ISO date string.
​
to
number | string
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

​
data
array
OHLC candles sorted ascending by t. Duplicate timestamps and rows with h < l or non-finite values are dropped.

​
Examples

Lighter BTC/USD, 1-minute candles for the last hour: 
curl "https://api.mobula.io/api/2/perp/ohlcv-history?dex=lighter&market=BTC/USD&period=1m&from=1777035900&to=1777039500"
Gains USD/JPY, 5-minute candles, last 200 candles only: 
curl "https://api.mobula.io/api/2/perp/ohlcv-history?dex=gains&market=USD/JPY&period=5m&from=1777000000&to=1777039500&amount=200"
Response: 
{
  "data": [
    { "t": 1777035900, "o": 78328.9, "h": 78370.8, "l": 78328.9, "c": 78367.1 },
    { "t": 1777035960, "o": 78367.1, "h": 78388.6, "l": 78340.2, "c": 78380.0 }
  ]
}

​
Errors

StatusWhenmessage
400Zod validation failed (invalid dex, malformed market)zod validation failed
400from >= tofrom must be < to
400period not in supported setunsupported period "<period>"
404Market not found for the selected DEX (errors[0] lists example pairs)unknown market "<market>" for dex "<dex>"
502Upstream DEX returned an error (timeout, non-200, or code !== 200 for Lighter)upstream <dex> error
500Unexpected internal errorinternal server error

​
Notes

  • Candle shape matches spot OHLCV endpoints ({t, o, h, l, c}). Perp has no v field — volume is not reported by the upstream DEXes.
  • Empty result sets are not errors — data: [] with HTTP 200 is returned when the upstream has no data for the range.
  • 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.