Hyperliquid Whale API: Five Endpoints for Wallet-Level Flow, With Honest Coverage Limits

Five new endpoints on the Buildix API expose Hyperliquid whale activity at the wallet level: the tracked whale list, a single wallet lookup, a paginated move feed, raw fills, and realized PnL. All five are live, all five are gated to the Whale tier, and all five ship with explicit coverage flags so you know exactly which part of the answer is real.

Most whale tracking products give you a dashboard. A dashboard is fine for browsing and useless for anything automated. If you want whale flow inside your own bot, your own Google Sheet, or your own Discord notifier, you need endpoints with stable shapes and honest limits.

What Are the Five Whale Endpoints?

GET /api/v1/whales returns the tracked whale set with position and account state. GET /api/v1/whales/{address} returns a single wallet, and it answers for untracked addresses too, marking them with a tracked: false field rather than throwing a 404. Passing an address that nobody follows still gives you live state.

GET /api/v1/whale-moves is the feed of detected position changes: opens, closes, increases, and reductions. It uses keyset pagination through a cursor, so you can walk history without the offset drift that breaks page-based pagination on a table that keeps growing.

GET /api/v1/wallet/{address}/fills returns the raw fill history for any address, and GET /api/v1/wallet/{address}/pnl returns realized performance over a requested window. Neither requires the address to be on the tracked list.

Typical response time in production sits between roughly 600 milliseconds and 1.4 seconds depending on the endpoint, with the fills endpoint the slowest because it pulls the largest payload upstream.

How Does the Whale Detection Actually Work?

A background monitor snapshots the state of every tracked wallet on a five minute cycle and diffs consecutive snapshots. A position that exists in the new snapshot and not the old one is an open. One that shrank is a reduction. That diff is what populates the move feed.

Two details make the difference between a feed you can trust and one that generates phantom events. First, a failed upstream read must never be treated as a closed position. If the exchange does not answer for a wallet on a given cycle, that wallet's previous snapshot is preserved rather than wiped, because comparing the next reading against an empty record would manufacture a fake open.

Second, staleness has to be measured against snapshot age rather than against a clock schedule. Tying a refresh check to specific minute values is the kind of assumption that silently stops firing the moment the cron cadence changes.

Neither of those is glamorous. Both are the reason the move feed does not send you a whale opening a position that has been sitting there for three days.

What Are the Coverage Limits Nobody Else Tells You About?

Hyperliquid's fill history endpoint ignores a start time beyond its retention window. Measured directly on a large institutional wallet in August 2026, requesting 7 days, 30 days, 90 days, and 365 days returned the same 2,000 fills covering roughly two days.

That is not a bug in any analytics tool. It is an upstream limit, and it cannot be engineered around from the outside. What it can be is declared.

So the fills endpoint returns covered_since and covered_until alongside the since and until you asked for. The PnL endpoint returns requested_since, covered_since, covered_until, and a boolean coverage_complete. A real response for a 7 day window might report a requested start of August 9 with actual coverage running from August 14 to August 15 and coverage_complete: false.

The alternative, which several products choose, is to serve a 30 day number and a 90 day number that are byte identical and let the customer assume they represent different periods. Labeling the gap is less impressive and considerably more useful.

One more honest limit: there is no websocket. The architecture is serverless, so streaming is not offered, and the developer documentation says so rather than listing it as a feature. Poll on an interval that matches the five minute snapshot cadence and you are not missing anything.

How Do You Authenticate and What Are the Limits?

API keys are generated from the account area on Pro and above. The five whale endpoints themselves require the Whale tier, and they return 403 for anonymous requests and for lower tiers, which is verified behavior in production rather than a documented intention.

Rate limiting is exposed on every response through X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Tier. The Whale tier allowance is 50,000 requests per day, which is enough to poll every tracked wallet continuously and still have headroom for backfills.

Error handling distinguishes causes rather than collapsing everything into a 500. Upstream throttling returns 503 as a retryable condition, upstream unavailability returns 502 with the underlying status in the detail, and malformed input returns 400 with a reason: invalid address, unsupported market, unknown action, malformed cursor, unsupported window.

HIP-3 symbols are explicitly rejected on the wallet endpoints with unsupported_market. The synthetic equity and commodity markets have a different data shape upstream, and returning a partial answer for them would be worse than returning none.

Full endpoint reference, parameters, and example payloads live at buildix.trade/developers.

What Would You Actually Build With This?

The obvious build is a mirror. Poll the move feed, filter by size and by the wallets you rate, push to your own channel with your own formatting and your own thresholds instead of accepting somebody else's alert design.

The more interesting build is a filter on your existing strategy. Take the entry conditions you already trade and require that no large wallet is positioned against you before the order goes out. Whale flow works better as a veto than as a trigger.

Third pattern: cohort tracking. Pull fills for a set of addresses over time, group by market, and measure which cohort is early rather than which cohort is large. Size is easy to see and tells you very little on its own.

Whichever direction you go, the wallet view at buildix.trade/wallet is the fastest way to identify which addresses are worth wiring into a program before you write any code against them.

FAQ

Do I need the Whale tier for all five endpoints? Yes. All five return 403 for lower tiers and for unauthenticated requests. Keys themselves can be generated from Pro upward, but these routes check tier per request.

Can I query a wallet that is not on the tracked list? Yes. Single wallet, fills, and PnL all accept arbitrary addresses. The tracked list only determines what appears in the aggregate whale endpoints and in the move feed.

Why is my 30 day PnL identical to my 90 day PnL? Because upstream fill retention covers roughly two days regardless of the start time requested. Read coverage_complete and covered_since on the response, which is exactly what those fields exist to tell you.

Is there a websocket feed? No. Serverless architecture, no persistent connections. Poll on an interval aligned with the five minute snapshot cycle.

An API that overstates its coverage costs you more than one that admits a gap, because you only find out which numbers were fiction after you have traded on them. The coverage flags are on these endpoints for that reason.

This article is educational and not financial advice. Wallet activity is public information and does not constitute a recommendation to follow any position. Perpetual futures carry a high risk of loss.