> For the complete documentation index, see [llms.txt](https://docs.hello.trade/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hello.trade/developer-tools/websocket-api/liquidation-auction.md).

# Liquidation Auction

When an account is liquidated, positions that cannot be closed against the live order book enter a short **manual-phase auction** before falling back to auto-deleveraging (ADL). The gateway broadcasts the unfilled position to all subscribed trading clients and collects signed claims for the duration of the auction window. The first claimant with sufficient margin becomes the counterparty and takes over the position at the liquidatee's zero-price.

See [Liquidation](/about/trading/liquidation.md) for where the auction sits in the overall liquidation waterfall.

***

## Eligibility

To participate in auctions a connection must:

1. **Authenticate** (see [Connection Management](/developer-tools/websocket-api/connection-management.md))
2. **Subscribe** to the trading stream via `subscribeTrading`

Subscribed connections automatically receive `manualLiquidationOffer` broadcasts — no separate subscription is required. Clients that are not subscribed when the auction opens never see the offer, and positions are routed straight to ADL if no client is subscribed.

***

## Auction Flow

```
Gateway                                          Subscribed client
   │                                                     │
   │  ── manualLiquidationOffer ───────────────────────► │   (broadcast to all
   │     {offerId, instrument, takerSide,                │    subscribed clients)
   │      quantity, frozenPrice, deadlineMs}             │
   │                                                     │
   │                                                     │  sign EIP-712 Order
   │                                                     │  matching offer terms
   │                                                     │
   │  ◄── claimLiquidation ───────────────────────────── │
   │      {offerId, signedOrder}                         │
   │                                                     │
   │  ── claimLiquidationAccepted ─────────────────────► │   (claim entered the
   │     {offerId}                                       │    auction)
   │                                                     │
   │   ... auction window closes (~500ms) ...            │
   │   pick winner, enter trade                          │
   │                                                     │
   │  ── executionReport ──────────────────────────────► │   (winner only: the
   │     (trade fill for the claimed position)           │    resulting fill)
```

1. Gateway broadcasts a `manualLiquidationOffer` to every subscribed client.
2. Interested clients reply with `claimLiquidation` carrying an EIP-712-signed order whose fields match the offer exactly.
3. Each accepted claim is acknowledged with `claimLiquidationAccepted`. The ack only confirms the claim entered the auction — it is **not** a win.
4. After the auction window closes, the gateway selects a winner and enters the trade. The winner observes the resulting fill on the [execution report](/developer-tools/websocket-api/execution-reports.md) stream. Losing claimants receive nothing further.

***

## manualLiquidationOffer

Broadcast pushed to all subscribed clients when a position enters the manual-phase auction.

**Direction:** Gateway → Client

### Message

```json
{
  "type": "manualLiquidationOffer",
  "offerId": "550e8400-e29b-41d4-a716-446655440000",
  "instrumentId": 42,
  "instrument": "NVDA",
  "takerSide": "Buy",
  "quantity": "100",
  "frozenPrice": "498.50",
  "deadlineMs": 1705600000200
}
```

### Fields

| Field          | Type   | Description                                                                                      |
| -------------- | ------ | ------------------------------------------------------------------------------------------------ |
| `offerId`      | string | UUID identifying this auction. Echo it back in `claimLiquidation`.                               |
| `instrumentId` | u32    | Numeric instrument ID of the position being liquidated.                                          |
| `instrument`   | string | Instrument symbol (e.g. `NVDA`).                                                                 |
| `takerSide`    | string | `Buy` or `Sell` — the side **you** take if you win (opposite of the liquidatee's closing side).  |
| `quantity`     | string | Quantity available to claim. Sign your order's `size` according to `takerSide`.                  |
| `frozenPrice`  | string | The execution (zero) price. Your signed order's `limitPrice` must equal this value.              |
| `deadlineMs`   | i64    | Unix timestamp (ms) at which the auction window closes. Claims arriving after this are rejected. |

***

## claimLiquidation

Submit a claim for an open offer. Fast-pathed past the request queue so it is not delayed behind other order operations during the short auction window.

**Authentication Required:** Yes

### Request

```json
{
  "type": "claimLiquidation",
  "offerId": "550e8400-e29b-41d4-a716-446655440000",
  "marginMode": "Cross",
  "signedOrder": {
    "sig": "0x...",
    "payload": "0x00..."
  }
}
```

**Note:** `signedOrder` carries an EIP-712 `Order` payload (type discriminator `0x00`), identical in shape to the `placeOrder` signature. See [Signatures - Orders](/developer-tools/signatures.md#orders).

### Request Fields

| Field         | Type   | Required | Description                                                                                |
| ------------- | ------ | -------- | ------------------------------------------------------------------------------------------ |
| `offerId`     | string | Yes      | The `offerId` from the `manualLiquidationOffer` you are claiming.                          |
| `marginMode`  | string | Yes      | Must be `Cross` — isolated claims are rejected. Must match the signed order's margin flag. |
| `signedOrder` | Object | Yes      | EIP-712 signed `Order` whose fields match the offer terms exactly.                         |

### Signed Order Requirements

The gateway validates the signed order against the offer terms. All of the following must hold or the claim is rejected:

| Order field  | Required value                                                                                                                                                                                                                         |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `account`    | Your authenticated wallet (the recovered signer must also match this address).                                                                                                                                                         |
| `market`     | The offer's `instrumentId`.                                                                                                                                                                                                            |
| `size`       | The offer's `quantity`, signed per `takerSide` (positive = `Buy`, negative = `Sell`).                                                                                                                                                  |
| `limitPrice` | The offer's `frozenPrice`.                                                                                                                                                                                                             |
| `deadline`   | A Unix timestamp (seconds) at least **1 hour** in the future — the claim validates as an IOC order, so the standard 1-hour minimum applies. A claim whose own signed deadline has already passed when the winner is picked is skipped. |
| `flags`      | Regular cross-margin order flags (not a managed close, not reduce-only).                                                                                                                                                               |

The order is treated as a `Limit` / `IOC` order. For payload encoding and flag bits, see [Signatures - Orders](/developer-tools/signatures.md#orders).

### Success Response

```json
{
  "type": "claimLiquidationAccepted",
  "offerId": "550e8400-e29b-41d4-a716-446655440000"
}
```

`claimLiquidationAccepted` only confirms your claim was validated and entered the auction. **Winning is determined after the window closes.** Once it resolves, every claimant whose claim was accepted receives a private `claimLiquidationResult` message (see below). Winners additionally receive the resulting position fill on the [execution report](/developer-tools/websocket-api/execution-reports.md) stream.

### Claim Result

After the auction resolves, the gateway sends a `claimLiquidationResult` to **each accepted claimant** — winners (`won: true`) and losers (`won: false`) alike. It is delivered privately to the claimant's authenticated connection(s).

```json
{
  "type": "claimLiquidationResult",
  "offerId": "550e8400-e29b-41d4-a716-446655440000",
  "won": false
}
```

| Field     | Type    | Description                                              |
| --------- | ------- | -------------------------------------------------------- |
| `offerId` | string  | UUID of the liquidation offer that was claimed.          |
| `won`     | boolean | `true` if your claim won the auction, `false` otherwise. |

Winners also receive the resulting position fill on the [execution report](/developer-tools/websocket-api/execution-reports.md) stream.

### Common Errors

| Code | Cause                                                                                                 |
| ---- | ----------------------------------------------------------------------------------------------------- |
| 4000 | Invalid request — unknown `offerId`, auction already closed, or a duplicate claim for the same offer. |
| 4001 | Signature verification failed, or `signed.account` does not match the authenticated wallet.           |
| 4003 | Not authenticated (authenticate before claiming).                                                     |
| 4029 | Rate limit exceeded.                                                                                  |
| 4100 | Insufficient margin to take the position (your account cannot absorb the claimed quantity).           |

***

## Winner Selection

Claims are filled **first-come, first-served** by gateway receive time. After the window closes, the gateway walks claims in arrival order and picks the first one whose signed `deadline` has not passed and whose margin can absorb the position. The winner is entered as the maker-side counterparty against the liquidatee at `frozenPrice`. If no claim is eligible, the position falls through to ADL.

Only one claim per wallet per offer is accepted — a duplicate is rejected with `4000`.