# builderLiquidations stream

> HyperCore private-preview documentation.

> For the complete documentation index, see [llms.txt](/docs/llms.txt).

<Callout intent="info">
  This API is in private preview. Target September 2026; timing is subject to change.
</Callout>


# builderLiquidations stream

Streams liquidation fills associated with a builder.

## Subscribe

```json
{
  "method": "subscribe",
  "subscription": {
    "type": "builderLiquidations",
    "builder": "0x2222222222222222222222222222222222222222",
    "aggregateByTime": true
  }
}
```

## Event envelope

```json
{
  "type": "builderLiquidations",
  "channel": "builderLiquidations",
  "seq": 1,
  "cursor": "500:1704067200000:3",
  "liquidations": [[
    "0x1111111111111111111111111111111111111111",
    {
      "coin": "ETH",
      "px": "2150.50",
      "sz": "1.5",
      "side": "B",
      "time": 1704067200000,
      "startPosition": "1.5",
      "dir": "Open Long",
      "closedPnl": "125.50",
      "hash": "0xabc...def",
      "oid": 12345678,
      "crossed": false,
      "fee": "2.50",
      "tid": 87654321,
      "cloid": "client-123",
      "builderFee": null,
      "deployerFee": null,
      "feeToken": "USDC",
      "builder": "0x2222222222222222222222222222222222222222",
      "twapId": null,
      "txIndex": 1,
      "liquidation": {
        "liquidatedUser": "0x3333333333333333333333333333333333333333",
        "markPx": "2148.00",
        "method": "market"
      }
    }
  ]]
}
```

## Payload fields

| Field | Type | Description |
| --- | --- | --- |
| type | string | Event type. |
| channel | string | Routing channel for the event. |
| seq | integer | Monotonic sequence number for the stream. |
| cursor | string | Resume cursor for the event position. |
| liquidations | array | Pairs of user address and liquidation fill. |
| liquidations[] | tuple | User address followed by a liquidation fill. |
| liquidations[]\[0] | string | Address associated with the fill. |
| liquidations[]\[1] | object | Liquidation fill record. |
| liquidations[]\[1].coin | string | Market symbol. |
| liquidations[]\[1].px | string | Fill price. |
| liquidations[]\[1].sz | string | Filled size. |
| liquidations[]\[1].side | string | Side code: A is ask/sell; B is bid/buy. |
| liquidations[]\[1].time | integer | Fill time in milliseconds. |
| liquidations[]\[1].startPosition | string | Position size before the fill. |
| liquidations[]\[1].dir | string | Position-direction classification for the fill. |
| liquidations[]\[1].closedPnl | string | Realized profit and loss from the fill. |
| liquidations[]\[1].hash | string | Transaction hash containing the fill. |
| liquidations[]\[1].oid | integer | Order identifier. |
| liquidations[]\[1].crossed | boolean | Whether the fill crossed the book. |
| liquidations[]\[1].fee | string | Fee charged for the fill. |
| liquidations[]\[1].tid | integer | Trade identifier. |
| liquidations[]\[1].cloid | string | Client-supplied order identifier, when present. |
| liquidations[]\[1].builderFee | string | Builder fee charged for the fill, when present. |
| liquidations[]\[1].deployerFee | string | Deployer fee charged for the fill, when present. |
| liquidations[]\[1].feeToken | string | Token used to pay the fee. |
| liquidations[]\[1].builder | string | Builder address associated with the fill. |
| liquidations[]\[1].twapId | integer \| null | TWAP identifier, when the fill belongs to a TWAP. |
| liquidations[]\[1].txIndex | integer | Index of the transaction within its block. |
| liquidations[]\[1].liquidation | object | Liquidation details. |
| liquidations[]\[1].liquidation.liquidatedUser | string | Address of the liquidated user. |
| liquidations[]\[1].liquidation.markPx | string | Mark price at liquidation. |
| liquidations[]\[1].liquidation.method | string | Liquidation method: market or backstop. |

## Behavior

The stream batches liquidation fills for the requested builder. The aggregateByTime parameter controls time aggregation, and the cursor identifies the event position for resumption.

## Unsubscribe

```json
{
  "method": "unsubscribe",
  "subscription": {
    "type": "builderLiquidations",
    "builder": "0x2222222222222222222222222222222222222222",
    "aggregateByTime": true
  }
}
```

## Resume

To resume a stream, supply cursor in the subscription object. Store and return the cursor unmodified.