# Liquidation Data

The Liquidation Data endpoints give you structured access to liquidation risk and exposure data across the Hyperliquid ecosystem. These endpoints allow you to monitor where forced liquidations are most likely to occur, identify assets and cohorts under elevated pressure, and build a clearer picture of market-wide risk before it materializes.

***

### Get Liquidation Fills

`/api/external/fills/liquidation`

{% hint style="success" %}
**Unique to HyperTracker Users**

HyperTracker indexes liquidation fills in a structured, queryable format so they can be consumed directly through the API without needing to parse raw on-chain data or maintain custom Hyperliquid infrastructure.
{% endhint %}

Returns raw liquidation fill events from Hyperliquid, ordered from most recent to oldest.

This endpoint can be called with no query parameters to return the latest liquidation fills across all markets. You can optionally filter by coin, address, side, or time range, and use `nextCursor` to paginate through older results.

<details>

<summary>Path Parameters</summary>

<table><thead><tr><th width="115.37890625">Parameter</th><th width="83.78125">Type</th><th width="105.984375">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>limit</code></td><td>number</td><td>No</td><td>Number of liquidation fills to return. </td></tr><tr><td><code>coin</code></td><td>string</td><td>No</td><td>Filter results by coin symbol. Example: <code>ETH</code>, <code>BTC</code>, <code>HYPE</code>, <code>cash:HOOD</code>, <code>xyz:MSTR</code>. If omitted, results are returned across all markets.</td></tr><tr><td><code>address</code></td><td>string</td><td>No</td><td>Filter results by wallet address</td></tr><tr><td><code>start</code></td><td>string</td><td>No</td><td>Start of the query period as an ISO timestamp. Optional. If omitted, the endpoint returns the latest liquidation fills.</td></tr><tr><td><code>end</code></td><td>string</td><td>No</td><td>End of the query period as an ISO timestamp. Can only be provided together with <code>start</code>. Must be later than <code>start</code> and within 3 months after <code>start</code>.</td></tr><tr><td><code>side</code></td><td>string</td><td>No</td><td>Filter by fill side. <code>A</code> = ask/sell, <code>B</code> = bid/buy.</td></tr><tr><td><code>nextCursor</code></td><td>string</td><td>No</td><td>Pagination cursor returned from a previous response. Use this to fetch the next page of older liquidation fills.</td></tr></tbody></table>

</details>

Request Examples

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

```bash
curl -X GET \
  'https://ht-api.coinmarketman.com/api/external/fills/liquidation' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://ht-api.coinmarketman.com/api/external/fills/liquidation"

headers = {
    "accept": "application/json",
    "Authorization": "Bearer YOUR_API_KEY"
}

params = {
    "limit": 10
}

response = requests.get(url, headers=headers, params=params)
data = response.json()

print(data)
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const url = new URL("https://ht-api.coinmarketman.com/api/external/fills/liquidation");

url.searchParams.append("limit", "10");

const response = await fetch(url, {
  method: "GET",
  headers: {
    "accept": "application/json",
    "Authorization": "Bearer YOUR_API_KEY"
  }
});

const data = await response.json();

console.log(data);
```

{% endtab %}
{% endtabs %}

Response

> **200 Success:** Returns a list of liquidation fills matching the selected filters, ordered from most recent to oldest.

<details>

<summary>Response Example</summary>

{% code expandable="true" %}

```json
{
  "fills": [
    {
      "oid": 446603091844,
      "address": "0x3160fb45324397c607528892eef27ad183768d7f",
      "coin": "cash:HOOD",
      "fullCoinName": "cash:HOOD",
      "fillType": "perp",
      "px": 81.697,
      "sz": 23.103,
      "side": "B",
      "time": "2026-05-28T17:27:35.681Z",
      "startPosition": -23.103,
      "dir": "Close Short",
      "closedPnl": -148.459878,
      "hash": "0x8673be950ab26d8d87ed043c710d0c02027f007aa5b58c5f2a3c69e7c9b64778",
      "crossed": true,
      "fee": 0.16987,
      "builderFee": 0,
      "tid": 926452912678690,
      "feeToken": "USDT0",
      "builder": "",
      "liquidatedUser": "0x3160fb45324397c607528892eef27ad183768d7f",
      "liquidationMarkPx": 81.633,
      "liquidationMethod": "market"
    }
  ],
  "nextCursor": "eyJpZCI6IjQzNTUyNzQ0NjUxMDY0NjA3MDYiLCJ0aW1lIjoxNzc5OTg5MjIwNzYyfQ..."
}
```

