liquidationFills | Hyperliquid WebSocket API

Credit Cost

1 per minute

Processing

Realtime

Estimate your monthly cost for this API using the Pricing Calculator.

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.

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>

string

required

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

Send this JSON message after the connection is established:

string

required

Always "subscribe".

object

required

Show properties

string

required

Always "liquidationFills".

boolean

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

Example

wscat -c "wss://hypercore.goldrushdata.com/ws?key=$GOLDRUSH_API_KEY"

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

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,
      );
    }
  }
});

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":

{
  "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.

{
  "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
      }
    ]
  ]
}

string

Always "liquidationFills".

array<[string, object]>

Tuples of [address, fill]. Same fill shape as userFills, with liquidation always populated.

Show fill properties (delta vs userFills)

object

required

Always present on this stream.

Show properties

string

The wallet whose position was liquidated.

string

Mark price at the time of liquidation.

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

allFills

stream every fill on HyperCore in real time for global market analytics and cross-wallet order-flow…

builderFills

stream live attributed fills for one or more builder addresses in real time.

userFills

stream real-time trade fills for one or more wallets as they execute on HyperCore.

Last reviewed: 2026-06-16

Foundational API

Hyperliquid API

JSON-RPC

Service Keys

liquidationFills | Hyperliquid WebSocket API

Credit Cost

Processing

Endpoint

Example

Unsubscribe

Streamed message

allFills

builderFills

userFills

Credit Cost

Processing

​Endpoint

​Subscribe

​Example

​Unsubscribe

​Streamed message

​Related endpoints

allFills

builderFills

userFills

Endpoint

Subscribe

Example

Unsubscribe

Streamed message

Related endpoints