> ## Documentation Index
> Fetch the complete documentation index at: https://docs.marketdataset.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# GET /crypto/liquidations

> Historical forced liquidations in crypto futures markets

## Endpoint

```
GET https://api.marketdataset.ai/crypto/liquidations
```

Liquidations occur when a trader's margin balance falls below the maintenance margin threshold. The exchange forcibly closes their position.

**Why liquidations matter:**

* Liquidation clusters mark significant support/resistance levels
* Cascading liquidations can trigger sharp directional moves
* Large liquidation events often mark local tops/bottoms

## Parameters

| Name         | Type    | Required | Description                                                |
| ------------ | ------- | -------- | ---------------------------------------------------------- |
| `symbol`     | string  | No       | Futures symbol, e.g. `BTCUSDT`. Returns all if omitted.    |
| `exchange`   | string  | No       | Exchange (default: `binance`)                              |
| `side`       | string  | No       | `long` or `short`. `long` = forced sell of a long position |
| `start_date` | string  | No       | ISO 8601 date                                              |
| `end_date`   | string  | No       | ISO 8601 date                                              |
| `limit`      | integer | No       | Records to return (default: `100`, max: `1000`)            |
| `cursor`     | string  | No       | Pagination cursor                                          |

## Credit cost

**\$0.010** per request

## Example request

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.marketdataset.ai/crypto/liquidations?symbol=BTCUSDT&side=long&limit=10" \
    -H "X-API-KEY: sk_your_key"
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.marketdataset.ai/crypto/liquidations",
      params={"symbol": "BTCUSDT", "side": "long", "limit": 10},
      headers={"X-API-KEY": "sk_your_key"},
  )
  print(response.json())
  ```
</CodeGroup>

## Example response

```json theme={null}
{
  "liquidations": [
    {
      "symbol": "BTCUSDT",
      "exchange": "binance",
      "side": "long",
      "quantity": 0.143,
      "price": 67843.21,
      "value_usd": 9701.58,
      "liquidated_at": "2024-11-01T14:32:17+00:00"
    }
  ],
  "next_page_url": null,
  "meta": {
    "request_id": "req_abc123",
    "credits_used": 0.01,
    "credits_remaining": 49.99
  }
}
```

## Fields

| Field       | Description                                                                                                   |
| ----------- | ------------------------------------------------------------------------------------------------------------- |
| `side`      | `long` = a long position was liquidated (forced sell); `short` = a short position was liquidated (forced buy) |
| `quantity`  | Contracts liquidated (in base currency)                                                                       |
| `price`     | Liquidation price                                                                                             |
| `value_usd` | USD value of the liquidation                                                                                  |