Hyperliquid Tracker: a Telegram bot for large Hyperliquid trades

The gap Hyperliquid Tracker fills: alerting, not analysis

Hyperliquid publishes a public trade stream. Reading it continuously is easy; deciding which of the thousands of prints matter to you is the tedious part. Hyperliquid Tracker is a small process that sits on that stream and forwards only trades above a size you set, into a Telegram channel you control. The audience is narrow: someone who already watches a handful of coins and wants a phone notification when a large print happens, without keeping a browser tab open.

The README is explicit about scope. It says the bot "monitors Hyperliquid trades and sends notifications to a Telegram channel when significant trades occur." There is no alerting UI, no per-user subscriptions, no history. One process, one channel, one threshold. If you want to query past flows or rank wallets, this is not the tool, and the README does not pretend otherwise.

How the trade stream becomes a Telegram message

The dependency list tells most of the story. @nktkas/hyperliquid is the Hyperliquid client, ws handles the socket, telegraf sends messages, and p-limit caps how many operations run at once. The package.json declares "type": "commonjs" and a build step that runs tsc into dist/index.js, so the runtime artifact is plain Node, not a bundler output.

The flow is a pipeline with three stages: subscribe to trade events, filter each event against SUPPORTED_COINS and MIN_NOTIONAL_VALUE, then hand the survivors to Telegraf for delivery. p-limit is the interesting inclusion. It suggests the author expected bursts of qualifying trades and wanted a ceiling on concurrent work rather than firing an unbounded number of sends. The README also lists "Automatic reconnection on connection loss," so the socket layer is expected to drop and recover without a manual restart.

What the README does not describe is the retry policy, the backoff curve, or what happens to trades that arrive while Telegram is rate limiting the bot. Those are the parts that decide whether the feed is trustworthy under load, and they are not documented.

Installing Hyperliquid Tracker and getting a first alert

Node.js 22.4.0 or higher is required, and the repository pins that floor in the engines field of package.json, so npm will warn on older runtimes. Clone the repository and install:

git clone https://github.com/gabriel-azara/hyperliquid-tracker
cd hyperliquid-tracker
npm install
npm run build

Before starting, create a Telegram bot. The README routes you through @BotFather with the /newbot command and tells you to save the API token it returns. Then create the channel that will receive alerts, add the bot as an administrator, and forward any message from that channel to @userinfobot to read the chat ID, which looks like -100xxxxxxxxxx.

Put both values in a .env file at the project root, copying the shape from .env.example:

TELEGRAM_BOT_TOKEN=your_bot_token_here
TELEGRAM_CHAT_ID=your_chat_id_here

Start the process with npm start, or npm run dev for the ts-node path. Once it is running, the README says a health check endpoint is available on port 3000 at the root path:

http://localhost:3000/

Hitting that URL should return the health response, which is the quickest way to confirm the process is alive before you wait for a trade large enough to trigger a message.

The threshold lives in TypeScript, not in .env

This is the design decision most likely to annoy you. .env.example contains exactly two keys, TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID. The values that actually shape what you receive, SUPPORTED_COINS and MIN_NOTIONAL_VALUE, are read from src/config/index.ts. The README states the default threshold is 1,000,000.

That means changing which coins you watch, or lowering the threshold to catch smaller prints, requires editing a TypeScript file and rebuilding with npm run build before restarting. On a platform like Railway, where the repository includes a railway.json, that is a redeploy rather than a config change. For a single-operator bot this is fine. For anything where a non-developer is expected to tune the feed, it is the wrong shape, and the README offers no environment-variable override.

There is a second consequence. Because the coin list is compiled in, adding a market means a code change and a fresh deploy, and there is no documented validation that the symbols you add are ones the exchange actually streams. A typo produces a silent gap in coverage rather than an error, as far as the README describes.

Where it breaks: delivery, silence, and the wrong use case

The troubleshooting section is the most honest part of the README. Its first entry, "Bot not sending messages," lists three causes: a wrong token or chat ID, the bot not being an administrator in the channel, and missing permission to send messages. All three are configuration faults that produce the same symptom, an apparently healthy process that never posts. Nothing in the README describes a startup check that fails loudly when Telegram rejects the credentials, so the health endpoint on port 3000 can return a good response while alerts go nowhere.

The second failure mode is silence by design. A threshold of 1,000,000 notional means quiet markets produce no messages at all, and there is no heartbeat or daily digest documented to distinguish "no large trades" from "the socket died and reconnection is failing." The README claims automatic reconnection but does not say how many attempts it makes or whether it gives up.

Finally, this is the wrong tool for anything multi-user. There is one chat ID per deployment. If five people want different thresholds or different coin lists, you run five processes with five bots, which also means five connections to the same public stream. The README does not discuss sharing a single subscriber across recipients.

Alternatives: a general Telegram alerting bot versus a dedicated one

The obvious alternative is a general-purpose notification bot such as a Telegram integration for an alerting platform, where you write the condition yourself and point it at a data source. The difference is where the logic lives. Hyperliquid Tracker ships the Hyperliquid subscription, the notional filter and the Telegram sender as one opinionated pipeline, so you install it and it works. A general alerting tool gives you the transport and the scheduling but not the Hyperliquid trade semantics, so you own the parsing of trade events and the definition of notional value.

That trade-off cuts both ways. The dedicated bot is faster to stand up and harder to extend, because the filter is compiled into src/config/index.ts. The general tool is slower to stand up and easier to extend, because conditions are configuration rather than code. If your requirement is exactly "tell me about trades above X on these coins," the dedicated bot wins on setup time. If your requirement is "tell me when a specific wallet's position changes," neither the README nor the configuration surface suggests this project supports it, and you would be building on a general tool from the start.

Maintenance cost, licence, and what the repository does not say

The last push to the repository was on 2026-07-21, and the repository is not archived. That is roughly two months before the date of writing, so the project is recent but there is no release history to inspect: no releases were retrieved, and the only version signal is 1.0.3 in package.json. Upgrade cost is dominated by the Hyperliquid client, @nktkas/hyperliquid at ^0.17.3. A caret range on a 0.x dependency means minor bumps are allowed, and 0.x libraries are where breaking changes tend to land. If the trade event shape changes, the filter in src/config/index.ts and the formatting before the Telegraf send are the code you will be fixing.

On licensing, package.json declares "MIT" in its license field, while the repository's top-level entries list no LICENSE file. The description in package.json also carries the note "Not affiliated with Hyperliquid." Anyone depending on the MIT grant should confirm which file actually carries the terms, since a package.json field and a licence file are not the same artifact. This is a factual gap, not legal advice.

The README also does not document rollback, log retention, or how to run more than one instance against the same Telegram channel without duplicate messages. Those are the questions to raise in an issue before you depend on the feed.

Editorial conclusion

Adopt it if you want a single-operator Telegram feed of large Hyperliquid trades and you are comfortable editing src/config/index.ts to change the coin list or the 1,000,000 notional threshold. Skip it if you need per-user alerts, historical queries, or a dashboard: the README describes a bot process and a health endpoint on port 3000, nothing more. Before deploying, verify Node is at least 22.4.0, confirm the bot is an administrator in the target channel, and check the package.json licence field against the repository, which lists no licence file at the top level.

Frequently asked questions

Official sources

1. 0xhype/hyperliquid-tracker on GitHub
2. Issues
3. README