Hyperliquid Has No Leaderboard API, So What Is a Whale Tracker Reading?
Every Hyperliquid whale tracker API is built on an awkward fact: Hyperliquid's public info endpoint has no call that returns all users, all positions, or a ranked leaderboard. clearinghouseState gives you one address's margin book, exactly and on-chain, but you have to already know the address. There is no "list the top 1,000 accounts" request, and no stream of every position change on the exchange.
So a tracker cannot "subscribe to whales". It has to discover addresses from somewhere, poll each one, and decide which of them count as whales. The quality of a whale feed is almost entirely the quality of those three steps, and most products do not say how they do any of them.
This post explains how it is possible at all: where the address universe comes from, what polling several thousand accounts costs, why classification matters more than size, and which endpoints expose each layer. The companion posts cover what to do with the result: reading the $100k+ account book and interpreting net_bias.
Step One: Where the Addresses Come From
Hyperliquid does publish one thing that helps: a static leaderboard dump at stats-data.hyperliquid.xyz/Mainnet/leaderboard. It is a file of roughly 28 MB, not an API. Each row is an address with its accountValue and per-window PnL, ROI and volume (day, week, month, all-time). It is a snapshot of accounts that have traded, refreshed on Hyperliquid's schedule, and downloading it takes 25 to 30 seconds.
That file is the seed for every serious tracker, and it is how ours builds its universe. The collector behind /quant/whales downloads the dump, keeps every address with an account value of at least $100,000 (around 11,600 accounts when measured in mid-2026, capped at 15,000), ranks them by value and refreshes the set about every six hours. Large accounts trade the whole liquid universe, so this set captures essentially all of the positioning notional even though it is a fraction of all addresses.
Two consequences follow for anyone comparing trackers:
- A brand-new wallet that deposits $5M and opens a position this morning is not in anyone's feed until the leaderboard dump includes it and the tracker refreshes its universe. There is no faster discovery path from public data.
- The threshold is a design choice, not a protocol fact. A product that says "we track all whales" is describing its own cut-off. Ours is reported in the payload as
summary.min_account_value_usd, withsummary.universe_sizeandsummary.accounts_trackednext to it.
Step Two: Polling Thousands of Margin Books Without Getting Rate-Limited
With a universe in hand, the tracker calls clearinghouseState for each address and reads assetPositions: coin, signed size, entry price, leverage, margin used, unrealised PnL and the on-chain liquidationPx. That last field is the reason this whole approach works. The liquidation price is not estimated; it is the number the exchange will act on.
The cost is throughput. Hyperliquid's public info endpoint has an IP-level request budget, so polling 11,000 addresses is a pacing problem. The collector polls one address at a time under that budget, prioritises the largest accounts and the ones that were active last cycle, and rotates a cursor through idle accounts for amortised discovery of newly active ones. The result is the roughly five-minute refresh behind /quant/whales, /quant/positioning and the liquidation map, and it is why the payload stamps its own cadence: positions_as_of at the top level is the poll-cycle completion time, and each top_coins[] entry has its own positions_as_of.
You can do the single-address version yourself through the API, for any address, tracked or not:
curl "https://cryptodataapi.com/api/v1/hyperliquid/wallet-positions?address=0xdfc24b077bc1425ad1dea75bcb6f8158e10df303" \
-H "X-API-Key: cdk_live_your_key"
The response is {wallets: {address: {account_value, positions: [...]}}, updated_at}, and each position carries coin, size, side, entry_price, unrealized_pnl, leverage, liquidation_price (null when the leg is collateralised well enough that no single-coin move liquidates it) and margin_used. A tracked address answers from cache; an untracked one triggers an on-demand query to Hyperliquid. That is the whole tracker in miniature: one address, one book, read on demand.
Step Three: Why Size Alone Makes a Bad Whale Feed
The largest accounts on Hyperliquid are market makers and vaults. They hold enormous two-sided inventory that says nothing about direction, and a feed that sums their books will tell you the "whales" are always roughly flat. A whale tracker that does not classify accounts is mostly a market-maker tracker.
Hyperliquid exposes no ground-truth account labels, so classification is a behavioural heuristic, and ours is documented rather than hidden. From the leaderboard metrics and the live position structure each account is tagged using:
- Turnover: monthly volume divided by account value. Market makers churn 50 to 500 times their equity in a month; directional traders are usually under 10.
- Breadth: how many distinct coins the account holds. Makers quote many markets.
- Net-to-gross ratio: directional traders are one-sided; makers are close to balanced.
- Average leverage, which flags the
high_leveragecohort. - Consistent profitable timeframes plus all-time PnL, which flags
smart_money.
The output is a primary class of market_maker, whale or other, plus overlay tags, and the rule set is versioned: meta.classifier_version changes whenever a threshold or anchor moves, so you can tell a classification drift from a real positioning change. The field that makes the classification useful is top_coins[].directional_net_usd: the coin's net notional excluding market-maker accounts. A large net_usd with a small directional_net_usd is liquidity, not a bet.
What /quant/whales Serves From All of That
curl "https://cryptodataapi.com/api/v1/quant/whales" \
-H "X-API-Key: cdk_live_your_key"
The response rolls the whole universe into a summary and a per-coin top_coins list. An example shape, with illustrative numbers:
{
"positions_as_of": 1761300000000,
"summary": {
"accounts_tracked": 11420, "universe_size": 11600, "min_account_value_usd": 100000,
"by_class": {"market_maker": 310, "whale": 1890, "other": 9220},
"coins_held": 164,
"total_long_usd": 6100000000, "total_short_usd": 5400000000,
"total_net_usd": 700000000, "total_gross_usd": 11500000000,
"long_pct": 53.0, "long_short_ratio": 1.13, "net_bias": "long",
"by_tag_usd": {"smart_money": {"long_usd": 0, "short_usd": 0, "net_usd": 0, "gross_usd": 0, "n_accounts": 0}}
},
"top_coins": [
{"coin": "BTC", "mark": 98000.0, "segment": "perp",
"gross_usd": 3900000000, "long_usd": 2100000000, "short_usd": 1800000000,
"net_usd": 300000000, "directional_net_usd": 410000000,
"long_pct": 53.8, "long_pct_pctile_30d": 71.0, "net_bias": "long",
"n_accounts": 4100, "n_long": 2300, "n_short": 1800, "dominant_side": "long",
"positions_as_of": 1761299940000}
],
"meta": {"segment": "perp", "venue": "hyperliquid", "spot_status": "not_yet_collected",
"classifier_version": "2026-07-02"}
}
Two fields need care. long_pct is structurally below 50% across the whole book, because gross_usd includes market makers whose short perp legs are hedged elsewhere; compare it to its own history, which is what long_pct_pctile_30d does per coin (the live long_pct's percentile within that coin's trailing 30 days of hourly samples). It is null until 48 hourly samples exist and for coins new to the top list; null means "no baseline yet", not a middling percentile. And summary.by_tag_usd is an overlay by tag, not a breakdown of by_class; the two do not sum to each other.
top_coins holds the 100 coins with the most whale notional (60 before 2026-10-14), sorted by gross_usd. Scope is Hyperliquid perpetuals; meta.spot_status says spot balances are not collected, and tokenised equities are excluded. The route is Pro and Pro Plus, or $0.03 per call over x402 with no key. The payload minus meta is archived every five minutes as the whale_activity snapshot type, and a daily aggregate going further back is on /api/v1/quant/whales/history (Pro Plus), where every point says source: "seed" or "live" and estimated so you know which part is observed. The free Crypto Whale Radar page draws the same read with about a 30-minute delay.
Whale Universe vs Top-Trader Leaderboard vs Single Wallet
"Whale tracking" covers three different reads that are easy to conflate. They come from the same leaderboard file but answer different questions.
/quant/whales | /hyperliquid/top-traders | /hyperliquid/wallet-positions | |
|---|---|---|---|
| Universe | Every account ≥ $100k, ~11k | 50 accounts scored on performance | Any one address |
| Selected by | Size | Account value ≥ $10k, all-time PnL ≥ $5k, month PnL ≥ $500, month volume ≥ $100k, profitable in ≥ 3 windows | You |
| Question answered | Where is big money positioned, net of makers? | Who has been consistently profitable? | What does this wallet hold right now? |
| Refresh | ~5 min | Leaderboard scored daily | On demand for untracked addresses |
| Key fields | net_bias, directional_net_usd, by_class | score, account_value, pnl.{day,week,month,all_time}, roi.* | positions[].liquidation_price, leverage |
| Tier | Pro, or x402 per call | Any key | Any key |
The top-trader list is the input to copy trading rather than to positioning analysis. /api/v1/hyperliquid/wallets/search (Pro) queries the same scored pool with your own gates, min_score, min_win_rate, min_profit_factor, min_trades_30d, min_avg_duration_hours and exclude_types such as hft,scalper, and the pool refreshes daily at 19:00 UTC. The copy-trading workflow built on it is in the Python copy-trading tutorial.
How to Use This in a Bot (and What It Cannot Tell You)
Poll /quant/whales on a five-minute loop, not faster. The read is cached for about two minutes and the underlying positions refresh on a five-minute cycle; polling every ten seconds returns the same positions_as_of. Diff directional_net_usd per coin between polls to see where conviction is moving.
Gate on the percentile, not the raw share. long_pct_pctile_30d above 90 or below 10 is "unusual for this coin"; a raw long_pct of 55 is not, because the book sits below 50 structurally. Skip coins where it is null rather than treating them as neutral.
Use by_class to sanity-check a move. If net_usd swings but directional_net_usd does not, a maker re-hedged. That is not a whale decision.
What no public-data tracker can give you: a wallet that is not yet in Hyperliquid's leaderboard dump, spot wallet balances, an account's intent behind a hedge, or a complete per-account history before the collector started (the whale_activity snapshots are forward-only because the data existed nowhere else). Anyone claiming otherwise is either estimating or running their own node and reading the order tape, which is a different and much more expensive product.
Single-wallet reads and the top-trader list are on any free key; the whale universe is on Pro, or per call over x402 for agents without a key.
Frequently asked questions
Does Hyperliquid have a leaderboard or all-users API?
No. The public info endpoint serves one address at a time through clearinghouseState. The only broad source is a static leaderboard file of about 28 MB at stats-data.hyperliquid.xyz, which lists accounts with their value and per-window PnL, ROI and volume. Trackers seed their address universe from that file.
How does the /quant/whales endpoint choose which accounts to track?
It keeps every leaderboard address with an account value of at least $100,000, ranks them by value, refreshes the set about every six hours and polls each one's margin book under Hyperliquid's request budget on a roughly five-minute cycle. summary.min_account_value_usd, universe_size and accounts_tracked report the current scope.
Why does the whale feed separate market makers?
The largest Hyperliquid accounts are market makers and vaults holding balanced two-sided inventory. Without classification a whale feed is mostly a market-maker feed that always reads flat. Accounts are tagged by turnover, breadth, net-to-gross ratio, leverage and profitability, and top_coins[].directional_net_usd excludes the market-maker class.
Can I read any Hyperliquid wallet's positions through the API?
Yes. GET /api/v1/hyperliquid/wallet-positions?address=0x... returns account_value and each position's coin, size, side, entry_price, unrealized_pnl, leverage, liquidation_price and margin_used, fetched on demand for addresses that are not already tracked. Any valid key.
What tier is the Hyperliquid whale tracker on?
/quant/whales is Pro and Pro Plus, or $0.03 per call over x402 with no key. /quant/whales/history is Pro Plus. /hyperliquid/top-traders and /hyperliquid/wallet-positions answer any valid key, and /hyperliquid/wallets/search is Pro.