{% endcode %}

</details>

***

### Export Liquidation Heatmap

`/api/external/exports/coins/{coin}/liquidation-heatmap`

<figure><img src="/files/Pp4qbUSB76ZehrWDT5zY" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}

<p align="center"><em>Liquidation heatmap from</em> <a href="https://app.coinmarketman.com/hypertracker/perps"><em>Perps</em></a> <em>page</em></p>
{% endhint %}

{% hint style="success" %}
**Unique to HyperTracker Users**

HyperTracker indexes liquidation fills in a structured, queryable format so they can be consumed directly through the API without needing to parse raw on-chain data or maintain custom Hyperliquid infrastructure.
{% endhint %}

Returns a temporary, pre-signed download URL for exporting liquidation heatmap data for a selected coin. The exported file contains price-bin ranges with estimated liquidation value, position count, and the most impacted segment for each bin, matching the liquidation heatmap data shown on the HyperTracker Perps page.

The returned download link expires quickly, usually within about 120 seconds, so it should be used shortly after it is generated.

<details>

<summary>Path Parameters</summary>

<table><thead><tr><th>Parameter</th><th>Type</th><th width="296.494140625">Description</th></tr></thead><tbody><tr><td><code>coin</code></td><td><code>string</code></td><td>Coin symbol (case-insensitive), for example <code>BTC</code>, <code>ETH</code>.</td></tr></tbody></table>

</details>

Request Examples

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

```
curl --request GET \
  --url 'https://ht-api.coinmarketman.com/api/external/exports/coins/BTC/liquidation-heatmap' \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --location
```

{% endtab %}

{% tab title="Python" %}

```
import requests

response = requests.get(
    'https://ht-api.coinmarketman.com/api/external/exports/coins/BTC/liquidation-heatmap',
    headers={'Authorization': 'Bearer YOUR_API_TOKEN'},
    allow_redirects=True
)

export_data = response.json()
```

{% endtab %}
{% endtabs %}

Response

> 200 Success: Returns a temporary pre-signed download URL for the selected coin’s liquidation heatmap export.

<details>

<summary>Response Example</summary>

{% code expandable="true" %}

