Hyperliquid Analytics API: Smart Money and Cohort Data Explained

Open interest on Hyperliquid just jumped $500 million in an hour. BTC is grinding sideways. You want to know whether that was a whale loading up for a directional move or 50,000 retail traders piling into the same crowded trade. The aggregate number is identical in both cases. The trade thesis is completely different.

Raw exchange data cannot answer that question. You need a layer on top of it that tells you who is positioned, how profitable they have been historically, and whether the smart money is aligned with or diverging from the rest of the market. This is what behavioral cohort analytics solves, and Hyperliquid's fully transparent onchain infrastructure makes it more tractable here than on any centralized exchange. This guide walks through how the data works, how to query it, and a concrete worked example for detecting smart money divergence using Python. HyperTracker is the API we will use for the examples, but the concepts apply no matter what tool you reach for.

Why Cohort Data Changes How You Read Hyperliquid

A behavioral cohort is a segment of wallets grouped by shared characteristics, usually position size and historical profitability. Instead of labeling specific addresses as whales or smart money, every wallet on the exchange gets classified into a bucket, and you work with the aggregate metrics for each bucket. It is the difference between following three famous traders and watching the entire market stratified by skill.

Aggregate open interest tells you nothing about who is positioned. A $500 million long increase looks identical on the chart whether it came from one wallet or fifty thousand. For your trade thesis and risk management, the difference matters enormously. If that long increase came entirely from the most profitable cohort, you have conviction from participants who have been right more often than wrong. If it came from the least profitable cohort, you have a crowded retail trade that historically precedes a reversal.

The real power shows up when you compare cohorts against each other. If the top PnL cohort is adding to longs while the bottom PnL cohort is capitulating shorts, both sides of the market agree and you have a confluence signal. If the top PnL cohort is long while the bottom PnL cohort is also heavily long, you have a crowded trade that is vulnerable to a squeeze. Same aggregate number, two very different setups.

Cohort divergence is the cleanest read on Hyperliquid. When elite traders and retail disagree, the historically profitable side is the one worth weighing more heavily. When they agree on the same direction, everyone is already in the boat and the edge is gone.

The Data You Need

Three pieces of data power this kind of analysis. Each one answers a different question, and you want all three to form a complete picture.

Cohort classification. Every wallet on Hyperliquid gets labeled by size and all-time profitability. This requires enough historical fill data to establish a PnL track record for each address, which is why you cannot bolt this on top of raw live data without a backfill. HyperTracker runs 16 cohorts: 8 segmented by position size (from smallest to largest) and 8 by all-time PnL (from consistent losers to top performers). Classification runs continuously as wallets accumulate more history.

Positioning data. For each cohort, you need current aggregate long notional, short notional, and wallet count. This tells you how the segment is currently allocated and how many participants are behind that allocation. Our data refreshes every 5 minutes from raw Hyperliquid state.

Directional bias. Aggregate positioning at a single point in time is a snapshot. Directional bias over a rolling window tells you whether the cohort is shifting and in which direction. A 12-hour rolling net positioning metric captures meaningful shifts without being too noisy for short-term scalping noise.

All of this comes from raw Hyperliquid data: fills, positions, account state. You can build it yourself if you want to operate the ingestion pipeline, classify every wallet, and keep rolling metrics current. The engineering is doable, the ongoing cost is not trivial. For most teams it is faster to query an API that has already done the work and spend your time on the strategy layer instead of the infrastructure layer.

A Worked Example: Detecting Smart Money Divergence

Let's make this concrete. The scenario: BTC perps on Hyperliquid have been ranging for several hours. You want to know if smart money is positioning ahead of a move before you commit capital. Here is how you would read that using the cohort endpoints.

Step 1: Query cohort metrics for BTC

Start with a single call to /cohort/metrics, passing the coin you care about. The response comes back with aggregate positioning for every cohort segment.

import requests

API_BASE = "https://ht-api.coinmarketman.com/api/external"
headers = {"Authorization": "Bearer YOUR_JWT_TOKEN"}

# Get positioning for all cohorts on BTC
response = requests.get(
    f"{API_BASE}/cohort/metrics",
    headers=headers,
    params={"coin": "BTC"}
)
cohorts = response.json()

Step 2: Isolate the top vs bottom PnL cohorts

Pull out the two ends of the profitability spectrum: the segment of wallets with the best all-time PnL and the segment with the worst. These are your smart money and retail benchmarks.

# Top profitability segment (elite traders)
top_pnl = [c for c in cohorts if c['segmentId'] == 'pnl_top'][0]
# Bottom profitability segment (consistent losers)
bottom_pnl = [c for c in cohorts if c['segmentId'] == 'pnl_bottom'][0]

top_long_ratio = top_pnl['longNotional'] / top_pnl['totalNotional']
bottom_long_ratio = bottom_pnl['longNotional'] / bottom_pnl['totalNotional']

Each ratio is a number between 0 and 1. A value of 0.7 means 70% of that cohort's notional exposure is long. A value of 0.3 means they are 70% short.

Step 3: Check for divergence

Subtract the bottom cohort's long ratio from the top cohort's long ratio. A large positive number means elite traders are long while retail is short, a classic bullish confluence. A large negative number means elite traders are short while retail is long, which historically warns of downside.

# If elite traders are majority long and losing traders are majority short,
# that's a bullish divergence. If it's the opposite, that's a warning.
divergence = top_long_ratio - bottom_long_ratio

