> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hypedexer.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Liquidations

> Stream liquidation events, grouped per liquidated user and block, with optional filters on the address and the notional.

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

## Subscribe

```json theme={null}
{"method": "subscribe", "subscription": {"type": "liquidations"}}
```

<Warning>
  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"`.
</Warning>

Connection, authentication and heartbeat are the same for every stream, see the [WebSocket overview](/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:

```json theme={null}
{
  "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) |

```json theme={null}
{"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

```json theme={null}
{"method": "unsubscribe", "subscription": {"type": "liquidations"}}
```

## From the shell

```bash theme={null}
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/`](/api-reference/liquidations/list-liquidations), which serves liquidations since 22 March 2025.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.