> 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 single coin or across all markets. The most recent events are returned first.

{% hint style="info" %}
**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.**
{% 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>