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

# liquidationFills | Hyperliquid WebSocket API

> Hyperliquid liquidationFills: stream a global, market-wide feed of every liquidation fill on HyperCore.

> [card] Credit Cost
>
> 1 per minute

> [card] Processing
>
> Realtime

> [!TIP]
>
> Estimate your monthly cost for this API using the [Pricing Calculator](https://goldrush.dev/docs/pricing-calculator.md?endpoint=%2Fapi-reference%2Fhyperliquid-websocket%2Fliquidation-fills).

> [!NOTE]
>
> * GoldRush-native:  No `wss://api.hyperliquid.xyz/ws` equivalent. The public WebSocket exposes per-wallet fills only; detecting liquidations there would require subscribing to every wallet and filtering.
> * Global stream: Every liquidation fill on HyperCore, across every wallet, on a single subscription. No `addresses` filter is accepted.
> * Every fill in this stream carries a non-null `liquidation` object. The rest of the payload mirrors `userFills`.
> * Live-only: No historical snapshot on subscribe. For historical liquidations, query the Streaming API [`HypercoreLedgerEvent`](https://goldrush.dev/docs/api-reference/streaming-api/types/hypercore-ledger-event) type.

Subscribe with no addresses filter to receive every liquidation fill on HyperCore across every wallet, in real time. Same payload shape as `userFills`, with the `liquidation` object populated (with `liquidatedUser`, `markPx`, `method`) on every entry.

## Endpoint

```
wss://hypercore.goldrushdata.com/ws?key=<GOLDRUSH_API_KEY>
```

**key** `string` *required*

Your GoldRush API key. Passed as a query parameter at connection time - no `Authorization` header is used.

## Subscribe

Send this JSON message after the connection is established:

**method** `string` *required*

Always `"subscribe"`.

**subscription** `object` *required*

**properties**

**type** `string` *required*

Always `"liquidationFills"`.

**aggregateByTime** `boolean`

When `true`, partial fills of the same liquidation within the same block are merged into one. Default `false`.

### Example

```bash wscat theme={null}
wscat -c "wss://hypercore.goldrushdata.com/ws?key=$GOLDRUSH_API_KEY"

> {"method":"subscribe","subscription":{"type":"liquidationFills"}}
```

```typescript TypeScript theme={null}
import WebSocket from "ws";

const ws = new WebSocket(
  `wss://hypercore.goldrushdata.com/ws?key=${process.env.GOLDRUSH_API_KEY}`,
);

ws.on("open", () => {
  ws.send(JSON.stringify({
    method: "subscribe",
    subscription: { type: "liquidationFills" },
  }));
});

ws.on("message", (raw) => {
  const msg = JSON.parse(raw.toString());
  if (msg.channel === "liquidationFills") {
    for (const [address, fill] of msg.fills) {
      console.log(
        "liquidated:", fill.liquidation.liquidatedUser,
        "via", fill.liquidation.method,
        "—", fill.coin, fill.sz, "@", fill.px,
      );
    }
  }
});
```

```python Python theme={null}
import asyncio, json, os
import websockets

async def main():
    uri = f"wss://hypercore.goldrushdata.com/ws?key={os.environ['GOLDRUSH_API_KEY']}"
    async with websockets.connect(uri) as ws:
        await ws.send(json.dumps({
            "method": "subscribe",
            "subscription": {"type": "liquidationFills"},
        }))
        async for raw in ws:
            msg = json.loads(raw)
            if msg.get("channel") == "liquidationFills":
                for address, fill in msg["fills"]:
                    liq = fill["liquidation"]
                    print("liquidated:", liq["liquidatedUser"],
                          "via", liq["method"], "—",
                          fill["coin"], fill["sz"], "@", fill["px"])

asyncio.run(main())
```

## Unsubscribe

Send the same `subscription` body with `method: "unsubscribe"`:

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

## Streamed message

Each push has `channel: "liquidationFills"` and a `fills` array of `[address, fill]` tuples. The `address` is the wallet whose order was filled (i.e. the liquidator's counterparty); `liquidation.liquidatedUser` is the wallet whose position was liquidated.

```json theme={null}
{
  "channel": "liquidationFills",
  "fills": [
    [
      "0x742d35cc6634c0532925a3b844bc9e7595f7f2e2",
      {
        "coin": "ETH",
        "px": "2150.5",
        "sz": "1.5",
        "side": "B",
        "time": 1704067200000,
        "startPosition": "1.5",
        "dir": "Open Long",
        "closedPnl": "125.5",
        "hash": "0xabc...def",
        "oid": 12345678,
        "crossed": false,
        "fee": "2.5",
        "tid": 87654321,
        "feeToken": "USDC",
        "liquidation": {
          "liquidatedUser": "0x...",
          "markPx": "2148.75",
          "method": "market"
        },
        "twapId": null
      }
    ]
  ]
}
```

**channel** `string`

Always `"liquidationFills"`.

**fills** `array\<[string, object]\>`

Tuples of `[address, fill]`. Same `fill` shape as [`userFills`](https://goldrush.dev/docs/api-reference/hyperliquid-websocket/user-fills), with `liquidation` always populated.

**fill properties (delta vs userFills)**

**liquidation** `object` *required*

Always present on this stream.

**properties**

**liquidatedUser** `string`

The wallet whose position was liquidated.

**markPx** `string`

Mark price at the time of liquidation.

**method** `string`

Liquidation method - `"market"` or `"backstop"`.

All other fields (`coin`, `px`, `sz`, `side`, `time`, `startPosition`, `dir`, `closedPnl`, `hash`, `oid`, `crossed`, `fee`, `tid`, `feeToken`, `twapId`, and optional `cloid` / `builderFee` / `builder`) match the [`userFills`](https://goldrush.dev/docs/api-reference/hyperliquid-websocket/user-fills) shape.

## Related endpoints

> [card] [allFills](https://goldrush.dev/docs/api-reference/hyperliquid-websocket/all-fills.md)
>
> stream every fill on HyperCore in real time for global market analytics and cross-wallet order-flow monitoring.

> [card] [builderFills](https://goldrush.dev/docs/api-reference/hyperliquid-websocket/builder-fills.md)
>
> stream live attributed fills for one or more builder addresses in real time.

> [card] [userFills](https://goldrush.dev/docs/api-reference/hyperliquid-websocket/user-fills.md)
>
> stream real-time trade fills for one or more wallets as they execute on HyperCore.

> [card] [builderLiquidations](https://goldrush.dev/docs/api-reference/hyperliquid-websocket/builder-liquidations.md)
>
> subscribe to real-time liquidation fills of your users.

See all Hyperliquid endpoints: [Overview hub](https://goldrush.dev/docs/goldrush-hyperliquid/overview.md) · [WebSocket API reference](https://goldrush.dev/docs/goldrush-hyperliquid/websocket-api/overview.md)

*Last reviewed: 2026-06-16*


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