Skip to main content
GET
/
2
/
perp
/
ohlcv-history
Get perp OHLCV history
curl --request GET \
  --url https://demo-api.mobula.io/api/2/perp/ohlcv-history
{
  "data": [
    {
      "t": 123,
      "o": 123,
      "h": 123,
      "l": 123,
      "c": 123
    }
  ]
}
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.

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