On most centralized exchanges, another trader’s open position is private. Hyperliquid works differently: its public information endpoint returns an account’s open perpetual positions and margin summary to a request whose only required detail is the account’s address. That is what makes “whale tracking” possible there. A tracker can poll the largest or most profitable accounts, notice when a position opens, grows, shrinks or flips, and report the change soon afterwards.
That visibility is real, and it is also easy to over-read. A position record is a fact about one address at one moment. The story people attach to it (“a whale is betting on a crash”, “smart money is buying”) is an interpretation layered on top. This guide separates the two, explains how SuperQuant’s tracker picks the accounts it follows, and lists the conclusions the data cannot carry. It is the first part of a six-part series.
What a public address query returns
Hyperliquid’s API documentation describes a clearinghouseState request for a user’s open positions and margin summary for perpetuals trading. Besides its type, the only required field is the user’s onchain address, in 42-character hexadecimal format. In the documentation’s example response, each open position lists the coin, the size, the entry price, the position value, the unrealized profit and loss (the gain or loss on the open position at current prices), the margin used, the leverage type and value, and a liquidation price. Account-level margin summaries come back in the same response.
The same endpoint has separate requests for open orders and fills, and fill history has limits worth knowing before you build on it. The documentation says the time-range fills request returns at most 2,000 fills per response, and that only the 10,000 most recent fills are available. For a very active account, that window can be short, so a “complete trade history” assembled from the public endpoint may not be complete at all.
What the record cannot tell you
The left column of the diagram is data. The right column is where most whale commentary lives, and none of it is in the response.
- Identity. An address is not a person or a fund. One owner can control many addresses, and one address can be operated by an automated system, a team or a custodian.
- Subaccounts and agents. Hyperliquid’s API documentation says that to query a master account or a sub-account you must pass in that account’s actual address, and that using an agent wallet’s address (a separate key that trades for an account) leads to an empty result. A large short on one address may be offset by a long on a sibling sub-account you are not watching.
- Other venues. A short on Hyperliquid can be a hedge against spot holdings or a long on another exchange. The public record shows one leg of a position that may have several.
- Intent and timing. A close can be profit-taking, a margin decision, a risk limit or a rebalancing rule. Nothing in the data says which, or what the account will do next.
- How collateral is arranged. Hyperliquid’s margining documentation describes cross margin, which shares collateral across an account’s cross positions, and isolated and strict isolated margin, which constrain an asset’s collateral to that asset. Its API documentation adds that under unified account or portfolio margin, the spot balances endpoint should be used for the trading account balance, so the perpetuals summary alone may not show it. Because cross positions share collateral, a liquidation price from one snapshot can change as the account’s other positions change; part two covers this.
A useful habit is to write the recorded fact and your interpretation in separate columns, exactly as the diagram does. In a fictional example, “Address 0x51c… reduced an ETH short by $6.4M at 14:02 UTC” is a recorded fact. “Whales are turning bullish on ETH” is a claim that needs more evidence than one record can give.
How a top-trader list is chosen
A tracker has to decide which accounts to watch, and that choice shapes everything that follows. SuperQuant’s public guide lists the rules its tracker uses. Vault accounts (managed pools rather than individual traders) are excluded. The rest need at least $5M of 30-day trading volume, $1M of 7-day volume, a $100k account and turnover under 1,500 times (30-day volume divided by account value). Those accounts are ranked by 30-day profit. The top 100 are re-ranked every six hours and checked about once a minute.
Two consequences follow directly. First, “top trader” here means “highest recent profit among active, sizable, non-vault accounts”. It does not mean the largest account or the most skilled trader. Second, the list is chosen using results that already happened. A list built from recent winners will look good over the window that built it; part four of this series explains why the fair test is what happens after an account is selected.
The guide also says that changes under $100k, and same-direction resizes under 25 percent, are not recorded as moves. Each check is compared with the one before, so a position built or trimmed in small steps can change a lot without any single step being recorded. That keeps alerts readable but can hide gradual scaling.
Reading a whale move without over-reading it
When a tracked account opens, closes or flips a position, or resizes it past those thresholds, the tracker records a move. The guide says each move is then measured at +1h, +24h and +7d from the price when it was detected. Before treating a move as information, ask three questions.
- What exactly changed? In fictional numbers, an “open” of $12M and an “increase” from $40M to $52M are different events even though both add $12M. A flip from short to long closes one position and opens another.
- How large is it relative to the market? A $5M position is large for one account and can be small relative to open interest (the total size of all open positions) in a major coin. Compare it with that market’s open interest rather than with your own account.
- What would make my interpretation wrong? If you read a large close as “the trader expects a reversal”, write down what you would expect to see if it were simply a risk-limit reduction, and check both.
The on-chain data research guide makes the same point for wallet labels: a record shows what was recorded, and attribution, intent and skill are separate claims that need their own evidence.
A short checklist before you use whale data
- Write the address, coin, side, size and detection time before writing any interpretation.
- Treat the account as one leg of a possibly larger book, unless you have evidence otherwise.
- Remember how the list was chosen: by 30-day profit, re-ranked every six hours.
- Remember that small changes and gradual resizing may not appear as moves.
- Check whether a fill history you rely on is inside the 10,000-fill window.
- Keep a record of moves that turned out to mean nothing, not only the ones that looked prescient.
Where this series goes next
The next part, whale liquidation distance, explains how the gap between price and a large position’s liquidation threshold is measured and why it moves. After that, whale consensus and crowding looks at what happens when many tracked accounts lean the same way, whale scorecards covers hit rates and selection bias, paper-copying a whale explains why follower fills differ, and a whale-alert research routine turns alerts into questions you can review. For the general risks of following another account’s trades, read the guide to evaluating copy trading.
This is educational research context, not investment advice.