```
{
    "coin": "BTC",
    "heatmap": [
        {
            "coin": "BTC",
            "priceBinIndex": 0,
            "priceBinStart": 0,
            "priceBinEnd": 467.97,
            "liquidationValue": 71527563.34585,
            "positionsCount": 3980,
            "mostImpactedSegment": 7
        },
        {
            "coin": "BTC",
            "priceBinIndex": 1,
            "priceBinStart": 467.97,
            "priceBinEnd": 935.94,
            "liquidationValue": 397057.72595,
            "positionsCount": 36,
            "mostImpactedSegment": 4
        },
        {
            "coin": "BTC",
            "priceBinIndex": 2,
            "priceBinStart": 935.94,
            "priceBinEnd": 1403.91,
            "liquidationValue": 146671.93735,
            "positionsCount": 43,
            "mostImpactedSegment": 13
        },
        {
            "coin": "BTC",
            "priceBinIndex": 3,
            "priceBinStart": 1403.91,
            "priceBinEnd": 1871.88,
            "liquidationValue": 57800.5346,
            "positionsCount": 25,
            "mostImpactedSegment": 12
        },
        {
            "coin": "BTC",
            "priceBinIndex": 4,
            "priceBinStart": 1871.88,
            "priceBinEnd": 2339.85,
            "liquidationValue": 13392.52145,
            "positionsCount": 26,
            "mostImpactedSegment": 1
        },
        {
            "coin": "BTC",
            "priceBinIndex": 5,
            "priceBinStart": 2339.85,
            "priceBinEnd": 2807.82,
            "liquidationValue": 518029.53085,
            "positionsCount": 47,
            "mostImpactedSegment": 4
        },
        {
            "coin": "BTC",
            "priceBinIndex": 6,
            "priceBinStart": 2807.82,
            "priceBinEnd": 3275.79,
            "liquidationValue": 9412.4366,
            "positionsCount": 11,
            "mostImpactedSegment": 12
        },
        {
            "coin": "BTC",
            "priceBinIndex": 7,
            "priceBinStart": 3275.79,
            "priceBinEnd": 3743.76,
            "liquidationValue": 3156268.12215,
            "positionsCount": 17,
            "mostImpactedSegment": 14
        },
        {
            "coin": "BTC",
            "priceBinIndex": 8,
            "priceBinStart": 3743.76,
            "priceBinEnd": 4211.73,
            "liquidationValue": 96683.38195,
            "positionsCount": 13,
            "mostImpactedSegment": 12
        },
        {
            "coin": "BTC",
            "priceBinIndex": 9,
            "priceBinStart": 4211.73,
            "priceBinEnd": 4679.7,
            "liquidationValue": 125770.83725,
            "positionsCount": 15,
            "mostImpactedSegment": 3
        },
        {
            "coin": "BTC",
            "priceBinIndex": 10,
            "priceBinStart": 4679.7,
            "priceBinEnd": 5147.67,
            "liquidationValue": 17144.08095,
            "positionsCount": 11,
            "mostImpactedSegment": 1
        },
        {
            "coin": "BTC",
            "priceBinIndex": 11,
            "priceBinStart": 5147.67,
            "priceBinEnd": 5615.64,
            "liquidationValue": 5280.2615,
            "positionsCount": 8,
            "mostImpactedSegment": 1
        },
        {
            "coin": "BTC",
            "priceBinIndex": 12,
            "priceBinStart": 5615.64,
            "priceBinEnd": 6083.61,
            "liquidationValue": 107605.80175,
            "positionsCount": 9,
            "mostImpactedSegment": 3
        },
        {
            "coin": "BTC",
            "priceBinIndex": 13,
            "priceBinStart": 6083.61,
            "priceBinEnd": 6551.58,
            "liquidationValue": 88262.2618,
            "positionsCount": 13,
            "mostImpactedSegment": 3
        },
        {
            "coin": "BTC",
            "priceBinIndex": 14,
            "priceBinStart": 6551.58,
            "priceBinEnd": 7019.55,
            "liquidationValue": 71461.35885,
            "positionsCount": 20,
            "mostImpactedSegment": 2
        },
        {
            "coin": "BTC",
            "priceBinIndex": 15,
            "priceBinStart": 7019.55,
            "priceBinEnd": 7487.52,
            "liquidationValue": 31923.3535,
            "positionsCount": 16,
            "mostImpactedSegment": 1
        },
        {
            "coin": "BTC",
            "priceBinIndex": 16,
            "priceBinStart": 7487.52,
            "priceBinEnd": 7955.49,
            "liquidationValue": 844530.63995,
            "positionsCount": 12,
            "mostImpactedSegment": 5
        },
        {
            "coin": "BTC",
            "priceBinIndex": 17,
            "priceBinStart": 7955.49,
            "priceBinEnd": 8423.46,
            "liquidationValue": 355376.418,
            "positionsCount": 14,
            "mostImpactedSegment": 9
        },
```

{% endcode %}

</details>

***

### Get Liquidation Risk by Asset

`api/external/`{`segmentId`}`/assets/liquidation-risk`

<figure><img src="/files/cICdqAi6kyx3SXA7exKv" alt=""><figcaption></figcaption></figure>

{% hint style="success" %}
**Unique to HyperTracker Users**
{% endhint %}

*Retrieves the percentage of open interest at high liquidation risk for each asset within a given segment (cohort). It shows how much of the total exposure is close to being liquidated.*\
\&#xNAN;*For example: If BTC has $1,000,000 in total open interest and $100,000 of that is within 75% of the liquidation threshold, then the liquidation risk by asset for XYZ is 10%.*

*The endpoint can return up to 500 results per request. Lower limits usually result in faster response times.*

{% hint style="info" %}
Understanding Liquidation Risk\
Liquidation risk indicates how close positions are to being liquidated. This data is crucial for monitoring market health and identifying potential cascading liquidation scenarios.
{% endhint %}

<details>

<summary>Path Parameters</summary>

