liquidationHistoryByTime

Get historical liquidation events for a coin or market-wide

Get historical liquidation events, for a single coin or across all markets. The most recent events are returned first.

All data fully available from 28-07-2025. We have performed a full backfill of all fills the HL native API offered, meaning that we have full historical data for most traders except for some very high volume addresses. TWAP fills are included from 02-08-2025.

POST Request

Field	Type	Description
type	string	Must be "liquidationHistoryByTime"
coin	string	i.e. "BTC", "ETH", or a HIP-3 market like "xyz:JPY". Omit for market-wide (optional)
startTime	int	Start time in ms, inclusive (optional)
endTime	int	End time in ms, inclusive (optional)
limit	int	Max results to return, default 500, max 1000 (optional)

cURL

curl -X POST https://api.hydromancer.xyz/info \
  -H "Authorization: Bearer $HYDROMANCER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "liquidationHistoryByTime",
    "coin": "BTC"
  }'

Python

import requests
import os

response = requests.post(
    'https://api.hydromancer.xyz/info',
    json={
        'type': 'liquidationHistoryByTime',
        'coin': 'BTC'
    },
    headers={
        'Authorization': f'Bearer {os.environ.get("HYDROMANCER_API_KEY")}',
        'Content-Type': 'application/json'
    }
)

print(response.json())

Javascript

import axios from 'axios';

try {
    const response = await axios.post('https://api.hydromancer.xyz/info', {
        type: 'liquidationHistoryByTime',
        coin: 'BTC'
    }, {
        headers: {
            'Authorization': `Bearer ${process.env.HYDROMANCER_API_KEY}`,
            'Content-Type': 'application/json'
        }
    });

    console.log(response.data);
} catch (error) {
    console.error('Error:', error.message);
}

---

Response Fields

Each event is the liquidated user's fill. side is "A" when a long was liquidated (forced sell) and "B" when a short was liquidated (forced buy).

Field	Type	Description
coin	string	Asset symbol
user	string	Address that was liquidated
px	string	Fill price
sz	string	Fill size
side	string	"A" = long liquidated, "B" = short liquidated
time	int	Timestamp (ms)
startPosition	string	Position size before the fill
dir	string	Direction, e.g. "Close Long"
closedPnl	string	Realized PnL on the fill
hash	string	Transaction hash
oid	int	Order id
crossed	bool	Whether the fill crossed the book
fee	string	Fee paid
tid	int	Trade id
cloid	string?	Client order ID (optional)
builderFee	string?	Builder fee (optional)
deployerFee	string?	Deployer fee (optional, HIP-3 fills only)
priorityGas	string?	Priority gas fee in HYPE (optional)
feeToken	string	Token the fee was paid in
builder	string?	Builder address (optional)
twapId	int?	TWAP order ID (null if not a TWAP fill)
liquidation	object	Liquidation detail (see below)
txIndex	int	Intra-block ordering index

liquidation object:

Field	Type	Description
liquidatedUser	string	Address that was liquidated
markPx	string	Mark price at liquidation
method	string	"market" (closed against the order book) or "backstop" (absorbed by the backstop liquidator at bankruptcy price)

Response

[
    {
        "coin": "BTC",
        "px": "50000.00",
        "sz": "1.0",
        "side": "A",
        "time": 1762398000007,
        "startPosition": "1.0",
        "dir": "Close Long",
        "closedPnl": "-1200.00",
        "hash": "0x1234567890abcdef",
        "oid": 123456,
        "crossed": true,
        "fee": "25.00",
        "tid": 789012,
        "cloid": null,
        "builderFee": null,
        "deployerFee": null,
        "priorityGas": null,
        "feeToken": "USDC",
        "builder": null,
        "twapId": null,
        "user": "0xabc...",
        "liquidation": {
            "liquidatedUser": "0xabc...",
            "markPx": "50000.00",
            "method": "market"
        },
        "txIndex": 12
    }
]