Hyperliquid Liquidation Tracker: 6 Proven Build Steps

A hyperliquid liquidation tracker watches where leverage is about to break. When price drifts toward a dense cluster of liquidation levels, a single move can trigger a chain of forced exits, and the traders who spot that cluster first are the ones who position around it instead of getting caught inside it. This guide shows you how to build a hyperliquid liquidation tracker on Hyperliquid perpetuals using Birdeye Data, the API that exposes open interest, liquidation maps, open positions, and wallet level risk through plain REST polling.

Perpetual futures on Hyperliquid move fast, and the risk picture changes every block. Birdeye Data covers four parts of that picture: which markets carry the most leverage, how much liquidation value sits in each market, where that value clusters across price, and which wallets are most exposed. You stitch those parts into one view. Everything below runs over REST, because the perpetuals endpoints have no socket feed, so the design leans on short polling intervals and a small store that holds the latest snapshot per market.

Direct Answer: Build a Hyperliquid Liquidation Tracker in 6 Steps

A hyperliquid liquidation tracker is six REST calls wired into one risk view. Each call answers one question, and you poll them on a loop.

1. Rank markets by open interest with GET /perps/v1/token/list to find where leverage actually concentrates.
2. Pull liquidation totals for one market with GET /perps/v1/token/overview to read the long and short pressure over 1h, 4h, 1d, and 7d.
3. Bucket liquidation value into price bands with GET /perps/v1/token/liquidation_map to render the heatmap and locate the walls.
4. List the largest open positions with GET /perps/v1/token/open_positions to see the size sitting under the nearest band.
5. Rank wallets with GET /perps/v1/wallet/list to find sharp traders worth following and overextended ones near the edge.
6. Profile one wallet with GET /perps/v1/wallet/overview and GET /perps/v1/wallet/open_positions to read its live positions, which carry the real liquidation price.

Every call uses the base URL https://public-api.birdeye.so, an X-API-KEY header, and the x-perp: hyperliquid header. Hyperliquid is the supported venue. The rest of this guide expands each step with parameters, a working request, and the gotchas that save you a debugging session.

Step 1: Rank Hyperliquid Markets by Open Interest

Before you watch liquidations, you need to know where leverage lives. A market with thin open interest cannot produce a meaningful cascade, so it is noise on a risk dashboard. The first call ranks every Hyperliquid market by open interest (OI) and hands you the long versus short split, which tells you which side is crowded and therefore which side is vulnerable.

Endpoint: GET /perps/v1/token/list

Venue: Hyperliquid (set with the x-perp: hyperliquid header)

Plan availability: All paid plans (Lite, Starter, Premium, Business, Enterprise)

Docs: Birdeye Data reference

The response gives you each market with its open interest, a long open interest figure, a short open interest figure, and a bias_text label that summarizes the lean. You sort by the field that matches your view: open_interest for raw size, long_io to find the most crowded longs, short_io for the most crowded shorts.

Parameter	Required	Description
x-perp	yes (header)	Venue selector, set to hyperliquid
time_frame	no	Window for the figures: 4h, 1d, 7d, 30d, or all (default all)
sort_by	no	open_interest, long_io, or short_io (default open_interest)
sort_type	no	desc or asc
offset	no	Pagination offset
limit	no	Page size, maximum 20

The field that decides your shortlist is sort_by. Sorting by open_interest surfaces the markets that can move the venue, while sorting by long_io or short_io surfaces the lopsided ones where a small price move clears a large stack. Read bias_text alongside the raw long_io versus short_io numbers to confirm the overcrowded side before you commit a market to your watchlist.

curl --request GET \
  --url '<https://public-api.birdeye.so/perps/v1/token/list?sort_by=open_interest&time_frame=1d&limit=20>' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --header 'x-perp: hyperliquid'

One value of polling this endpoint is the history you build yourself. Open interest history is not handed to you, so persist each snapshot with a timestamp. After a day of polling you can chart how open interest climbed into a move, which is the early signal that leverage is stacking up. Now that you have a shortlist of markets that actually carry risk, you can measure how much liquidation pressure each one holds, which is Step 2.

