# Telegram alert bot

Posts Blockmetric radar events to a Telegram chat: big liquidations, liquidation cascades, whales liquidated or close to
liquidation (configurable). With an API Pro key it uses the live stream (`GET /api/v1/stream`, reconnects with
`Last-Event-ID`); with other keys it polls `GET /api/v1/radar/events`.

## Setup

1. Create a bot with [@BotFather](https://t.me/BotFather) and copy the token.
2. Add the bot to your channel or group (as admin for channels) and find the chat id (e.g. send a message and read
   `https://api.telegram.org/bot<token>/getUpdates`).
3. Create an API key on `/account/api`.

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

export BLOCKMETRIC_API_KEY=bm_live_…
export BLOCKMETRIC_BASE_URL=https://<domain>/api/v1
export TELEGRAM_BOT_TOKEN=123456:ABC…
export TELEGRAM_CHAT_ID=-1001234567890
node bot.mjs
```

| Variable | Default | |
|---|---|---|
| `BLOCKMETRIC_KINDS` | `big_liquidation,liq_cascade,whale_liquidated,whale_near_liq` | event kinds, comma-separated |
| `BLOCKMETRIC_MIN_SEVERITY` | `2` | 1 info … 4 critical |
| `POLL_SECONDS` | `20` | polling interval without API Pro |
| `TELEGRAM_API_BASE` | `https://api.telegram.org` | only for tests against a local fake |

The bot sends at most one message per second and honours Telegram's flood control (`429` + `retry_after`).
Messages end with "Data: Blockmetric (public sources). Not investment advice." Keep the attribution when you
redistribute data (commercial use needs API Pro).