Skip the Build: Cohort Alerts on Hyperliquid in 20 Lines of Code

Every week, another builder on Hyperliquid decides to build their own alert system from scratch. They want to know when smart money flips direction, when whales open new positions, or when the most profitable traders start accumulating a token nobody is watching yet. Reasonable goals. The execution plan, though, usually starts with "first, I'll classify every wallet on the exchange." That is where projects stall.

Wallet classification is the hard part. You need months of historical fills, a PnL engine that handles partial closes and liquidations correctly, an equity calculator that accounts for unrealized positions, and a way to keep all of it current as thousands of new trades hit the chain every minute. Most teams spend three to six months building and debugging the classification layer before writing a single line of alert logic. Some never finish.

There is a faster path. If the classification is already done for you, building a cohort alert system collapses from a multi-month infrastructure project to an afternoon of code. This article walks through exactly how to do it: pulling pre-computed cohort data from the HyperTracker API, writing threshold logic, and pushing alerts to Telegram or Discord. The working version is about 20 lines of Python.

Why wallet classification is the bottleneck

Before you can alert on what smart money is doing, you need to define "smart money." On Hyperliquid, that means computing the all-time PnL of every active wallet, bucketing wallets by cumulative performance and current size, and keeping those classifications accurate as new trades arrive in near-real-time.

Our data uses 16 behavioral cohorts. Eight are based on perp equity size: Shrimp ($0 to $250), Fish ($250 to $10K), Dolphin ($10K to $50K), Apex Predator ($50K to $100K), Small Whale ($100K to $500K), Whale ($500K to $1M), Tidal Whale ($1M to $5M), and Leviathan ($5M+). Eight more are based on all-time PnL: Money Printer (+$1M+), Smart Money (+$100K to +$1M), Consistent Grinder (+$10K to +$100K), Humble Earner ($0 to +$10K), Exit Liquidity (-$10K to $0), Semi-Rekt (-$100K to -$10K), Full Rekt (-$1M to -$100K), and Giga-Rekt (below -$1M).

Building this classification engine means ingesting every fill on Hyperliquid (going back months for historical accuracy), computing realized and unrealized PnL per wallet, tracking equity changes across position opens and closes, and reclassifying wallets as they cross thresholds. The compute is not trivial. A wallet that was a Consistent Grinder last week might cross $100K in cumulative PnL today and become Smart Money. Your system needs to catch that transition within minutes, which means recomputing classifications on every batch of new fills.

Most teams that attempt this from scratch find that the classification layer alone takes 300+ engineering hours and two to three months of tuning before it matches production accuracy. That is before you write a single alert.

The pre-computed shortcut

The HyperTracker API ships all 16 cohort classifications pre-computed. Every wallet on Hyperliquid is already classified, and the classifications update as new fills arrive. Instead of building the classification engine, you query a single endpoint and get cohort-level positioning, bias signals, and aggregate metrics for any segment you want to monitor.

The key endpoint for cohort alerts is /api/external/cohort/metrics. It returns aggregate positioning data for any cohort on any asset, including long percentage, short percentage, open interest, and the number of active wallets in that segment. Poll it on a schedule (the data refreshes every five minutes), compare the current snapshot to the previous one, and fire an alert when something crosses a threshold you care about.

Here is a minimal working example. This script checks whether the Money Printer cohort (all-time PnL above +$1M) has shifted its BTC positioning by more than a configurable threshold since the last check, and sends a Telegram message if it has:

import requests, os, json

API = "https://ht-api.coinmarketman.com/api/external"
TOKEN = os.environ["HT_API_KEY"]
TG_TOKEN = os.environ["TG_BOT_TOKEN"]
TG_CHAT = os.environ["TG_CHAT_ID"]
HEADERS = {"Authorization": f"Bearer {TOKEN}"}
THRESHOLD = 10  # percentage-point shift to trigger alert
STATE_FILE = "last_bias.json"

def get_bias():
    r = requests.get(f"{API}/cohort/metrics?coin=BTC&cohortId=8", headers=HEADERS)
    data = r.json()
    return data["longPercentage"]

def send_tg(msg):
    requests.post(f"https://api.telegram.org/bot{TG_TOKEN}/sendMessage",
                  json={"chat_id": TG_CHAT, "text": msg})