Step 2: Track Liquidation Pressure Across 4 Windows

Pick one market off the shortlist, say BTC, and the overview call returns its full pressure read in a single response: current price, the number of open positions, open interest, and how much long and short value has already been liquidated over four rolling windows, returned as long_liquidation_1h, short_liquidation_1h, and the matching 4h, 1d, and 7d fields. Reading the same market across those windows shows whether the pain is spiking in the last hour or has been bleeding all week.

Endpoint: GET /perps/v1/token/overview

Venue: Hyperliquid (set with the x-perp: hyperliquid header)

Plan availability: All paid plans (Lite, Starter, Premium, Business, Enterprise)

Docs: Birdeye Data reference

Parameter	Required	Description
x-perp	yes (header)	Venue selector, set to hyperliquid
token	yes	Market symbol such as BTC or SOL

The parameter that trips people up is token. It takes a symbol, not an address, so you pass BTC rather than a long mint or contract string. Pass an address here and the call returns nothing useful, because the venue indexes perpetual markets by ticker.

curl --request GET \
  --url '<https://public-api.birdeye.so/perps/v1/token/overview?token=BTC>' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --header 'x-perp: hyperliquid'

Compare the four windows side by side rather than reading one in isolation. A large 7d total with a quiet 1h means the storm already passed, while a 1h total climbing toward the 1d total means pressure is building right now. That contrast is the signal you want on the dashboard. Realized totals tell you a market is active, but not where the next liquidations wait. For that you switch from time to price, which is the liquidation map.

Step 3: Map Liquidation Walls Across Price Bands

The liquidation map answers that question by projecting how much position value would be liquidated at each price level, bucketed into bands, so a single market number becomes a row of levels you can actually see. Rendered as a heatmap, the dense bands are the walls, and price tends to gravitate toward them because that is where the most forced orders wait.

Endpoint: GET /perps/v1/token/liquidation_map

Venue: Hyperliquid (set with the x-perp: hyperliquid header)

Plan availability: All paid plans (Lite, Starter, Premium, Business, Enterprise)

Docs: Birdeye Data reference

Each row in the response is a price band defined by a low_price and a high_price. The band carries a long_liq_value and a short_liq_value, the liquidation value that would be cleared if price reaches that band, with matching long_liq_size and short_liq_size for the token quantity and a position_count for how many open positions sit there. Longs are liquidated as price falls and shorts as price rises, so the bands below the current price carry the long values and the bands above carry the short values. The cumulative cum_long_liq_value and cum_short_liq_value fields add that value up as price sweeps further in each direction, which tells you how much gets cleared by the time price reaches a given level.

Parameter	Required	Description
x-perp	yes (header)	Venue selector, set to hyperliquid
token	yes	Market symbol such as BTC or SOL

As in the previous step, token is a symbol. The fields to render are long_liq_value and short_liq_value per band for the heatmap intensity, and the cum_* fields when you want a cumulative curve overlaid on the chart.

curl --request GET \
  --url '<https://public-api.birdeye.so/perps/v1/token/liquidation_map?token=BTC>' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --header 'x-perp: hyperliquid'

To render the map, bucket the bands onto a vertical price axis and color each band by its liquidation value, with the current price drawn as a line across the middle. The heavy bands closest to the current price are the ones to watch, because a move into one triggers forced exits that push price further, into the next band, which is how a cascade builds. Once you can see the walls, the next question is which actual positions sit against them, and that is the open positions call.

Step 4: Surface the 50 Largest Open Positions

Aggregate value is enough to draw the heatmap, but a wall built by one whale behaves nothing like a wall built by a thousand small accounts. The open positions call shows you which it is, listing individual positions in a market with entry price, mark price, leverage, size, and position value, so you can see the concrete exposure sitting beneath the nearest wall.

Endpoint: GET /perps/v1/token/open_positions

