TradePortfolio
DocsDepth Band History
Docs

Depth Band History

Dev

GET /orderbook/depth-history

Returns a historical timeseries of cumulative resting bid and ask liquidity within a configurable basis-point band around each sampled snapshot's mid price. The endpoint samples one stored snapshot per requested resolution bucket, then sums bid and ask depth both in base-size units and USD notional.

Authentication

Requires Dev tier or higher. Dev receives a rolling 30-day lookback; Pro and Team receive full stored history. This endpoint is categorized as historical for rate limiting: Dev receives 30 requests per minute, while Pro and Team receive 100 requests per minute.

Parameters

Query parameters

NameTypeRequiredDescription
exchangestring✓Single exchange slug. Supported depth venues include binance, bybit, okx, hyperliquid, lighter, coinbase, kalshi, and extended.
symbolstring✓Single canonical or venue-native symbol. Symbols are normalized to uppercase unless they use a HIP-3 prefix such as xyz:BTC.
startstring (ISO 8601)✓Start timestamp for the requested window.
endstring (ISO 8601)✓End timestamp for the requested window. Must be after start.
resolutionstring–native, 1m, 5m, 15m, 30m, 1h, 4h, or 1d. Defaults to 1m. native is treated as 1m.
band_bpsnumber–Basis-point distance from mid to include on each side. Defaults to 500, minimum 1, maximum 5000.

Tier behavior

  • Pro: Rolling 30-day historical lookback for one exchange and symbol.
  • Team: Same endpoint behavior and historical rate-limit bucket as Pro.

Example request

bash
curl -H "X-Api-Key: lk_live_your_key_here" \
  "https://api.loris.tools/orderbook/depth-history?exchange=binance&symbol=BTC&start=2026-07-30T00:00:00Z&end=2026-07-30T01:00:00Z&resolution=5m&band_bps=500"

Example response

json
{
  "exchange": "binance",
  "symbol": "BTC",
  "canonical_symbol": "BTC",
  "start": "2026-07-30T00:00:00.000Z",
  "end": "2026-07-30T01:00:00.000Z",
  "resolution": "5m",
  "band_bps": 500.0,
  "points": [
    {
      "ts": "2026-07-30T00:00:00.123Z",
      "mid": 67249.75,
      "bid_depth_size": 13758.4,
      "ask_depth_size": 10787.1,
      "bid_depth_usd": 125000.5,
      "ask_depth_usd": 98000.25
    }
  ]
}

Errors

  • 400 — Missing required parameter, invalid timestamp, unsupported resolution, end before start, or invalid band_bps.
  • 500 — ClickHouse is unavailable or the depth history query failed.

For authentication errors (401) and rate limit responses (429), see Errors.

Related