Liquidations

Liquidation events as our indexer publishes them: one frame per liquidated position, already aggregated across the liquidators that absorbed it.

{"method": "subscribe", "subscription": {"type": "liquidations"}}

The subscription name is plural, liquidations. The singular is refused with {"type":"error","message":"Unsupported subscription: liquidation"}. Data frames, on the other hand, carry the singular "type": "liquidation".

Connection, authentication and heartbeat are the same for every stream, see the WebSocket overview. The subscription is acknowledged with {"channel":"subscriptionResponse","data":{"method":"subscribe","subscription":{...}}}, then frames start arriving.

A real frame

Captured on 19 September 2026, trimmed to its first row:

{
  "type": "liquidation",
  "count": 12,
  "data": [
    {
      "builder": null,
      "coin": "UNI",
      "fee_total_liquidated": 0.005615,
      "fill_px_vwap": 9.2849,
      "hash": "0x1220a9283ba8a91a139a0444ba813a00005bc10dd6abc7ecb5e9547afaac8304",
      "liq_dir": "short",
      "liquidated_user": "0xf7f01ac68c0b87679b4a78064b930fd58d80ed0e",
      "liquidator_count": 1,
      "liquidators": ["0x53136b4a7c432585f28903b77c7816a723e0271f"],
      "mark_px": 9.2824,
      "method": "market",
      "notional_total": 12.99886,
      "size_total": 1.4,
      "tid": 829369114245472,
      "time": "2026-09-19T07:12:56",
      "time_ms": 1789801976260
    }
  ]
}

count is the number of rows in data, not a running total.

Field	Meaning
`coin`	Market of the liquidated position
`liq_dir`	Side that was liquidated: `long` or `short`
`liquidated_user`	Address whose position was closed
`liquidators` / `liquidator_count`	Addresses that absorbed it, and how many
`size_total`	Size liquidated, in units of the coin
`notional_total`	Value liquidated, in USD
`fill_px_vwap` / `mark_px`	Volume-weighted fill price, and the mark price at the time
`fee_total_liquidated`	Fees paid on the liquidating fills
`method`	How it was closed, for example `market`
`builder`	Builder code carried by the fills, `null` when there is none
`tid`, `hash`	Trade id and transaction hash
`time`, `time_ms`	Event time, as an ISO string and in milliseconds

Filters

All filters are optional and can be combined.

Filter	Type	Effect
`user`	string	Only liquidations where this address is the liquidated user or a liquidator
`users`	array of strings	Same as `user` for up to 50 addresses. Combines with `user`
`amount_dollars`	number	Only liquidations whose `notional_total` is at least this value in USD
`builder`	string	Only liquidations of positions whose fills carried this builder code (0x address)

{"method": "subscribe", "subscription": {"type": "liquidations", "amount_dollars": 50000}}
{"method": "subscribe", "subscription": {"type": "liquidations", "user": "0xf7f01ac68c0b87679b4a78064b930fd58d80ed0e"}}
{"method": "subscribe", "subscription": {"type": "liquidations", "users": ["0xf7f01ac68c0b87679b4a78064b930fd58d80ed0e", "0x53136b4a7c432585f28903b77c7816a723e0271f"]}}

An invalid users value is refused with an error frame and no subscription: {"type":"error","message":"liquidations: 'users' must be a non-empty list of 0x-prefixed addresses"}, or "... accepts at most 50 addresses".

Unsubscribe

{"method": "unsubscribe", "subscription": {"type": "liquidations"}}

From the shell

wscat -H "X-API-Key: $HYPEDEXER_API_KEY" -c wss://api.hypedexer.com/ws
# then paste:
# {"method":"subscribe","subscription":{"type":"liquidations","amount_dollars":50000}}

Historical liquidations

Right after the acknowledgement, the server sends one liquidation frame with the most recent events it holds in cache, filtered like the stream: up to 200, newest first. The cache empties after ten minutes without any liquidation, so this first frame can have count: 0. There is no longer replay: for anything older, use GET /liquidations/, which serves liquidations since 22 March 2025.

Introduction

REST API

WebSocket

A real frame

Filters

Unsubscribe

From the shell

Historical liquidations

​Subscribe

​A real frame

​Filters

​Unsubscribe

​From the shell

​Historical liquidations

Subscribe

A real frame

Filters

Unsubscribe

From the shell

Historical liquidations