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
    }
  ]
}

Documentation Index

Fetch the complete documentation index at: https://docs.mobula.io/llms.txt

Use this file to discover all available pages before exploring further.

​
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

ParameterTypeRequiredDescription
dexstringYesUpstream DEX to query. One of gains, lighter.
marketstringYesPair in BASE/QUOTE format (e.g., BTC/USD, USD/JPY). Case-insensitive.
periodstringNoCandle width. One of 1m, 5m, 15m, 30m, 1h, 4h, 1d, 1w. Default 5m.
fromnumber | stringNoRange start (inclusive). UNIX seconds, UNIX milliseconds, or ISO date string.
tonumber | stringNoRange end (inclusive). Same unit handling as from. Must be greater than from.
amountnumberNoMax 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:
FieldTypeDescription
tnumberUNIX seconds.
onumberOpening price.
hnumberHighest price in the interval.
lnumberLowest price in the interval.
cnumberClosing 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

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

  • 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