liquidationFills

Stream all liquidation fills.

Every live data message includes both routing identifiers with the same value:

{"type": "liquidationFills", "channel": "liquidationFills"}

Other payload fields are omitted above. Existing clients may continue routing on either field.

💧New endpoint - this endpoint is not a part of original Hyperliquid API and is added by us for builder convenience.

Subscribe

{ 
    "type": "subscribe",
    "subscription": {
        "type": "liquidationFills",
        "aggregateByTime": true // optional
    }
} 

Unsubscribe

{ 
    "type": "unsubscribe",
    "subscription": {
        "type": "liquidationFills",
        "aggregateByTime": true // optional
    }
}

Fill data format

Each fill contains an address and fill details. Fills are batched per block.

Reconnection Note: When reconnecting with a session, replay and live events may overlap. Deduplicate using (time, txIndex) - skip fills where this tuple is at or before your last processed fill. See Session Management for details.

{
  "type": "liquidationFills",
  "channel": "liquidationFills",
  "seq": 1,
  "cursor": "500:1704067200000:3",
  "fills": [
    [
      "0x742d35cc6634c0532925a3b844bc9e7595f7f2e2",
      {
        "coin": "ETH",
        "px": "2150.50",                    // price
        "sz": "1.5",                        // size
        "side": "B",                        // B=buy, A=sell
        "time": 1704067200000,              // timestamp (ms)
        "startPosition": "1.5",             // position before fill
        "dir": "Open Long",                 // direction
        "closedPnl": "125.50",              // realized PnL
        "hash": "0xabc...def",              // fill hash
        "oid": 12345678,                    // order ID
        "crossed": false,                   // was crossed
        "fee": "2.50",                      // fee amount
        "tid": 87654321,                    // trade ID
        "cloid": "client-123",              // client order ID (optional)
        "feeToken": "USDC",                 // fee token
        "liquidation": {                    // liquidation details
          "liquidatedUser": "0x...",        // address of liquidated user
          "markPx": "2148.75",              // mark price at liquidation
          "method": "market"                // liquidation method ("market" or "backstop")
        },
        "twapId": null,                     // TWAP ID, null if not a TWAP
        "txIndex": 3                        // transaction index within block
      }
    ]
  ]
}

Examples

Javascript

const WebSocket = require('ws');

const ws = new WebSocket(`wss://api.hydromancer.xyz/ws?token=${process.env.HYDROMANCER_API_KEY}`);

ws.on('message', (data) => {
    const msg = JSON.parse(data);

    if (msg.type === 'connected') {
        // Subscribe to fills
        ws.send(JSON.stringify({
            type: 'subscribe',
            subscription: {
                type: 'liquidationFills'
            }
        }));
    } else if (msg.type === 'ping') {
        ws.send(JSON.stringify({ type: 'pong' }));
    } else if (msg.type === 'liquidationFills') {
        console.log(`Received ${msg.fills.length} liquidations`);
    }
});

Python

import websocket
import json
import os

def on_message(ws, message):
    msg = json.loads(message)

    if msg['type'] == 'connected':
        ws.send(json.dumps({
            "type": "subscribe",
            "subscription": {
                "type": "liquidationFills"
            }
        }))
    elif msg['type'] == 'ping':
        print("Received ping, sending pong")
        ws.send(json.dumps({'type': 'pong'}))
    elif msg['type'] == 'liquidationFills':
        print(f"Received {len(msg['fills'])} liquidations")
    elif msg['type'] == 'subscriptionUpdate':
        print(f"Subscription update: {msg}")
    elif msg['type'] == 'error':
        print(f"Error: {msg}")
    else:
        print(f"Unknown message type: {msg}")

ws = websocket.WebSocketApp(
    f"wss://api.hydromancer.xyz/ws?token={os.environ.get('HYDROMANCER_API_KEY')}",
    on_message=on_message
)
ws.run_forever()

Error messages:

{
    "type": "error",
    "message": "Invalid API key"
}

Common errors

1. Connection timeout - Respond to ping messages

2. Too many subscriptions - Maximum 1 subscription per API key

3. Invalid API key