prev = json.load(open(STATE_FILE)) if os.path.exists(STATE_FILE) else {"bias": None}
current = get_bias()
if prev["bias"] is not None and abs(current - prev["bias"]) >= THRESHOLD:
    direction = "bullish" if current > prev["bias"] else "bearish"
    send_tg(f"Money Printer BTC shift: {prev['bias']:.0f}% -> {current:.0f}% long ({direction})")
json.dump({"bias": current}, open(STATE_FILE, "w"))

That is 20 lines. Schedule it with cron (every five minutes matches the API refresh rate) and you have a working cohort alert system. No infrastructure to maintain, no wallet classification to debug, no PnL engine to build.

Expanding beyond a single cohort

The minimal example monitors one cohort on one asset. A production alert system usually watches multiple cohorts across multiple tokens, because the interesting signals come from divergences between groups. When Money Printers are going long on ETH while Giga-Rekts are piling into the same direction, that is a very different signal than when Money Printers are long and Giga-Rekts are short.

To monitor multiple cohorts, loop over a configuration list. Each entry specifies a cohort ID, an asset, and a threshold:

WATCHLIST = [
    {"coin": "BTC", "cohortId": 8, "label": "Money Printer", "threshold": 10},
    {"coin": "BTC", "cohortId": 15, "label": "Giga-Rekt", "threshold": 15},
    {"coin": "ETH", "cohortId": 9, "label": "Smart Money", "threshold": 10},
    {"coin": "ETH", "cohortId": 12, "label": "Exit Liquidity", "threshold": 15},
    {"coin": "SOL", "cohortId": 8, "label": "Money Printer", "threshold": 12},
]

For each entry, pull the current cohort metrics, compare against the stored state, and fire the alert if the shift exceeds the threshold. The full script stays under 40 lines because the heavy lifting (classification, aggregation, PnL computation) happens on the API side.

Divergence alerts: the high-value signal

The most actionable alert is not "Smart Money went long." It is "Smart Money went long while the least profitable cohort went short on the same asset at the same time." That divergence between the top and bottom of the PnL distribution often precedes sharp moves, because it tells you that experienced traders are taking the opposite side of retail flow.

Building a divergence detector adds a few lines to the loop. After fetching metrics for both cohorts on the same asset, compare their long percentages. If one cohort is above a high-conviction threshold (say, a configurable percentage that fits your risk tolerance) and the other is below a low-conviction threshold, that is a divergence event worth alerting on.

# Divergence detection (add inside the polling loop)
mp_long = get_cohort_bias(coin="BTC", cohort_id=8)   # Money Printer
gr_long = get_cohort_bias(coin="BTC", cohort_id=15)  # Giga-Rekt

if mp_long > HIGH_CONVICTION and gr_long < LOW_CONVICTION:
    send_tg(f"DIVERGENCE: Money Printer {mp_long:.0f}% long, "
            f"Giga-Rekt {gr_long:.0f}% long on BTC. Smart money vs retail split.")

You can adjust the conviction thresholds to your own risk appetite. Some builders set them tight for more frequent alerts, others widen them to only catch extreme divergences. The data structure is the same either way.

Webhook delivery: when polling is not enough

Polling every five minutes works for most use cases, but some builders want push delivery. If you are on the Flow tier ($799/mo) or above, the HyperTracker API supports webhooks. Instead of your script asking "has anything changed?" on a schedule, the API pushes a payload to your endpoint when a condition is met.

Webhooks eliminate the polling loop entirely. You register a URL with the API, define the trigger conditions (cohort ID, asset, threshold), and the API fires a POST request to your server whenever the condition is met. Your server just needs to parse the payload and forward it to Telegram, Discord, or whatever notification channel you use.

For most builders starting out, polling on the Pulse tier ($179/mo, 50K requests per month) is more than enough. Checking 10 cohort/asset combinations every five minutes uses about 86,400 requests per month, which is well within the Pulse limit. Scale up to webhooks or WebSocket (Stream tier, $1,999/mo) when your alert system grows into a production trading signal service.

The DIY alternative and why it costs more than you think

For context, here is what building the same system from scratch looks like. You need five infrastructure layers: data ingestion (RPC node, WebSocket handlers, reconnect logic), wallet classification (PnL engine, equity tracker, cohort assignment), storage (time-series database, hot and cold tiers), an API layer (auth, rate limiting, documentation), and monitoring (uptime alerts, data quality checks, on-call rotation).

