How to Build with Liquidation Data from Hyperliquid

Hyperliquid liquidation data records positions that were forcibly reduced or closed, including the market, price, size and whether the liquidation used the order book or a backstop. Builders can use these records to monitor market stress, add execution controls and build liquidation dashboards.

The useful part is not the big red number. It is understanding what produced it, which accounts were affected and what the market looked like at the time.

This guide explains how to read those events and turn them into a practical application: a liquidation-stress panel for one market, with historical data, live updates and a visible indication of whether the data is complete.

For the trader's side, including how to calculate your liquidation price and avoid being liquidated, you may check out Hyperliquid Guide's liquidation explainer.

What is liquidation data on a trading platform?

A liquidation happens when an account no longer meets its maintenance-margin requirements and positions must be reduced or closed. Hyperliquid first attempts liquidation through the order book.

If account equity falls below the backstop threshold without successful book liquidation, the backstop mechanism can take over.

A useful liquidation record tells you:

• Who: the liquidated account.
• What: the market and position size affected.
• When: the event timestamp.
• At what price: the fill price and mark price at liquidation.
• How: order-book liquidation or backstop takeover.

Those two prices have different jobs. Mark price determines liquidation eligibility; an order-book liquidation executes against available liquidity. They can differ, especially during volatility.

If your application needs both, our Hyperliquid oracle, mark and mid-price data explains the pricing context.

How is liquidation data used in trading?

1. Monitor cascade risk

A liquidation cascade is the feedback loop traders worry about: forced buying or selling puts pressure on the market, more positions become vulnerable, and further liquidations follow.

Look at the pace of liquidation notional, the number of affected accounts and the liquidity available to absorb order-book liquidations. The same amount of forced flow can mean very different things in a deep book and a thin one.

Our analysis of how Hyperliquid priced in Dario's tweet provides a concrete example of examining liquidations alongside market depth. This guide focuses on building the monitoring workflow rather than repeating that event study.

Treat the result as context, not an automatic trade signal. A liquidation spike alone does not tell you whether the move is ending or accelerating.

2. Assess crowding: realized prints versus projected liquidation prices

Historical liquidation prints show what happened. Projected liquidation prices show where currently tracked positions could become vulnerable.

Use separate layers for them. Plot historical events at their fill prices. Build a projected-risk layer from current position state, including liquidationPx and the account snapshot time.

The projected layer needs refreshing. Hyperliquid explains that liquidation prices can change with funding and, for cross-margin positions, PnL elsewhere in the account.

Coverage matters too. If you track a selected set of wallets, label it as that set. Do not turn a partial view into a chart called “all Hyperliquid liquidation levels.”

3. Read the order-book versus backstop mix

Hydromancer's historical records distinguish market liquidations from backstop liquidations.

That lets you ask a more specific question than “How much was liquidated?”: how much was handled by the book, and how much reached the backstop?

Compare the methods over the same market and time window. Use notional rather than fill count when measuring the amount of exposure involved. A large transfer and a small fill should not contribute equally to a notional-based chart.

A rising backstop share is a reason to investigate liquidity and account conditions—not proof of insolvency. Keep backstop transfers separate when analysing aggressive order-book flow.

What do builders use liquidation data for?

1. Risk engines and account alerts

Build warnings that combine a user's current position risk with wider market conditions. For example, an application could flag a vulnerable position while liquidation activity in that market is increasing.

The event feed is the market context. Current account state is what makes the warning relevant to that user. A message sent after their liquidation is a notification, not prevention.

2. Execution controls

An execution system can combine liquidation activity with spread and depth to adjust order size, participation or temporary pauses.

Align the timestamps. Comparing an earlier liquidation with the current book can make liquidity appear to have been available when it was not. Our BBO, L2Book and L4Book guide explains which book view fits which workload.

3. HLP and HIP-3 backstop monitoring

Track acquired exposure, market concentration and subsequent position changes for the relevant backstop account.

Identify that account correctly: Hyperliquid describes its liquidator vault as a component strategy of HLP, while HIP-3 documentation describes DEX-specific onchain backstop liquidators with their own scope and eligibility conditions.

A takeover is one event, not the entire balance sheet. Add account-state data before drawing conclusions about exposure or financial health.

4. Attribution and user-facing products

Liquidation tickers, historical maps and builder-attributed dashboards answer different product questions. Choose the dataset that matches the label.

For builder analytics, builderLiquidations uses last-touch attribution: the user's last non-liquidation fill for the coin must carry the builder code. The docs also note that a preceding TWAP fill produces no notification because TWAP fills do not carry builder codes.

