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

# builderLiquidations | Hyperliquid WebSocket API

> Hyperliquid builderLiquidations: subscribe to real-time liquidation fills of your users.

> [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%2Fbuilder-liquidations).

> [!NOTE]
>
> * GoldRush-native. `builderLiquidations` is not exposed on `wss://api.hyperliquid.xyz/ws`. Pointing a client at the public endpoint with this subscription type will fail.
> * TWAP fills do not carry builder codes. If a user's last fill before liquidation was a TWAP fill, no builder liquidation notification will be sent.

## 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. `builder` is required.

**method** `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.

**subscription** `object` *required*

**properties**

**type** `string` *required*

Always `"builderLiquidations"`.

**builder** `string` *required*

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

**aggregateByTime** `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.

**dex** `string`

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

### Example

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

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

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

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

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

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

**type** `string`

Always `"builderLiquidations"`.

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

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

**fill properties (delta vs userFills)**

**builder** `string`

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

**builderFee** `string | null`

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

**deployerFee** `string | null`

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

**user** `string`

The liquidated wallet - mirrors the tuple `address`.

**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`) match the [`userFills`](https://goldrush.dev/docs/api-reference/hyperliquid-websocket/user-fills) shape.

> [!NOTE]
>
> **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`](https://goldrush.dev/docs/api-reference/hyperliquid-websocket/liquidation-fills) stream if you need every liquidation regardless of builder attribution.

## Errors

A missing or malformed `builder` field returns an error message:

```json theme={null}
{ "channel": "error", "data": "subscription builderLiquidations requires a 'builder' field" }
```

## Related endpoints

> [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] [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] [liquidationFills](https://goldrush.dev/docs/api-reference/hyperliquid-websocket/liquidation-fills.md)
>
> stream a global, market-wide feed of every liquidation fill on HyperCore.

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

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-07-28*


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