Liquidation Auction

Real-time auction that lets subscribed trading clients claim positions during the manual phase of a liquidation.

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 for where the auction sits in the overall liquidation waterfall.

---

Eligibility

To participate in auctions a connection must:

1. Authenticate (see Connection Management)

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

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

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

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.

Success Response

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

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