# Heatmap fetch (Node)

Fetches the liquidation heatmap of a coin (where tracked Hyperliquid positions would be liquidated, over time) and
prints the largest clusters above the mark (short liquidations) and below it (long liquidations). With `--csv` it also
writes the whole grid as long-form CSV (`time,price,long_usd,short_usd,mark`) for your own charts or backtests.

```bash
# from the repository root, once (until the SDK is on npm)
npx tsc -p sdk/typescript/tsconfig.json
cd examples/heatmap-fetch && npm install

export BLOCKMETRIC_API_KEY=bm_live_…
export BLOCKMETRIC_BASE_URL=https://<domain>/api/v1
node heatmap.mjs BTC --tf 15m --hours 24 --top 5
node heatmap.mjs ETH --tf 1h --hours 168 --csv eth-heatmap.csv
node heatmap.mjs BTC --tf 15m --hours 6 --end 2026-10-26T00:00:00Z   # an earlier window
```

| Option | Default | |
|---|---|---|
| `--tf` | `15m` | column interval: 1m · 5m · 15m · 1h · 4h · 12h · 1d (as your plan allows) |
| `--hours` | `24` | window; more than the interval's column cap answers `invalid_param` |
| `--end` | now | end of the window (ISO 8601) |
| `--top` | `5` | clusters per side |
| `--csv` | - | write the grid to this file |

Every key covers the heatmap of every coin: free keys the last 24 hours (15m and 1h), paid plans up to 1 or 3 years. Gap columns (no snapshot stored) are skipped
in the CSV. Not investment advice.