Stream Builder Liquidations

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.

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.

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

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

Message format

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.

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:

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

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.

When to use builder liquidations

Reach for builderLiquidations

Monitoring liquidations across your builder’s order flow: alerting your users when their positions are force-closed, or auditing liquidation outcomes per DEX.

Reach for liquidationFills instead

You want every liquidation on the venue regardless of builder attribution; the global stream costs the same and needs no builder address.

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.

Quickstart

Guides

Hyperliquid API

Stream Builder Liquidations

Message format

When to use builder liquidations

Reach for builderLiquidations

Reach for liquidationFills instead

Pair with other streams

​Subscribe

​Message format

​When to use builder liquidations

Reach for builderLiquidations

Reach for liquidationFills instead

​Pair with other streams

Subscribe

Message format

When to use builder liquidations

Pair with other streams