| Parameter              | Type     | Description                                                                                       |
| ---------------------- | -------- | ------------------------------------------------------------------------------------------------- |
| `segmentId [required]` | `number` | The cohort ID to analyze liquidation risk for. [See Legend.](broken://pages/2OgdlIjFaVrmIkriNBrm) |

</details>

<details>

<summary>Query Parameters</summary>

| Parameter | Type     | Description                           |
| --------- | -------- | ------------------------------------- |
| `offset`  | `number` | The number of items to skip           |
| `limit`   | `number` | The maximum number of items to return |

</details>

Request Examples

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

```
curl --request GET \
  --url 'https://ht-api.coinmarketman.com/api/external/5/assets/liquidation-risk?limit=50' \
  --header 'Authorization: Bearer YOUR_API_TOKEN'
```

{% endtab %}

{% tab title="JavaScript" %}

```
const segmentId = 5;
const response = await fetch(
  `https://ht-api.coinmarketman.com/api/external/5/assets/liquidation-risk?limit=50`,
  {
    headers: { 'Authorization': 'Bearer YOUR_API_TOKEN' }
  }
);
const liquidationData = await response.json();
```

{% endtab %}

{% tab title="Python" %}

```
import requests

segment_id = 5

response = requests.get(
    f"https://ht-api.coinmarketman.com/api/external/5/assets/liquidation-risk?limit=50",
    params={"limit": 50},
    headers={
        "Authorization": "Bearer YOUR_API_TOKEN",
    },
)