The engineering hours add up. Data ingestion is typically 200 hours. Wallet classification, the hardest layer, runs 300+ hours with months of tuning. Storage architecture is another 200 hours. The API layer adds 150. Monitoring is ongoing. Teams that attempt the full build routinely spend $10,000 or more per month in combined infrastructure, cloud compute, and engineering time.

Compare that to $179/mo on the Pulse tier. You skip all five layers, get 16 pre-computed cohorts with classifications that update every five minutes, and your entire "infrastructure" is a cron job running a 20-line Python script. The engineering time shifts from months of plumbing to an afternoon of alert logic.

Production hardening: from script to system

The 20-line script works as a proof of concept. Moving it to production means handling a few edge cases that do not show up until you have been running alerts for a week or two.

Deduplication

If your cron job restarts or overlaps, you might fire the same alert twice. Store a hash of each alert message (cohort + asset + direction + timestamp rounded to the nearest hour) and skip duplicates. A simple dictionary persisted to disk handles this.

Cooldown periods

Cohort bias can oscillate around a threshold, generating a flurry of alerts as it crosses back and forth. Add a cooldown: once an alert fires for a specific cohort/asset pair, suppress further alerts for that pair for a configurable window (30 minutes to a few hours, depending on your trading style).

Error handling

API calls fail. Networks drop. Telegram's API has rate limits of its own. Wrap your polling loop in a try/except, log failures, and use exponential backoff for retries. If the HyperTracker API returns a non-200 status, do not treat stale data as a signal. Skip the comparison and try again next cycle.

Multi-channel delivery

Telegram is the default for crypto alerts, but production systems often route to multiple channels: Telegram for mobile notifications, Discord for team channels, and a database for historical alert analysis. Structure your send function as a dispatcher that fans out to multiple backends based on alert severity.

Cohort IDs and what to watch

Here is the full reference for cohort IDs, so you can copy them directly into your configuration:

| Cohort | ID | Type | Range | | --- | --- | --- | --- | | Shrimp | 16 | Size | $0 to $250 equity | | Fish | 1 | Size | $250 to $10K | | Dolphin | 2 | Size | $10K to $50K | | Apex Predator | 3 | Size | $50K to $100K | | Small Whale | 4 | Size | $100K to $500K | | Whale | 5 | Size | $500K to $1M | | Tidal Whale | 6 | Size | $1M to $5M | | Leviathan | 7 | Size | $5M+ | | Money Printer | 8 | PnL | +$1M+ all-time | | Smart Money | 9 | PnL | +$100K to +$1M | | Consistent Grinder | 10 | PnL | +$10K to +$100K | | Humble Earner | 11 | PnL | $0 to +$10K | | Exit Liquidity | 12 | PnL | -$10K to $0 | | Semi-Rekt | 13 | PnL | -$100K to -$10K | | Full Rekt | 14 | PnL | -$1M to -$100K | | Giga-Rekt | 15 | PnL | Below -$1M |

For alert systems, the highest-signal cohorts are usually Money Printer (ID 8) and Smart Money (ID 9) on the long side, contrasted with Exit Liquidity (ID 12) and Giga-Rekt (ID 15) as the retail counterweight. Watching these four across BTC, ETH, and SOL gives you a broad picture of smart money versus retail positioning with just 12 API calls per cycle.

Start building cohort alerts today

The HyperTracker API gives you 16 pre-computed cohorts, position metrics, and order flow data. The Free tier includes 100 requests per day. Enough to prototype your alert system before upgrading to Pulse ($179/mo) for production polling.

Get your API key

Twenty lines is the starting line

The point of this article is not that 20 lines of code is the finished product. It is that 20 lines is where your alert system starts producing value, instead of being three months into a classification engine that still has edge cases. The HyperTracker API handles the part that takes the longest (classifying every wallet on Hyperliquid into 16 behavioral cohorts, keeping those classifications current, and serving aggregate metrics through a clean REST interface), so you can focus on what actually differentiates your system: the alert logic, the thresholds, the divergence patterns, and the trading decisions that follow.

Build the alert. Ship it to Telegram. Watch what the Money Printers are doing. Then decide if you need to go deeper.