Venue: Hyperliquid (set with the x-perp: hyperliquid header)

Plan availability: All paid plans (Lite, Starter, Premium, Business, Enterprise)

Docs: Birdeye Data reference

Parameter	Required	Description
x-perp	yes (header)	Venue selector, set to hyperliquid
token	yes	Market symbol such as BTC or SOL
sort_by	no	position_value or open_time (default open_time)
sort_type	no	desc or asc
offset	no	Pagination offset
limit	no	Page size, maximum 50

Sort by position_value with sort_type=desc to put the biggest exposure at the top, which is almost always what a risk view wants. Read direction from the sign of size: a negative size is a short and a positive size is a long, the standard signed convention on Hyperliquid. Note that this endpoint does not return a liquidation_price, so you read exposure here through entry_price, mark_price, leverage_value with its leverage_type, and size, and you reserve the real liquidation price for the wallet drill down in Step 6.

curl --request GET \
  --url '<https://public-api.birdeye.so/perps/v1/token/open_positions?token=BTC&sort_by=position_value&sort_type=desc&limit=50>' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --header 'x-perp: hyperliquid'

If you expect a liquidation_price field here and key your UI off it, every row renders blank, because the field lives on the wallet endpoint instead. Read the sign of size to label direction and use position_value to rank, and the position table becomes the bridge between the aggregate map and the individual traders behind it. That is where the wallet leaderboard comes in.

Step 5: Rank Traders on the Risk Leaderboard

The wallet list is where you stop looking at markets and start looking at the traders behind them. It ranks wallets across performance and risk fields, and one call serves two opposite goals depending on how you sort. Sort one way and you find sharp, consistent wallets worth following. Sort another way and you find overextended wallets sitting closest to liquidation.

Endpoint: GET /perps/v1/wallet/list

Venue: Hyperliquid (set with the x-perp: hyperliquid header)

Plan availability: All paid plans (Lite, Starter, Premium, Business, Enterprise)

Docs: Birdeye Data reference

Parameter	Required	Description
x-perp	yes (header)	Venue selector, set to hyperliquid
last_trade_duration	no	Activity window: 1d, 7d, 30d, 90d, or all (default all)
sort_by	no	One of 30 values including total_pnl, win_rate, roi, leverage, and bias, plus 90d variants (default total_pnl)
sort_type	no	desc or asc
offset	no	Pagination offset
limit	no	Page size, maximum 20

The lever here is sort_by, which accepts thirty values. For sharp wallets, sort by win_rate_90d to favor traders with a long track record rather than one lucky week. For risk, sort by leverage or bias to surface the accounts running the hottest books. Pair sort_by with last_trade_duration so you only rank wallets that have traded recently, since a dormant account with a great 90d return is not a live signal.

curl --request GET \
  --url '<https://public-api.birdeye.so/perps/v1/wallet/list?sort_by=win_rate_90d&sort_type=desc&last_trade_duration=7d&limit=20>' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --header 'x-perp: hyperliquid'

The leaderboard gives you a ranked set of wallet addresses, but it stops at the summary level. To see what a single wallet is actually holding right now, you drill into it, which is the final step.

Step 6: Profile One Wallet’s Live Liquidation Risk

Take any address off the leaderboard and you can open its book. Two calls do it. The wallet overview returns the account summary, fields like perp_equity, win_rate, total_pnl, and realized versus unrealized profit and loss. The wallet open positions call returns the live positions, which here carry the real liquidation_price. This is the only place in the pipeline where the liquidation price comes straight from the API rather than being inferred.

Endpoint: GET /perps/v1/wallet/overview and GET /perps/v1/wallet/open_positions

Venue: Hyperliquid (set with the x-perp: hyperliquid header)

Plan availability: All paid plans (Lite, Starter, Premium, Business, Enterprise)

Docs: overview, open positions

Parameter	Required	Description
x-perp	yes (header)	Venue selector, set to hyperliquid
wallet	yes	Wallet address in 0x format

