> ## Documentation Index
> Fetch the complete documentation index at: https://docs.uniblock.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Stream Builder Liquidations

> Stream Hyperliquid liquidation fills attributed to your builder code in real time, with builder-fee data and liquidation metadata attached.

The `builderLiquidations` channel is a GoldRush-native stream of liquidation fills attributed to a specific **builder code**. Attribution follows the liquidated user's last fill before liquidation: when that fill carried your builder code, the liquidation is emitted on your stream. Think of it as the intersection of `liquidationFills` and `builderFills`: you only receive liquidations attributed to your builder address, with the `builder` and `liquidation` metadata populated on every entry. Use it to monitor liquidations across your builder's order flow without filtering the global stream yourself.

<Info>
  `builderLiquidations` requires a `builder` address; there's no wildcard
  subscription. It's billed at **1 credit/min** (5,000 CU/min), the same rate as
  the other account streams. See
  [pricing](/guides/hyperliquid/websockets/overview#pricing).
</Info>

## Subscribe

```json theme={null}
{
  "method": "subscribe",
  "subscription": {
    "type": "builderLiquidations",
    "builder": "0xb84168cf3be63c6b8dad05ff5d755e97432ff80b"
  }
}
```

| Field             | Required | Meaning                                                                                   |
| ----------------- | -------- | ----------------------------------------------------------------------------------------- |
| `builder`         | Yes      | Builder address whose routed liquidation fills you want, as lowercase `0x`-prefixed hex.  |
| `aggregateByTime` | No       | Merge partial fills from the same liquidation within the same block. Defaults to `false`. |
| `dex`             | No       | Filter to a single DEX; omit to receive fills from all DEXs.                              |

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

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

## Message format

<Note>
  Unlike the other channels on this connection, `builderLiquidations` messages
  keep the upstream wire shape and are **not** wrapped in the `channel`/`data`
  envelope: match on `msg.type === "builderLiquidations"` rather than
  `msg.channel`.
</Note>

Each message carries an array of `[address, fill]` tuples, where the address is the **liquidated wallet** and the fill is the liquidation attributed to your builder:

```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,
        "feeToken": "USDC",
        "builder": "0xb84168cf3be63c6b8dad05ff5d755e97432ff80b",
        "builderFee": null,
        "deployerFee": null,
        "twapId": null,
        "liquidation": {
          "liquidatedUser": "0x742d35cc6634c0532925a3b844bc9e7595f7f2e2",
          "markPx": "2148.00",
          "method": "market"
        },
        "user": "0x742d35cc6634c0532925a3b844bc9e7595f7f2e2"
      }
    ]
  ]
}
```

Fills follow the standard Hyperliquid fill shape (`coin`, `px`, `sz`, `side`, `time`, `dir`, `closedPnl`, and so on), extended with the fields that make this stream useful:

| Field                        | Meaning                                                                |
| ---------------------------- | ---------------------------------------------------------------------- |
| `builder`                    | The builder code that routed the closing order.                        |
| `builderFee`                 | Builder fee earned on the fill, in `feeToken`; `null` if none.         |
| `deployerFee`                | Deployer fee attributed to the fill; `null` if none.                   |
| `liquidation.liquidatedUser` | The wallet that was liquidated (mirrors the tuple address and `user`). |
| `liquidation.markPx`         | Mark price at liquidation time.                                        |
| `liquidation.method`         | How the position was closed: `"market"` or `"backstop"`.               |

<Warning>
  TWAP fills don't carry builder codes. If a user's last fill before liquidation
  was a TWAP fill, no builder liquidation is emitted for it.
</Warning>

## When to use builder liquidations

<CardGroup cols={2}>
  <Card title="Reach for builderLiquidations" icon="circle-check">
    Monitoring liquidations across your builder's order flow: alerting your
    users when their positions are force-closed, or auditing liquidation
    outcomes per DEX.
  </Card>

  <Card title="Reach for liquidationFills instead" icon="circle-half-stroke">
    You want every liquidation on the venue regardless of builder attribution;
    the global stream costs the same and needs no `builder` address.
  </Card>
</CardGroup>

## Pair with other streams

`builderLiquidations` tells you which of your builder's positions were force-closed; the surrounding channels fill in the rest:

* `builderFills`: every fill attributed to your builder, not just liquidations.
* `liquidationFills`: the global liquidation stream across all builders.
* `userFills` / `orderUpdates`: per-wallet fills and order lifecycle events.

See the full list in the [WebSocket overview](/guides/hyperliquid/websockets/overview#available-channels).