# Liquidation alert bot (Node)

Alerts on big liquidations and liquidation cascades as they happen, and warns once per cluster when the price comes
close to a large liquidation cluster of the heatmap (built from real tracked Hyperliquid positions). Alerts go to the
console and, optionally, to any JSON webhook (`ALERT_WEBHOOK_URL`, e.g. a Slack incoming webhook).

How events arrive depends on your plan. The same bot covers all three:

| `BOT_MODE` | Plan | How |
|---|---|---|
| `stream` | API Pro | live stream `GET /api/v1/stream`, reconnects with `Last-Event-ID` |
| `webhook` | API Dev, API Pro | signed webhooks pushed to this process; verifies `Blockmetric-Signature` |
| `poll` | every key | `client.follow('liquidations', …)`: new liquidations ≥ `BOT_MIN_USD` |
| `auto` (default) | | `stream`, falling back to `poll` without API Pro |

## Run

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

export BLOCKMETRIC_API_KEY=bm_live_…                    # create one on /account/api
export BLOCKMETRIC_BASE_URL=https://<domain>/api/v1
node bot.mjs                                            # auto: stream or poll

# webhooks (API Dev / API Pro): add an endpoint on /account/api pointing at https://<your host>/hook
BOT_MODE=webhook BLOCKMETRIC_WEBHOOK_SECRET=whsec_… PORT=3000 node bot.mjs
# local test without a public URL: npx blockmetric listen --forward-to http://localhost:3000/hook
```

| Variable | Default | |
|---|---|---|
| `BOT_COINS` | `BTC,ETH` | coins to watch (events and heatmap clusters) |
| `BOT_KINDS` | `big_liquidation,liq_cascade,whale_liquidated` | radar event kinds (stream / webhook) |
| `BOT_MIN_SEVERITY` | `2` | 1 info … 4 critical (stream / webhook) |
| `BOT_MIN_USD` | `250000` | smallest single liquidation to alert on (poll) |
| `BOT_CLUSTER_MIN_USD` | `5000000` | smallest heatmap cluster to warn about |
| `BOT_CLUSTER_DISTANCE` | `0.01` | warn when the mark is within this fraction of a cluster (0.01 = 1 %) |
| `BOT_CLUSTER_MINUTES` | `5` | how often to check the heatmap; `0` turns the cluster check off |
| `POLL_SECONDS` | `15` | polling interval (mind your per-minute limit) |
| `ALERT_WEBHOOK_URL` | - | POSTs `{"text": …, "content": …}` for every alert |
| `BOT_EXIT_AFTER` | `0` | stop after this many alerts (demos, tests); `0` = run until Ctrl+C |

Each alert is sent once (webhook deliveries are at-least-once and deduplicated on the event id). Which venues appear
depends on the data licence of the API (`meta.sources`); a cluster comes from the newest 15-minute heatmap column.
Keep the attribution when you show the data to others (`meta.attribution`). Not investment advice.

`bot.mjs` exports `run`, `config`, `nearClusters` and the formatters, so you can reuse them in your own code.