builderLiquidations | 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; attributing a liquidation to a builder there would require subscribing to every wallet and filtering.
Builder-scoped: builder is required. The stream returns only liquidation fills whose closing order was routed through your builder code - it is the intersection of liquidationFills and builderFills.
Every entry carries a non-null liquidation object plus the attributed builder; the rest of the payload mirrors userFills.
TWAP caveat: TWAP fills do not carry builder codes. If a user’s last fill before liquidation was a TWAP fill, no builder liquidation is emitted for it.

Subscribe with your builder address to receive every liquidation fill attributed to your builder code, in real time. This is the builder-attributed slice of the global liquidationFills stream: same per-fill shape as userFills, with both the liquidation object and the builder attribution populated 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. builder is required.

string

required

Always "subscribe" - GoldRush house style, matching the sibling channels. This is the only accepted form; a bare type: "subscribe" envelope is not recognized and is relayed upstream unchanged.

object

required

Show properties

string

required

Always "builderLiquidations".

string

required

Your builder address (lowercase 0x-prefixed 42-character hex). Only liquidations whose closing order was routed through this builder are streamed.

boolean

When true, partial fills of the same liquidation within the same block are merged by (user, time, order_id) into one entry. Defaults to false on this channel.

string

Optional DEX filter - "xyz" or "main" (first-DEX fills only). Omit to stream across all DEXs.

Example

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

> {"method":"subscribe","subscription":{"type":"builderLiquidations","builder":"0xb84168cf3be63c6b8dad05ff5d755e97432ff80b"}}

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: "builderLiquidations",
      builder: "0xb84168cf3be63c6b8dad05ff5d755e97432ff80b",
    },
  }));
});

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

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": "builderLiquidations",
                "builder": "0xb84168cf3be63c6b8dad05ff5d755e97432ff80b",
            },
        }))
        async for raw in ws:
            msg = json.loads(raw)
            if msg.get("type") == "builderLiquidations":
                for address, fill in msg["liquidations"]:
                    liq = fill["liquidation"]
                    print("liquidated:", liq["liquidatedUser"],
                          "via", liq["method"], "—",
                          fill["coin"], fill["sz"], "@", fill["px"],
                          "builder:", fill["builder"])

asyncio.run(main())

Unsubscribe

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

{
  "method": "unsubscribe",
  "subscription": {
    "type": "builderLiquidations",
    "builder": "0xb84168cf3be63c6b8dad05ff5d755e97432ff80b"
  }
}

Streamed message

Each push keeps the upstream wire shape: type: "builderLiquidations" and a liquidations array of [address, fill] tuples - it is not normalized to the channel/fills shape used by the sibling channels. The address (and mirrored user field) is the wallet whose position was liquidated; liquidation.liquidatedUser repeats it, and builder is the attributed builder code.

{
  "type": "builderLiquidations",
  "liquidations": [
    [
      "0x742d35cc6634c0532925a3b844bc9e7595f7f2e2",
      {
        "coin": "ETH",
        "px": "2150.50",
        "sz": "1.5",
        "side": "A",
        "time": 1704067200000,
        "startPosition": "1.5",
        "dir": "Close Long",
        "closedPnl": "-125.50",
        "hash": "0xabc...def",
        "oid": 12345678,
        "crossed": true,
        "fee": "2.50",
        "tid": 87654321,
        "cloid": null,
        "builderFee": null,
        "deployerFee": null,
        "feeToken": "USDC",
        "builder": "0xb84168cf3be63c6b8dad05ff5d755e97432ff80b",
        "twapId": null,
        "liquidation": {
          "liquidatedUser": "0x742d35cc6634c0532925a3b844bc9e7595f7f2e2",
          "markPx": "2148.00",
          "method": "market"
        },
        "user": "0x742d35cc6634c0532925a3b844bc9e7595f7f2e2"
      }
    ]
  ]
}

string

Always "builderLiquidations".

array<[string, object]>

Tuples of [address, fill]. The address is the liquidated wallet. Same fill shape as userFills, with liquidation and builder always populated.

Show fill properties (delta vs userFills)

string

The builder code the closing order was routed through - matches the subscribed builder.

string | null

Builder fee earned on this fill, denominated in feeToken; null when none applies.

string | null

Deployer fee attributed to this fill, denominated in feeToken; null when none applies.

string

The liquidated wallet - mirrors the tuple address.

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) match the userFills shape.

TWAP-preceded liquidations are omitted. TWAP fills do not carry builder codes, so if a user’s last fill before liquidation was a TWAP slice, GoldRush cannot attribute the liquidation to a builder and no entry is emitted on this stream. Use the global liquidationFills stream if you need every liquidation regardless of builder attribution.

Errors

A missing or malformed builder field returns an error message:

{ "channel": "error", "data": "subscription builderLiquidations requires a 'builder' field" }

liquidationFills

stream a global, market-wide feed of every liquidation fill on HyperCore.

builderFills

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

allFills

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

userFills

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

Last reviewed: 2026-07-28

Foundational API

Hyperliquid API

JSON-RPC

Service Keys

builderLiquidations | Hyperliquid WebSocket API

Credit Cost

Processing

Endpoint

Example

Unsubscribe

Streamed message

Errors

liquidationFills

builderFills

allFills

userFills

Credit Cost

Processing

​Endpoint

​Subscribe

​Example

​Unsubscribe

​Streamed message

​Errors

​Related endpoints

liquidationFills

builderFills

allFills

userFills

Endpoint

Subscribe

Example

Unsubscribe

Streamed message

Errors

Related endpoints