API documentation

REST API for estimated liquidation data across crypto, metals, a stock index and FX. JSON over HTTPS. All responses are gzip-compressed.

Base URL

https://lqtserver.tail1e0dc4.ts.net

Authentication

Every /api/v1/* request needs an API key — either as a header or a query parameter:

# header (recommended)
curl -H "X-API-Key: YOUR_KEY" "https://lqtserver.tail1e0dc4.ts.net/api/v1/liquidations?symbol=BTCUSDT"

# query param (handy for the browser)
https://lqtserver.tail1e0dc4.ts.net/api/v1/liquidations?symbol=BTCUSDT&key=YOUR_KEY

Missing or wrong key → 401.

Rate limit

60 requests / minute per key (sliding window). Exceeding it returns 429. Data is cached and recomputed every ~45 s, so polling faster than that returns the same snapshot.

Errors

GET /api/v1/symbols

List the supported markets.

curl -H "X-API-Key: YOUR_KEY" "https://lqtserver.tail1e0dc4.ts.net/api/v1/symbols"

{
  "symbols": [
    { "symbol": "BTCUSDT", "label": "BTC" },
    { "symbol": "XAUUSDT", "label": "Gold" },
    { "symbol": "US100",   "label": "US100 (Nasdaq)" },
    { "symbol": "US500",   "label": "US500 (S&P 500)" },
    ...
  ]
}

GET /api/v1/liquidations

Current price plus the estimated liquidation amount ($) at every price level (full standing profile).

curl -H "X-API-Key: YOUR_KEY" "https://lqtserver.tail1e0dc4.ts.net/api/v1/liquidations?symbol=BTCUSDT&interval=60&limit=2000"

{
  "symbol": "BTCUSDT",
  "price": 63069.4,
  "total_usd": 49479897192,
  "levels": 165,
  "liquidations": [
    { "price": 56309.26, "usd": 660167190, "side": "long" },
    { "price": 62009.59, "usd": 1684064865, "side": "long" },
    { "price": 65284.25, "usd": 1120233105, "side": "short" }
  ],
  "updated": 1781900326807
}

• liquidations[] — every price level, sorted ascending by price.
• side — long = below price (support), short = above (resistance).
• usd — estimated liquidation notional at that level. total_usd = sum.
• updated — last refresh time, epoch milliseconds.

GET /api/v1/heatmap

The full time × price grid — every coordinate of the heatmap.

curl -H "X-API-Key: YOUR_KEY" "https://lqtserver.tail1e0dc4.ts.net/api/v1/heatmap?symbol=BTCUSDT&interval=60&limit=500"

{
  "symbol": "BTCUSDT", "interval": "60", "price": 63069.4,
  "pLow": 56187.97, "pHigh": 77897.76, "nrow": 180, "ncol": 500,
  "t0": 1779..., "t1": 1781...,
  "grid": [ [0,0,12,...180 values...], ... ncol columns ... ],
  "candles": [ [open, high, low, close, time_ms], ... ],
  "profile": [ { "price": ..., "usd": ..., "side": "..." }, ... ],
  "updated": 1781900326807
}

Decoding a cell grid[col][row] (density 0–100):

price(row) = pLow + (row + 0.5) / nrow * (pHigh - pLow)
time(col)  = t0 + (t1 - t0) * col / (ncol - 1)   // epoch ms
row 0 = lowest price (pLow), row nrow-1 = highest (pHigh)

Hyperliquid — real positions

Everything above is estimated from price and volume, because centralised venues don't publish positions. Hyperliquid is on-chain, so these endpoints return the actual position: real entry, real leverage, and the real liquidation price the exchange itself will use. Positions are aggregated across every Hyperliquid perp venue — the main dex plus builder-deployed ones such as xyz, which lists equities and commodities (GOLD, GOOGL, SILVER, CL). Reading only the main dex under-reports an active account by a double-digit percentage of its book.

GET /api/v1/hl/account

Full account state: equity, margin, PnL windows, positions, spot balances, open orders.

curl -H "X-API-Key: YOUR_KEY" "https://lqtserver.tail1e0dc4.ts.net/api/v1/hl/account?address=0x7fda...17d1"

{
  "address": "0x7fda...17d1", "updated": 1781900326807,
  "account": {
    "value": 17910000.0, "perp_value": 17840000.0, "spot_value": 43200.0,
    "notional": 85360000.0, "margin_used": 6674022.0,
    "free_margin": 8780000.0, "withdrawable": 8780000.0, "withdrawable_pct": 49.2,
    "leverage": 4.78, "positions": 36, "venues": ["main", "xyz"]
  },
  "pnl": { "all": 172560000.0, "day": -843000.0, "day2": -1710000.0,
           "week": -2280000.0, "month": -10610000.0,
           "vlm_month": 1106000000.0,
           "charts": {
             "total_pnl":     [[ts, value], ...],
             "perp_pnl":      [[ts, value], ...],
             "total_balance": [[ts, value], ...],
             "perp_balance":  [[ts, value], ...]
           },
           "series": [[ts, pnl], ...] },
  "positions": [ {
    "coin": "ETH", "venue": "main", "side": "short", "size": 22378.65,
    "notional": 42800000.0, "entry": 1858.03, "mark": 1911.45,
    "liq": 2512.10, "dist_pct": 31.4, "upnl": -1200000.0, "roe": -43.2,
    "leverage": 15.0, "margin": "cross", "funding": -1100000.0
  }, ... ],
  "spot":   [ { "coin": "KNTQ", "total": 377735.63, "mark": 0.0965,
                "value": 36467.0, "entry_ntl": 90882.23 }, ... ],
  "orders": [ { "coin": "BTC", "side": "sell", "px": 64716.0, "size": 0.0122,
                "orig_size": 0.0122, "type": "Limit", "reduce_only": false,
                "trigger": null, "ts": 1781900000000 }, ... ],
  "degraded": null
}

dist_pct is the signed % move that would liquidate the position — negative means price must fall (a long), positive means it must rise (a short). A null liq means the position can't be liquidated at any reachable price, which is normal for cross margin with collateral well beyond the position. degraded lists any sub-fetch that timed out; positions are never partial.

pnl.charts holds four time series, each [epoch_ms, value]: cumulative PnL and account balance, for the whole account and for the perpetual side alone. The gap between them is the spot contribution. pnl.series is an alias for charts.total_pnl, kept for compatibility — prefer charts in new code.

Spot balances are valued against USDC-quoted books that have 24h volume. Hyperliquid also lists many of the same assets against USDH, and those books are frequently dead — on 2026-08-07, UBTC/USDH marked 18.6% above the BTC perp on $0.00 of volume. A token whose only market is dead returns value: null rather than a stale figure.

GET /api/v1/hl/positions

Just the positions, optionally filtered to those near liquidation.

curl -H "X-API-Key: YOUR_KEY" "https://lqtserver.tail1e0dc4.ts.net/api/v1/hl/positions?address=0x7fda...17d1&near=10"

The cheap way to poll an address for real risk: near=10 returns only positions whose liquidation sits within 10% of mark. Positions with no reachable liquidation price are excluded when near is set.

GET /api/v1/hl/fills

Trade history, newest first. Params: address (required), limit (1–500, default 100), offset.

curl -H "X-API-Key: YOUR_KEY" "https://lqtserver.tail1e0dc4.ts.net/api/v1/hl/fills?address=0x7fda...17d1&limit=100"

{ "address": "0x7fda...17d1", "updated": ..., "total": 2000,
  "fills": [ { "coin": "ETH", "dir": "Close Short", "side": "buy",
               "px": 1906.1, "size": 0.0949, "pnl": -4.59,
               "fee": -0.0018, "ts": 1781900000000 }, ... ] }

GET /api/v1/hl/ledger

Deposits, withdrawals and transfers, newest first. Same params as fills.

curl -H "X-API-Key: YOUR_KEY" "https://lqtserver.tail1e0dc4.ts.net/api/v1/hl/ledger?address=0x7fda...17d1"

{ "address": "...", "updated": ..., "total": 1540,
  "entries": [ { "ts": ..., "kind": "deposit", "amount": 670000.0,
                 "token": null, "to": null, "hash": "0x..." }, ... ] }

kind is one of deposit, withdraw, send, spotTransfer, accountClassTransfer, vaultDeposit, spotGenesis.

GET /api/v1/hl/leaderboard

Largest Hyperliquid accounts by equity. Param: limit (1–200, default 50).

curl -H "X-API-Key: YOUR_KEY" "https://lqtserver.tail1e0dc4.ts.net/api/v1/hl/leaderboard?limit=50"

{ "updated": ..., "accounts": [
  { "address": "0xa822...d748", "name": null, "value": 13687878930.07,
    "pnl_day": 0.0, "pnl_week": 305319178.96, "pnl_month": 271240210.09,
    "roi_month": 2.02 }, ... ] }

Upstream window stats are sparse — a literal 0.0 PnL means “not reported” far more often than it means flat. Treat value as the reliable field.

Caching. Account state is cached 20s, trade history 30s, the ledger 2 minutes and the leaderboard 30 minutes. A cold leaderboard call can take several seconds; account lookups are typically well under a second.

History depth

The window is the most recent limit candles, so lookback = limit × interval.

• Crypto paginates to reach these depths; the futures‑backed markets (metals, Brent, the index futures, EUR/USD) cap at ~60 days for 5m/15m, ~2 years for 1h, decades for 1D.
• Newly‑listed instruments only go back to their listing date.

Supported symbols

Intervals

Notes

• All values are estimates derived from price/volume — not exchange liquidation prints.
• The index, oil, metal and FX markets use futures volume — the cash index and spot FX feeds print no size at all, and the engine weights every level by turnover, so a zero‑volume feed would return an empty map.
• Amounts are notional estimates; absolute $ for the futures‑backed markets isn’t directly comparable to crypto.