result = response.json()
```

{% endtab %}
{% endtabs %}

Response

> 200 Success: Returns liquidation risk data by asset

<details>

<summary>Response Example</summary>

{% code expandable="true" %}

```
{
    "totalCount": 294,
    "items": [
        {
            "coin": "DOGE",
            "totalValue": 5121448.364955,
            "riskValue": 0,
            "percentRisk": 0
        },
        {
            "coin": "DOOD",
            "totalValue": 1797.73664,
            "riskValue": 0,
            "percentRisk": 0
        },
        {
            "coin": "DOT",
            "totalValue": 919798.58649,
            "riskValue": 0,
            "percentRisk": 0
        },
        {
            "coin": "DYM",
            "totalValue": 2685.172599,
            "riskValue": 0,
            "percentRisk": 0
        },
        {
            "coin": "ENS",
            "totalValue": 73286.40263,
            "riskValue": 0,
            "percentRisk": 0
        },
        {
            "coin": "ETC",
            "totalValue": 166596.596496,
            "riskValue": 0,
            "percentRisk": 0
        },
        {
            "coin": "ETHFI",
            "totalValue": 126536.105268,
            "riskValue": 0,
            "percentRisk": 0
        },
        {
            "coin": "FET",
            "totalValue": 252331.87994,
            "riskValue": 0,
            "percentRisk": 0
        },
        {
            "coin": "flx:COIN",
            "totalValue": 441.4917,
            "riskValue": 0,
            "percentRisk": 0
        },
        {
            "coin": "flx:CRCL",
            "totalValue": 5072.8345,
            "riskValue": 0,
            "percentRisk": 0
        },
        {
            "coin": "flx:GOLD",
            "totalValue": 27276.8546,
            "riskValue": 0,
            "percentRisk": 0
        },
        {
            "coin": "flx:OIL",
            "totalValue": 67535.1378,
            "riskValue": 0,
            "percentRisk": 0
        },
        {
            "coin": "flx:PALLADIUM",
            "totalValue": 200.5861,
            "riskValue": 0,
            "percentRisk": 0
        },
        {
            "coin": "flx:PLATINUM",
            "totalValue": 16639.995,
            "riskValue": 0,
            "percentRisk": 0
        },
        {
            "coin": "flx:SILVER",
            "totalValue": 7832.61655,
            "riskValue": 0,
            "percentRisk": 0
        },
        {
            "coin": "flx:TSLA",
            "totalValue": 102005.966,
            "riskValue": 0,
            "percentRisk": 0
        },
        {
            "coin": "flx:USDE",
            "totalValue": 7758.06555,
            "riskValue": 0,
            "percentRisk": 0
        },
        {
            "coin": "flx:XMR",
            "totalValue": 7603.3214,
            "riskValue": 0,
            "percentRisk": 0
        },
        {
            "coin": "FOGO",
            "totalValue": 195846.010167,
            "riskValue": 0,
            "percentRisk": 0
        },
        {
            "coin": "FTT",
            "totalValue": 24908.6439,
            "riskValue": 0,
            "percentRisk": 0
        },
        {
            "coin": "GAS",
            "totalValue": 17006.95099,
            "riskValue": 0,
            "percentRisk": 0
        },
        {
            "coin": "GMT",
            "totalValue": 13952.722524,
            "riskValue": 0,
            "percentRisk": 0
        },
        {
            "coin": "GMX",
            "totalValue": 2794.986942,
            "riskValue": 0,
            "percentRisk": 0
        },
        {
            "coin": "GRASS",
            "totalValue": 437271.7594,
            "riskValue": 0,
            "percentRisk": 0
        },
        {
            "coin": "HBAR",
            "totalValue": 1617504.10548,
            "riskValue": 0,
            "percentRisk": 0
        },
        {
            "coin": "HMSTR",
            "totalValue": 2630.87478,
            "riskValue": 0,
            "percentRisk": 0
        },
        {
            "coin": "hyna:1000PEPE",
            "totalValue": 473826.628779,
            "riskValue": 0,
            "percentRisk": 0
        },
        {
            "coin": "hyna:ADA",
            "totalValue": 29877.34632,
            "riskValue": 0,
            "percentRisk": 0
        },
        {
            "coin": "hyna:BCH",
            "totalValue": 10261.26306,
            "riskValue": 0,
            "percentRisk": 0
        },
        {
            "coin": "hyna:BNB",
            "totalValue": 41004.8471,
            "riskValue": 0,
            "percentRisk": 0
        },
        {
            "coin": "hyna:BTC",
            "totalValue": 5803054.331584,
            "riskValue": 0,
            "percentRisk": 0
        },
        {
            "coin": "hyna:DOGE",
            "totalValue": 40739.633961,
            "riskValue": 0,
            "percentRisk": 0
        },
        {
            "coin": "hyna:ENA",
            "totalValue": 21097.77894,
            "riskValue": 0,
            "percentRisk": 0
        },
        {
            "coin": "hyna:ETH",
            "totalValue": 1380934.98304,
            "riskValue": 0,
            "percentRisk": 0
        },
        {
            "coin": "hyna:FARTCOIN",
            "totalValue": 421726.585198,
            "riskValue": 0,
            "percentRisk": 0
        },
        {
            "coin": "hyna:HYPE",
            "totalValue": 236900.089545,
            "riskValue": 0,
            "percentRisk": 0
        },
        {
            "coin": "hyna:IP",
            "totalValue": 8725.611664,
            "riskValue": 0,
            "percentRisk": 0
        },
        {
            "coin": "hyna:LIGHTER",
            "totalValue": 15928.932,
            "riskValue": 0,
            "percentRisk": 0
        },
        {
            "coin": "hyna:LINK",
            "totalValue": 23551.04241,
            "riskValue": 0,
            "percentRisk": 0
        },
        {
            "coin": "hyna:LTC",
            "totalValue": 30754.07892,
            "riskValue": 0,
            "percentRisk": 0
        },
        {
            "coin": "hyna:PUMP",
            "totalValue": 90557.200125,
            "riskValue": 0,
            "percentRisk": 0
        },
        {
            "coin": "hyna:SOL",
            "totalValue": 809994.909,
            "riskValue": 0,
            "percentRisk": 0
        },
        {
            "coin": "hyna:SUI",
            "totalValue": 27753.203734,
            "riskValue": 0,
            "percentRisk": 0
        },
        {
            "coin": "hyna:XMR",
            "totalValue": 430.1868,
            "riskValue": 0,
            "percentRisk": 0
        },
        {
            "coin": "hyna:XPL",
            "totalValue": 16554.241634,
            "riskValue": 0,
            "percentRisk": 0
        },
        {
            "coin": "hyna:XRP",
            "totalValue": 124472.97235,
            "riskValue": 0,
            "percentRisk": 0
        },
        {
            "coin": "hyna:ZEC",
            "totalValue": 61625.5884,
            "riskValue": 0,
            "percentRisk": 0
        },
        {
            "coin": "HYPER",
            "totalValue": 10060.556616,
            "riskValue": 0,
            "percentRisk": 0
        },
        {
            "coin": "ICP",
            "totalValue": 64001.11556,
            "riskValue": 0,
            "percentRisk": 0
        },
        {
            "coin": "IMX",
            "totalValue": 4519.105104,
            "riskValue": 0,
            "percentRisk": 0
        }
    ]
}
```

{% endcode %}

</details>

***


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.coinmarketman.com/endpoints/liquidation-data.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.