The parameter is wallet, a 0x address taken straight from the leaderboard in Step 5. The field that matters most is liquidation_price on each open position, and leverage_type tells you which case you are in. An isolated position carries a single fixed level. A cross position returns null for liquidation_price, because its collateral is shared across the whole book and its risk is portfolio level rather than position level. For a cross position you derive an effective level from entry_price, leverage_value, and size rather than reading one field.

curl --request GET \
  --url '<https://public-api.birdeye.so/perps/v1/wallet/overview?wallet=0xYOUR_WALLET>' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --header 'x-perp: hyperliquid'

curl --request GET \
  --url '<https://public-api.birdeye.so/perps/v1/wallet/open_positions?wallet=0xYOUR_WALLET>' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --header 'x-perp: hyperliquid'

Treat liquidation_price as present when you get it and computed when you do not, and your wallet view stays correct whether a trader runs isolated or cross margin. With all six layers in place, you now have a full hyperliquid liquidation tracker, from a venue level scan down to one wallet’s nearest exit.

Track API Credit Usage as You Scale

A tracker like this polls constantly, and call volume climbs faster than most teams expect once the watchlist grows. Birdeye Data exposes a credits endpoint so you can read your own consumption directly and tune your polling intervals against the real number rather than guessing.

Endpoint: GET /utils/v1/credits

curl --request GET \
  --url '<https://public-api.birdeye.so/utils/v1/credits>' \
  --header 'X-API-KEY: YOUR_API_KEY'

A practical pattern is to poll the broad market list on a slower loop, since rankings shift gradually, and reserve the faster loop for the handful of markets and wallets on your active watchlist. Check the credits endpoint as you scale the watchlist, and let the real number set your cadence.

Putting It Together: Reference Architecture

The pieces form a funnel. Wide market scans feed a narrow watchlist, the watchlist feeds detailed polling, and detailed polling feeds the UI. A small in memory store holds the latest snapshot per market and per wallet, so the interface always reads from the store rather than blocking on a call.

Use this checklist before you ship:

• Every request sends the x-perp: hyperliquid header and an X-API-KEY.
• token parameters use symbols such as BTC, and wallet parameters use 0x addresses.
• Open interest snapshots are persisted with timestamps so you can build history.
• Position direction is read from the sign of size, not from a separate side field.
• liquidation_price is read from the wallet positions call, and computed for cross margin.
• Polling runs on two loops, a slow scan and a fast watchlist, with credits monitored.

Frequently Asked Questions

What is a hyperliquid liquidation tracker?

It is a tool that reads leverage and liquidation data from Hyperliquid perpetual markets and shows where forced exits are likely to cluster. A hyperliquid liquidation tracker combines market open interest, liquidation maps, open positions, and wallet level risk into a single view so a trader can see cascade zones before price reaches them.

Does Birdeye Data support venues other than Hyperliquid for perpetuals?

The perpetuals endpoints target Hyperliquid, which you select with the x-perp: hyperliquid header. The venue is set per request through that header.

Do the perpetuals endpoints stream over WebSocket?

The perpetuals endpoints are REST. You build live behavior with short polling intervals, typically a slow loop for the market scan and a faster loop for the markets and wallets on your watchlist.

Where does the real liquidation price come from?

From GET /perps/v1/wallet/open_positions, where each position can carry a liquidation_price. The market level GET /perps/v1/token/open_positions call does not return that field, so you use the wallet call for an exact figure and derive an effective level for cross margin positions.

How do I tell a long from a short in the position data?

By the sign of the size field. A negative size is a short and a positive size is a long, following the standard signed size convention.

Which plans can call the perpetuals endpoints?

All paid plans, from Lite through Enterprise, per the accessibility listing on each endpoint reference page.

---

You now have every layer of a hyperliquid liquidation tracker, from the venue level market scan down to one wallet’s nearest exit, all over plain REST. Grab an API key from Birdeye Data, start with the market list, and add each layer until the full risk view is live.