TradePortfolio
DocsEstimated Heatmap
Docs

Estimated Liquidation Heatmap

Dev

GET /liquidations/heatmap

Time-anchored inferred exposure history: hourly snapshots or coarser averages. The Pro chart uses the same calculation. Estimated exposure under assumed leverage, not a price prediction.

Authentication

Requires Dev or higher. Dev history is clamped to 30 days; Pro/Team can request older ranges where inputs remain available.

Parameters

Query parameters

NameTypeRequiredDescription
exchangestring✓Venue slug. Requires a candle adapter and usable market OI history.
symbolstring✓Base or native perpetual symbol, e.g. BTC or BTCUSDT. One instrument is selected.
startISO 8601 UTC✓Inclusive snapshot hour; rounded up to an hour.
endISO 8601 UTC✓Exclusive end capped at now. Maximum 720 hourly input scores per request, including when aggregated into coarser display columns.
intervalstring–1h (default): snapshots. 4h, 12h or 1d: UTC-aligned mean hourly exposure, not a sum. Columns include end_time, sample_count and as_of; incomplete input periods are omitted.
grouping_bpsinteger–25 (default), 50 or 100. Absolute logarithmic price grid; minimum 25 bps.

Tier behavior

  • Dev: 30-day history, clamped with a notice.
  • Pro / Team: Older snapshots where upstream candles and stored OI are available.

Example request

bash
curl -H "X-Api-Key: lk_live_your_key_here" \
  "https://api.loris.tools/liquidations/heatmap?exchange=binance&symbol=BTC&start=2026-10-20T00:00:00Z&end=2026-10-21T00:00:00Z&grouping_bps=25"

Example response

json
{
  "exchange": "binance",
  "symbol": "BTC",
  "model_version": "liq-heatmap-v1",
  "method": "estimated",
  "start": "2026-10-20T00:00:00Z",
  "end": "2026-10-21T00:00:00Z",
  "as_of": "2026-10-20T23:00:00Z",
  "price_source": "mark",
  "lookback_hours": 168,
  "grouping_bps": 25,
  "status": "ok",
  "columns": [
    {
      "time": "2026-10-20T23:00:00Z",
      "status_as_of": "2026-10-21T00:00:00Z",
      "reference_price": 80000,
      "oi_usd": 1000000000,
      "cells": [
        {
          "price_low": 76000,
          "price_high": 76190,
          "long_usd": 12000000,
          "short_usd": 0,
          "lifecycle": [
            {
              "status": "active",
              "at": null,
              "at_end": null,
              "long_usd": 12000000,
              "short_usd": 0,
              "ending_usd": 0
            }
          ]
        }
      ]
    }
  ],
  "gaps": [],
  "truncated": false,
  "notices": []
}

Errors

  • 400 — Invalid parameters or range.
  • 500 — Input service temporarily unavailable. Missing history instead returns a clear status and empty columns.

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

Related