> ## 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: stream liquidation fills attributed to your builder code in real time.

<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](/docs/pricing-calculator?endpoint=%2Fapi-reference%2Fhyperliquid-websocket%2Fbuilder-liquidations).
</Tip>

<Info>
  * 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.
</Info>

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`](/docs/api-reference/hyperliquid-websocket/liquidation-fills) stream: same per-fill shape as [`userFills`](/docs/api-reference/hyperliquid-websocket/user-fills), with both the `liquidation` object and the `builder` attribution populated 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. `builder` is required.

<ParamField body="method" type="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.
</ParamField>

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

    <ResponseField name="builder" type="string" required>
      Your builder address (lowercase `0x`-prefixed 42-character hex). Only liquidations whose closing order was routed through this builder are streamed.
    </ResponseField>

    <ResponseField name="aggregateByTime" type="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.
    </ResponseField>

    <ResponseField name="dex" type="string">
      Optional DEX filter - `"xyz"` or `"main"` (first-DEX fills only). Omit to stream across all DEXs.
    </ResponseField>
  </Expandable>
</ParamField>

### Example

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

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

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

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

  <Expandable title="fill properties (delta vs userFills)">
    <ResponseField name="builder" type="string">The builder code the closing order was routed through - matches the subscribed `builder`.</ResponseField>
    <ResponseField name="builderFee" type="string | null">Builder fee earned on this fill, denominated in `feeToken`; `null` when none applies.</ResponseField>
    <ResponseField name="deployerFee" type="string | null">Deployer fee attributed to this fill, denominated in `feeToken`; `null` when none applies.</ResponseField>
    <ResponseField name="user" type="string">The liquidated wallet - mirrors the tuple `address`.</ResponseField>

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

<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`](/docs/api-reference/hyperliquid-websocket/liquidation-fills) stream if you need every liquidation regardless of builder attribution.
</Note>

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

<CardGroup cols={2}>
  <Card title="liquidationFills" href="/docs/api-reference/hyperliquid-websocket/liquidation-fills">stream a global, market-wide feed of every liquidation fill on HyperCore.</Card>
  <Card title="builderFills" href="/docs/api-reference/hyperliquid-websocket/builder-fills">stream live attributed fills for one or more builder addresses in real time.</Card>
  <Card title="allFills" href="/docs/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="userFills" href="/docs/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-07-28*