if divergence > 0.3:
    print(f"Bullish divergence: elite {top_long_ratio:.0%} long vs retail {bottom_long_ratio:.0%} long")
elif divergence < -0.3:
    print(f"Bearish divergence: elite {top_long_ratio:.0%} long vs retail {bottom_long_ratio:.0%} long")
else:
    print("No significant divergence, cohorts aligned")

The 0.3 threshold is a starting point, not gospel. Tune it based on your timeframe and risk tolerance. A tighter threshold gives you more signals but more noise. A wider threshold gives you fewer, higher-confidence reads.

Step 4: Confirm with 12-hour bias trend

A single snapshot is a starting point. Confirm it by checking the /cohort/bias endpoint, which returns the rolling 12-hour directional bias for each cohort. If the divergence you just spotted is new, it might be noise. If it has been persistent for the last several hours, it is a stronger read.

bias_response = requests.get(
    f"{API_BASE}/cohort/bias",
    headers=headers,
    params={"coin": "BTC"}
)
bias = bias_response.json()

# Look for cohorts that have been persistently biased in one direction
for segment in bias:
    if segment['segmentId'] in ('pnl_top', 'pnl_bottom'):
        print(f"{segment['segmentId']}: {segment['netBias']:+.2f} (12h rolling)")

When the top PnL cohort has been holding a positive bias for hours and the bottom cohort has been holding a negative bias, that is a setup worth paying attention to. When the bias is fresh and everything flipped in the last 15 minutes, wait for another data point.

Reading Order Flow Alongside Cohorts

Cohorts tell you who is positioned. Order flow tells you what they are doing right now. Combine the two and you get a much richer picture of the market state than either one alone.

The /orders/5m-snapshots endpoint returns rolling 5-minute windows of active orders on Hyperliquid, with stop and take-profit visibility. You can see where resting orders cluster at specific price levels, which levels have the heaviest concentration, and how that clustering shifts over time. This is not a real-time orderbook stream, it is periodic snapshots, and that is the right cadence for this kind of analysis.

A simple interpretation framework:

• Heavy stops from retail at a level: more likely to cascade when breached, because retail stops tend to cluster at obvious round numbers and technical levels. Breaking those levels triggers a chain of forced selling.
• Heavy take-profits from profitable wallets at a level: expect supply as price approaches. If the elite cohort is placing TPs at $72k on BTC, price is going to meet resistance there from their exits.
• Thin order book from both cohorts in a zone: a vacuum. Price can move through that range fast because there is nothing in the way. These zones often show up between obvious technical levels and can produce the quickest moves of the day.

The framework is not a crystal ball. It gives you context for levels you were already watching, and it helps you prioritize which levels are worth paying attention to before they hit.

Real Limitations (Be Honest)

Every framework has edges where it breaks down. If you are going to trade on this data, you should know where those edges are.

• Cohort classification needs history. A wallet that has been active for two days cannot be classified reliably. New wallets fall into the unclassified bucket until they build up enough track record. This means you are always missing some fraction of the most recent activity.
• 5-minute refresh is not high-frequency. This data is not built for sub-minute scalping. If your edge lives inside a 2-minute window, you need a different product. Cohort analytics works best on timeframes where 5 minutes is a reasonable tick.
• Past PnL does not guarantee future performance. The "top PnL cohort" can still be wrong on any given trade. Survivorship bias, regime changes, and mean reversion are all real. Treat cohort signals as one input among several, never as the whole trade thesis.
• Divergence works better on longer timeframes. Hour-by-hour and day-by-day divergence signals are cleaner than minute-by-minute ones. The noise at very short timeframes overwhelms the signal.
• Order flow shows current resting orders. It does not show future intent. A cluster of stops at a level tells you what happens if price gets there, it does not tell you whether price will get there.

These limits are not deal-breakers. They are the reason you combine cohort data with other inputs instead of using it in isolation.

Going Further

Once you are comfortable with /cohort/metrics, /cohort/bias, and /orders/5m-snapshots, there is more to explore.

• /liquidation-risk scores asset-level liquidation exposure so you can see where leveraged positions are clustered before a cascade triggers.
• /leaderboard ranks top traders by PnL across all-time, monthly, weekly, and daily timeframes if you want to drill into specific wallets inside a cohort.
• /builders/list returns analytics on builder codes, useful if you are building a trading interface and want to benchmark against other builders.
• /fills gives you 6+ months of trade history for backtesting strategies against real cohort behavior.
• Webhooks on the Flow tier ($799/mo) push alerts to you instead of making you poll. Trigger on cohort shifts, liquidation thresholds, or divergence events.

The free tier allows 100 requests per day, which is enough to prototype all of the examples in this article end-to-end. No credit card required, and you can keep using it indefinitely if your usage stays under the limit.

Get free API access

Closing Thoughts

The analytics layer does not replace your trading judgment. It gives you better inputs. Cohort data lets you see who is in the market, order flow shows what they are doing at specific price levels, and the divergence between smart money and retail is one of the cleanest signals Hyperliquid's transparent onchain infrastructure makes possible. The top PnL cohort can still be wrong and the bottom cohort can still get a trade right, but over enough observations the edge is real and the data is right there to query. Start with the cohort endpoints, build an intuition for what divergence looks like in your preferred timeframe, and layer in order flow once you trust the cohort reads.