For volume analysis, start with liquidation versus non-liquidation volume, not “forced versus organic.” Non-liquidation activity is not automatically organic, and ADL requires its own classification.

Build a liquidation-stress panel for Hyperliquid

Start with one market. BTC is a straightforward scope for the first version: one identifier, one set of units and fewer opportunities to combine unrelated records.

The example below is an implementation blueprint, not a live market reading. Its output is a panel with four views:

Keep the bucketing interval configurable. The point is to make the definitions explicit before putting a chart in front of a user.

Step 1: Load a historical window

Use liquidationHistoryByTime for a coin and time range. It accepts inclusive millisecond startTime and endTime bounds, returns newest-first results and caps requests at 1,000 records.

This minimal request retrieves recent BTC events. For the panel, add the time bounds matching the selected window:

cURL

A response at the requested limit may be truncated. Split busy intervals and reconcile their boundaries. If a single-timestamp interval still reaches the cap, confirm a supported retrieval approach rather than skipping records and calling the window complete.

For larger studies, use the daily liquidation files described in our Reservoir archive guide. Liquidation files are subsets of the all-fills dataset; summing both double-counts those records. S3 is requester-pays, so AWS retrieval costs can apply.

Step 2: Establish the event contract

Normalize historical records into a small internal schema:

These mappings follow the historical endpoint's documented account perspective.

Use decimal arithmetic for financial values. Compute each record's notional as fill price multiplied by absolute size, in the market's quote units. Notional is exposure transferred or closed—not the trader's loss.

Do not assume every WebSocket fill has the same account perspective. Normalize live records against liquidation.liquidatedUser before applying the historical long/short mapping.

Step 3: Add live events without leaving a gap

After authenticating a backend WebSocket connection, subscribe to the documented liquidation stream:

WebSocket subscription (JSON)

The subscription shown is market-wide. Filter incoming records to coin === "BTC" for this panel; do not assume the stream accepts the REST endpoint's coin filter.

Messages carry a fills array of address-and-fill pairs, batched per block.

For initial synchronization, buffer live events while loading a historical window that overlaps the buffer. Normalize both sources, reconcile their overlapping records, then continue with live updates. Verify the cross-source event identity before merging; do not deduplicate just because two records share a price and size.

Keep credentials on the backend, not in the browser bundle. Our data-feeds guide covers the broader streaming setup.

Step 4: Calculate the panel's metrics

For each time bucket:

• Sum normalized liquidation notional separately for longs and shorts.
• Split notional by market and backstop; preserve unknown methods separately if encountered.
• Count distinct liquidatedUser addresses. Multiple fills from one account are not multiple affected accounts.
• Keep the most recent processed event time and the ingestion status alongside the totals.

For a backstop-share chart, divide backstop notional by the combined market-and-backstop notional in the same window. Show N/A if there are no classified events; zero is a different statement.

When comparing this panel with total traded volume, reconcile account-side fills to a consistent volume convention. Do not count both sides of an ordinary trade but only one side of a liquidation and call the ratio comparable.

Step 5: Make interruptions visible

Store the cursor only after successfully processing its message. Handle replay messages as well as live messages, and use idempotent writes so retries do not inflate totals.

The documented session replay window is up to 30 seconds. Longer interruptions need historical backfill and reconciliation.

For liquidation-stream replay, the docs specify (time, txIndex) deduplication. That rule belongs to the stream's replay handling; it is not a substitute for verifying identity across REST, WebSocket and archive data.

Show an unresolved gap in the panel instead of a misleading zero. Also distinguish the last event timestamp from connection health: a quiet market can have no new liquidations while the connection is healthy.

Step 6: Check the result before expanding

Before adding more markets, verify that:

• Replaying a processed batch leaves totals unchanged.
• Several fills from one account still count as one affected account within the selected window.
• Market and backstop subtotals reconcile with the classified total.
• Historical response caps and reconnect gaps are detected, not silently ignored.
• The live/REST overlap does not duplicate events.

Then add mark-price and order-book observations for market context. For account-specific risk features, add fresh position snapshots separately. Review the rate-limit guide before expanding the polling workload.

What liquidation data does Hydromancer provide?

Use this as a reference when choosing the inputs for your application:

For a first build, get one market working end to end. A small panel with correct totals and honest gap reporting is more useful than a market-wide map you cannot reconcile.

Our liquidation data product page gives the overview, and the API-key guide explains how to get access.