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.

GET /2/perp/ohlcv-history

Get perp OHLCV history

cURL

curl --request GET \
  --url https://demo-api.mobula.io/api/2/perp/ohlcv-history

200

{
  "data": [
    {
      "t": 123,
      "o": 123,
      "h": 123,
      "l": 123,
      "c": 123
    }
  ]
}

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

Parameter	Type	Required	Description
dex	string	Yes	Upstream DEX to query. One of gains, lighter.
market	string	Yes	Pair in BASE/QUOTE format (e.g., BTC/USD, USD/JPY). Case-insensitive.
period	string	No	Candle width. One of 1m, 5m, 15m, 30m, 1h, 4h, 1d, 1w. Default 5m.
from	number | string	No	Range start (inclusive). UNIX seconds, UNIX milliseconds, or ISO date string.
to	number | string	No	Range end (inclusive). Same unit handling as from. Must be greater than from.
amount	number	No	Max candles to return (capped at 2000). When range yields more than amount, the most recent are kept.

Response

Each entry in data is a candle:

Field	Type	Description
t	number	UNIX seconds.
o	number	Opening price.
h	number	Highest price in the interval.
l	number	Lowest price in the interval.
c	number	Closing price.

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:

curl -X GET "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 -X GET "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

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

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 · 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

200

application/json

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

Show child attributes