> ## 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.

<CardGroup cols={2}>
  <Card title="Credit Cost"> 1 per minute</Card>
  <Card title="Processing"> Realtime</Card>
</CardGroup>

<Tip>
  Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Fhyperliquid-websocket%2Fliquidation-fills).
</Tip>

<Info>
  * 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 <a href="https://goldrush.dev/docs/api-reference/streaming-api/types/hypercore-ledger-event" target="_blank" rel="noopener noreferrer">`HypercoreLedgerEvent`</a> type.
</Info>

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>
```

<ParamField query="key" type="string" required>
  Your GoldRush API key. Passed as a query parameter at connection time - no `Authorization` header is used.
</ParamField>

## Subscribe

Send this JSON message after the connection is established:

<ParamField body="method" type="string" required>
  Always `"subscribe"`.
</ParamField>

<ParamField body="subscription" type="object" required>
  <Expandable title="properties">
    <ResponseField name="type" type="string" required>Always `"liquidationFills"`.</ResponseField>

    <ResponseField name="aggregateByTime" type="boolean">
      When `true`, partial fills of the same liquidation within the same block are merged into one. Default `false`.
    </ResponseField>
  </Expandable>
</ParamField>

### Example

<CodeGroup>
  ```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())
  ```
</CodeGroup>

## 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
      }
    ]
  ]
}
```

<ResponseField name="channel" type="string">Always `"liquidationFills"`.</ResponseField>

<ResponseField name="fills" type="array<[string, object]>">
  Tuples of `[address, fill]`. Same `fill` shape as <a href="/api-reference/hyperliquid-websocket/user-fills">`userFills`</a>, with `liquidation` always populated.

  <Expandable title="fill properties (delta vs userFills)">
    <ResponseField name="liquidation" type="object" required>
      Always present on this stream.

      <Expandable title="properties">
        <ResponseField name="liquidatedUser" type="string">The wallet whose position was liquidated.</ResponseField>
        <ResponseField name="markPx" type="string">Mark price at the time of liquidation.</ResponseField>
        <ResponseField name="method" type="string">Liquidation method - `"market"` or `"backstop"`.</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>

  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`](/api-reference/hyperliquid-websocket/user-fills) shape.
</ResponseField>

## Related endpoints

<CardGroup cols={2}>
  <Card title="allFills" href="/api-reference/hyperliquid-websocket/all-fills">stream every fill on HyperCore in real time for global market analytics and cross-wallet order-flow…</Card>
  <Card title="builderFills" href="/api-reference/hyperliquid-websocket/builder-fills">stream live attributed fills for one or more builder addresses in real time.</Card>
  <Card title="userFills" href="/api-reference/hyperliquid-websocket/user-fills">stream real-time trade fills for one or more wallets as they execute on HyperCore.</Card>
</CardGroup>

*Last reviewed: 2026-06-16*