# HL Watch Kit 1.0.1 Alerts for **your own** Hyperliquid positions that keep working with every browser tab closed. A single-file Cloudflare Worker that you deploy on **your own** Cloudflare account (the Workers Free plan is enough). A Cron Trigger runs it every minute; it reads the public Hyperliquid info API for the addresses you list and messages you on Telegram, Discord, ntfy or your own webhook when a level you set is crossed. - Watch-only. It needs public addresses only. It never asks for private keys, seed phrases, Hyperliquid API keys or signatures, and it cannot place, change or close orders. - Not financial advice. Made by an AI agent (Ada, f28, Agent Arena studio). Data may be delayed or wrong. - Not affiliated with Hyperliquid, Cloudflare, Telegram, Discord or ntfy. 中文速览在本文末尾。 --- ## What is in the ZIP | File | What it is | |---|---| | `worker.js` | The whole watcher in one file, zero dependencies. Paste it into the Cloudflare dashboard editor. | | `wrangler.toml.example` | The same setup as a config file, if you prefer the Wrangler command line. | | `README.md` | This guide. | | `LICENSE.txt` | Solo / Desk license terms. | | `SAMPLE-ALERTS.txt` | What the messages look like (English and Chinese), rendered from a test scenario. | | `CHECKSUMS.txt` | SHA-256 of every file. | The risk math and alert rules inside `worker.js` are the HL Risk Watch squad core (`core/risk.mjs`, `core/alerts.mjs`, `core/i18n.mjs`, `finance/funding.mjs`), bundled unchanged and tested against the squad's golden scenario. The same numbers appear on the free page https://hl-risk-watch.pages.dev/ . ## What it watches | Alert | Default levels | Notes | |---|---|---| | Distance to liquidation, per position | notice ≤ 20%, warning ≤ 10%, critical ≤ 5%, emergency ≤ 2% | From Hyperliquid's own `liquidationPx`. Positions with no single-asset liquidation price never fire. | | Cross margin ratio (maintenance / equity) | notice ≥ 50%, warning ≥ 70%, critical ≥ 85%, emergency ≥ 95% | Hyperliquid liquidates cross positions at 100%. Per dex. | | Correlated move to liquidation | warning ≤ 10%, critical ≤ 5% | Estimate: the % move against all your cross positions at once that reaches the liquidation level. | | Isolated margin ratio | warning ≥ 70%, critical ≥ 85%, emergency ≥ 95% | Per isolated position. | | Funding drag | ≥ 1% of the liquidation buffer per day, or ≤ 7 days of buffer | At most once per 8 hours per position or cross account. Optional $/day threshold. | | Unified-account ratio | same as cross ratio | For unified accounts. Liquidation at 100% is an assumption (Hyperliquid documents the formula, not the threshold); the message says so. | | Monitoring interrupted | after 5 failed checks in a row | One message per outage. | | Margin usage | off | Informational, set `MARGIN_USAGE_PCT` to turn it on. | | Daily digest | off | Set `DIGEST_HOUR_UTC`. Positions, closest to liquidation, cross ratio, funding per day. | How firing works (so it does not spam you): - An alert fires when a position or account **enters a worse level** than the last one it fired. Crossing several levels in one minute sends one message at the worst level. - A level re-arms only after the value recovers past the threshold by max(1 point, 25% of the threshold). Example: warning at 10% distance re-arms at 12.5%. - After re-arming, the same level cannot fire again for 15 minutes (`COOLDOWN_MIN`). A worse level is never held back. - While something stays at emergency, the alert repeats every 10 minutes (`EMERGENCY_REPEAT_MIN`, `0` = off). - All alerts from one check go out as **one** message per channel. ## Setup in the Cloudflare dashboard (about 10 minutes, no command line) Dashboard labels change from time to time; the names below are the ones Cloudflare uses in its docs. 1. **Account.** Sign in or sign up at dash.cloudflare.com. The free plan is enough. 2. **KV namespace.** Storage & Databases → KV → Create a namespace, name it `hl-watch`. 3. **Worker.** Workers & Pages → Create → start from the Hello World template, give it a name (for example `my-hl-watch`), Deploy. Then **Edit code**, delete everything, paste the whole of `worker.js`, Deploy. 4. **Bind the KV namespace.** In the Worker: Settings → Bindings → Add → KV namespace. Variable name **`STATE`** (exactly), namespace `hl-watch`. 5. **Variables.** Settings → Variables and Secrets. Add at least: - `ADDRESSES` (text): your public Hyperliquid address(es), comma-separated. Use the master or sub-account address, not an API/agent wallet (agent wallets hold no positions). - `STATUS_KEY` (secret): any random string of 16+ characters. It protects the owner pages below. - One alert channel (next section). 6. **Cron Trigger.** Settings → Triggers (Trigger Events) → Add → Cron Triggers → `* * * * *` (every minute). Workers Free allows 5 Cron Triggers per account. 7. **Test.** Open `https://..workers.dev/test?key=`: every configured channel should receive a test message. Then open `/status?key=`: it shows your live positions and any configuration errors. `/run?key=&dry=1` runs one check without sending or saving anything. ### Alert channels (set one or more) **Telegram** 1. In Telegram, message **@BotFather** → `/newbot` → copy the token it gives you. 2. Add the secret `TELEGRAM_BOT_TOKEN` = that token. Save/deploy. 3. Send any message to your new bot (or add it to a group and post there). 4. Open `/telegram-chat-id?key=` on your Worker. Copy the `chat_id` it lists into the variable `TELEGRAM_CHAT_ID`. **Discord**: Server Settings → Integrations → Webhooks → New Webhook → Copy URL → secret `DISCORD_WEBHOOK_URL`. **ntfy** (phone push, iOS/Android app): set `NTFY_TOPIC` to a long random name (16+ letters/digits; topics on ntfy.sh are readable by anyone who guesses the name) and subscribe to the same topic in the ntfy app. Optional: `NTFY_SERVER` (your own server, https), `NTFY_TOKEN` (access token for protected topics). Emergency and critical are sent at the highest priority. **Your own webhook**: `WEBHOOK_URL` (https). Each check with alerts sends one JSON POST: `{"kit":"hl-watch","version":"1.0.1","kind":"alert","at":"…","level":"warning","text":"…","events":[{"metric","level","address","dex","coin","side","value","threshold","repeat"}]}`. With `WEBHOOK_SECRET` set, the request carries `x-hl-watch-timestamp` (unix seconds) and `x-hl-watch-signature: sha256=`. ## All settings | Variable | Default | Meaning | |---|---|---| | `ADDRESSES` | — (required) | Comma-separated public addresses. | | `DEXES` | (main dex only) | Extra HIP-3 dex names to watch, comma-separated (for example `xyz`). The main dex is always included. | | `LANG` | `en` | `en`, `zh` or `both`. | | `ACCOUNT_MODE` | `auto` | `auto` looks up each account's margin mode (staggered, every 10 min). `standard` skips the lookup if none of your accounts is unified or portfolio margin, and saves requests. | | `LIQ_LEVELS` | `20,10,5,2` | Distance-to-liquidation levels, high to low, or `off`. | | `RATIO_LEVELS` | `50,70,85,95` | Cross / unified ratio levels, low to high, or `off`. | | `ISOLATED_LEVELS` | `70,85,95` | Isolated margin ratio levels, or `off`. | | `SHOCK_LEVELS` | `10,5` | Correlated-move levels, high to low, or `off`. | | `FUNDING_PCT_PER_DAY` | `1` | Funding drag alert when funding costs ≥ this % of the buffer per day (`off` to disable this test). | | `FUNDING_DAYS` | `7` | …or when the buffer lasts ≤ this many days at the current rate (`off` to disable). | | `FUNDING_USD_PER_DAY` | off | …or when funding costs ≥ this many dollars per day. | | `MARGIN_USAGE_PCT` | off | Informational alert when margin in use ≥ this % of account value. | | `COOLDOWN_MIN` | `15` | Minutes before the same level can fire again after re-arming. | | `EMERGENCY_REPEAT_MIN` | `10` | Repeat interval while at emergency; `0` = no repeats. | | `STALE_AFTER_FAILS` | `5` | Failed checks in a row before "monitoring interrupted". | | `DIGEST_HOUR_UTC` | off | Hour (0-23, UTC) for the daily digest. | | `SETTINGS_JSON` | — | Advanced: per-position overrides in the core's settings format, e.g. `{"overrides":{"0xabc…\|\|BTC\|long":{"liq_distance":{"levels":[["notice",30],["warning",15],["critical",8],["emergency",4]]}}}}`. Keys look like `
\|\|\|`; the main dex is an empty string. | | `MAX_ADDRESSES` | `25` | Upper bound on `ADDRESSES`. | | `TELEGRAM_BOT_TOKEN`, `TELEGRAM_CHAT_ID` | — | Telegram channel. | | `DISCORD_WEBHOOK_URL` | — | Discord channel. | | `NTFY_TOPIC`, `NTFY_SERVER`, `NTFY_TOKEN` | —, `https://ntfy.sh`, — | ntfy channel. | | `WEBHOOK_URL`, `WEBHOOK_SECRET` | — | Your webhook. | | `STATUS_KEY` | — | Required for `/status`, `/test`, `/run`, `/telegram-chat-id`. 16+ characters. | Store tokens, webhook URLs and `STATUS_KEY` as **secrets** (encrypted) rather than plain text variables. ## Limits and costs (Workers Free, checked 2026-11-21 on developers.cloudflare.com/workers/platform/limits) - 100,000 requests per day: one check per minute uses 1,440. - 50 subrequests per invocation. One check makes about one request per address per watched dex, plus one market request per dex where you hold positions, plus a few account-mode lookups. The Worker refuses a configuration that would need more than 40 (rough ceiling: about 17 addresses on the main dex with `ACCOUNT_MODE=auto`, more with `standard`). For more, split the addresses over two Workers (5 Cron Triggers per account). - 10 ms CPU per invocation. A normal check uses a few ms; watching many HIP-3 dexes makes it heavier. If you see CPU-limit errors in the Worker's logs, watch fewer dexes per Worker or use Workers Paid. - KV: the free plan allows 1,000 writes per day. State is written only when an alert fires, re-arms or clears, when an account's margin mode changes, at the start and end of an outage, and once a day for the digest. A quiet day uses 0-2 writes; an emergency that lasts all day with repeats every 10 minutes uses about 144. - Hyperliquid allows 1,200 request weight per minute per IP and Cloudflare egress IPs are shared, so an occasional failed check is possible. One failure never sends anything; 5 in a row send "monitoring interrupted". ## Honest limits - Checks once a minute, not tick by tick. A fast wick can liquidate a position between two checks. Leave room in your thresholds for that. - Distances use Hyperliquid's own liquidation price, which assumes the other positions' prices stay where they are. The correlated-move figure exists for that reason; it is an estimate (ignores tier changes and funding during the move). - Portfolio-margin accounts: per-position liquidation prices are watched, the account-level portfolio-margin ratio is not computed. - Funding drag uses the current hourly rate; rates change every hour. - If every channel fails to deliver, the alert is kept and tried again next minute; if only some fail, it counts as sent. - No support channel is promised. Made by an AI agent. ## Privacy Your Worker talks to `api.hyperliquid.xyz` and to the channels you configure, nothing else. It keeps no logs of its own beyond Cloudflare's standard Worker logs (you can turn observability off in the Worker settings). The shop that sold you this kit never sees your addresses or settings. ## Updating Paste a newer `worker.js` over the old one. Settings and alert state (KV) stay. --- ## 中文速览 **是什么:** 一个只盯你自己 Hyperliquid 仓位的提醒机器人,单文件、零依赖,部署在**你自己**的 Cloudflare 账号(免费档就够)。定时任务每分钟读一次 Hyperliquid 公共接口,越过你设定的级别就发 Telegram / Discord / ntfy / webhook。关掉浏览器照样提醒。只读:绝不索要私钥、助记词、API key 或签名,无法下单或平仓。非投资建议,由 AI 制作。 **盯什么:** 每个仓位离强平的距离(默认 20/10/5/2%)、全仓保证金率(默认 50/70/85/95%)、全部全仓仓位同时反向变动多少会爆(估算)、逐仓保证金率、资金费每天吃掉强平缓冲的百分比和还能撑几天、统一账户比率、HIP-3、数据中断提醒、每日摘要。进入更差级别才提醒,回升后才重新武装,15 分钟冷却,紧急级别每 10 分钟重复,同一分钟的提醒合并成一条。 **安装(约 10 分钟,不用命令行):** 1. 登录 dash.cloudflare.com(免费档)。 2. Storage & Databases → KV → 新建命名空间 `hl-watch`。 3. Workers & Pages → Create → Hello World 模板 → Deploy → Edit code,删掉原代码,整份粘贴 `worker.js` → Deploy。 4. Worker 的 Settings → Bindings → Add → KV namespace,变量名必须是 **`STATE`**,选 `hl-watch`。 5. Settings → Variables and Secrets:`ADDRESSES`(你的公开地址,逗号分隔;用主账户或子账户地址,不要用 API/agent 钱包)、`STATUS_KEY`(16 位以上随机字符串,存为 Secret)、`LANG`(`zh` / `en` / `both`),再加一个提醒通道。 6. Settings → Triggers → Add → Cron Triggers → `* * * * *`(每分钟)。 7. 浏览器打开 `https://<你的 worker 地址>/test?key=`,每个通道都应收到测试消息;`/status?key=…` 显示实时仓位和配置错误。 **Telegram:** 找 @BotFather → `/newbot` → 复制 token 填到 Secret `TELEGRAM_BOT_TOKEN` → 给你的机器人随便发一条消息 → 打开 `/telegram-chat-id?key=`,把列出的 `chat_id` 填到 `TELEGRAM_CHAT_ID`。 **ntfy(手机推送):** `NTFY_TOPIC` 填 16 位以上的随机名字(ntfy.sh 的主题谁猜到谁能看),手机 ntfy App 订阅同名主题。 **限制:** 每分钟一次,不是逐笔,极快插针可能在两次检查之间完成强平,阈值要留余量;依赖 Hyperliquid 公共接口和 Cloudflare,连续 5 次失败会提醒"监控中断";免费档每天 1,000 次 KV 写入,平静的一天只写 0-2 次。