> For the complete documentation index, see [llms.txt](https://docs.hydromancer.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hydromancer.xyz/readme/rest-api/historical-data/liquidationhistorybytime.md).

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

{% hint style="info" %}
**All data is fully available from 28-07-2025. Hydromancer performed a full backfill of fills offered by the native Hyperliquid API. The result includes full historical data for most traders, except some very high-volume addresses. TWAP fills are included from 02-08-2025.**
{% endhint %}

## POST Request

<table><thead><tr><th width="120">Field</th><th width="119">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>type</code></td><td>string</td><td>Must be <code>"liquidationHistoryByTime"</code></td></tr><tr><td><code>coin</code></td><td>string</td><td>i.e. "BTC", "ETH", or a HIP-3 market like "xyz:JPY". Omit for market-wide (optional)</td></tr><tr><td><code>startTime</code></td><td>int</td><td>Start time in ms, inclusive (optional)</td></tr><tr><td><code>endTime</code></td><td>int</td><td>End time in ms, inclusive (optional)</td></tr><tr><td><code>limit</code></td><td>int</td><td>Max results to return, default 500, max 1000 (optional)</td></tr></tbody></table>

{% tabs %}
{% tab title="cURL" %}

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

{% endtab %}

{% tab title="Python" %}

```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())
```

{% endtab %}

{% tab title="Javascript" %}

```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);
}
```

{% endtab %}
{% endtabs %}

***

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

<details>

<summary>Response</summary>

```json
[
    {
        "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
    }
]
```

</details>