---
title: Liquidations
description: Aggregated liquidation volume data via the Kiyotaka Data API.
---

# Liquidations

<EndpointBar method="GET" path="/v1/points"></EndpointBar>

<TypeHeader type="LIQUIDATION_AGG" meta="Weight: 1x | Max points: 100,000"></TypeHeader>

Aggregated liquidation volume over an interval. Returns one series per side (buy/sell liquidations).

## Response fields

| Field | Type | Description |
| --- | --- | --- |
| `liquidations` | double | Total liquidation volume (coin by default, USD with [transform](/docs/exchanges#transforms)) |
| `timestamp` | Timestamp | Start of the interval |

The series identifier includes a `side` field (`BUY` or `SELL`) to distinguish the direction of liquidations.

## Capabilities

| Feature | Supported | Details |
| --- | --- | --- |
| USD denomination | Yes | `transform.normalize.quote=USD` converts to USD |
| Multi-exchange aggregation | Yes | `transform.groupBy.type=GROUP_BY_TYPE_SUM` with `coin` param |

## Examples

### Single exchange (coin values)

Fetches 1 hour of hourly liquidation data for BTCUSDT on Binance Futures. Returns two series -- one for buy-side liquidations (longs getting liquidated) and one for sell-side (shorts getting liquidated). Values are in coin terms.

<CodeTabs>

<CodePanel lang="curl">
<pre><span class="s-f">curl</span> <span class="s-s">"https://api.kiyotaka.ai/v1/points</span>
    <span class="s-p">?type</span>=<span class="s-s">LIQUIDATION_AGG</span>
    <span class="s-p">&exchange</span>=<span class="s-s">BINANCE_FUTURES</span>
    <span class="s-p">&rawSymbol</span>=<span class="s-s">BTCUSDT</span>
    <span class="s-p">&interval</span>=<span class="s-s">HOUR</span>
    <span class="s-p">&from</span>=<span class="s-n">1774800000</span>
    <span class="s-p">&period</span>=<span class="s-n">3600</span><span class="s-s">"</span> \\
  <span class="s-k">-H</span> <span class="s-s">"X-Kiyotaka-Key: YOUR_API_KEY"</span></pre>
</CodePanel>

<CodePanel lang="python">
<pre><span class="s-k">import</span> <span class="s-v">requests</span>
&#10;
<span class="s-v">response</span> = requests.<span class="s-f">get</span>(
    <span class="s-s">"https://api.kiyotaka.ai/v1/points?type=LIQUIDATION_AGG&exchange=BINANCE_FUTURES&rawSymbol=BTCUSDT&interval=HOUR&from=1774800000&period=3600 "</span>,
    headers={<span class="s-s">"X-Kiyotaka-Key"</span>: <span class="s-s">"YOUR_API_KEY"</span>}
)
<span class="s-v">data</span> = response.<span class="s-f">json</span>()</pre>
</CodePanel>

<CodePanel lang="javascript">
<pre><span class="s-k">const</span> <span class="s-v">response</span> = <span class="s-k">await</span> <span class="s-f">fetch</span>(
  <span class="s-s">"https://api.kiyotaka.ai/v1/points?type=LIQUIDATION_AGG&exchange=BINANCE_FUTURES&rawSymbol=BTCUSDT&interval=HOUR&from=1774800000&period=3600 "</span>,
  { headers: { <span class="s-s">"X-Kiyotaka-Key"</span>: <span class="s-s">"YOUR_API_KEY"</span> } }
)
<span class="s-k">const</span> <span class="s-v">data</span> = <span class="s-k">await</span> response.<span class="s-f">json</span>()</pre>
</CodePanel>

</CodeTabs>

### Aggregated across exchanges (USD)

Sums liquidation volume across Binance Futures, Bybit, and OKX for all BTC pairs, converted to USD. Useful for tracking total market liquidation pressure.

<CodeTabs>

<CodePanel lang="curl">
<pre><span class="s-f">curl</span> <span class="s-s">"https://api.kiyotaka.ai/v1/points</span>
    <span class="s-p">?type</span>=<span class="s-s">LIQUIDATION_AGG</span>
    <span class="s-p">&exchange</span>=<span class="s-s">BINANCE_FUTURES</span>
    <span class="s-p">&exchange</span>=<span class="s-s">BYBIT</span>
    <span class="s-p">&exchange</span>=<span class="s-s">OKEX_SWAP</span>
    <span class="s-p">&coin</span>=<span class="s-s">BTC</span>
    <span class="s-p">&interval</span>=<span class="s-s">HOUR</span>
    <span class="s-p">&from</span>=<span class="s-n">1774800000</span>
    <span class="s-p">&period</span>=<span class="s-n">3600</span>
    <span class="s-p">&transform.groupBy.type</span>=<span class="s-s">GROUP_BY_TYPE_SUM</span>
    <span class="s-p">&transform.normalize.quote</span>=<span class="s-s">USD</span><span class="s-s">"</span> \\
  <span class="s-k">-H</span> <span class="s-s">"X-Kiyotaka-Key: YOUR_API_KEY"</span></pre>
</CodePanel>

<CodePanel lang="python">
<pre><span class="s-k">import</span> <span class="s-v">requests</span>
&#10;
<span class="s-v">response</span> = requests.<span class="s-f">get</span>(
    <span class="s-s">"https://api.kiyotaka.ai/v1/points?type=LIQUIDATION_AGG&exchange=BINANCE_FUTURES&exchange=BYBIT&exchange=OKEX_SWAP&coin=BTC&interval=HOUR&from=1774800000&period=3600&transform.groupBy.type=GROUP_BY_TYPE_SUM&transform.normalize.quote=USD "</span>,
    headers={<span class="s-s">"X-Kiyotaka-Key"</span>: <span class="s-s">"YOUR_API_KEY"</span>}
)
<span class="s-v">data</span> = response.<span class="s-f">json</span>()</pre>
</CodePanel>

<CodePanel lang="javascript">
<pre><span class="s-k">const</span> <span class="s-v">response</span> = <span class="s-k">await</span> <span class="s-f">fetch</span>(
  <span class="s-s">"https://api.kiyotaka.ai/v1/points?type=LIQUIDATION_AGG&exchange=BINANCE_FUTURES&exchange=BYBIT&exchange=OKEX_SWAP&coin=BTC&interval=HOUR&from=1774800000&period=3600&transform.groupBy.type=GROUP_BY_TYPE_SUM&transform.normalize.quote=USD "</span>,
  { headers: { <span class="s-s">"X-Kiyotaka-Key"</span>: <span class="s-s">"YOUR_API_KEY"</span> } }
)
<span class="s-k">const</span> <span class="s-v">data</span> = <span class="s-k">await</span> response.<span class="s-f">json</span>()</pre>
</CodePanel>

</CodeTabs>

### Response

<CodeBlock lang="JSON">
<pre>{
  <span class="s-p">"series"</span>: [
    {
      <span class="s-p">"id"</span>: {
        <span class="s-p">"type"</span>: <span class="s-s">"LIQUIDATION_AGG"</span>,
        <span class="s-p">"exchange"</span>: <span class="s-s">"BINANCE_FUTURES"</span>,
        <span class="s-p">"rawSymbol"</span>: <span class="s-s">"BTCUSDT"</span>,
        <span class="s-p">"normalizedSymbol"</span>: <span class="s-s">"BTC-USDT"</span>,
        <span class="s-p">"category"</span>: <span class="s-s">"PERPETUAL"</span>,
        <span class="s-p">"interval"</span>: <span class="s-s">"HOUR"</span>,
        <span class="s-p">"side"</span>: <span class="s-s">"SELL"</span>,
        <span class="s-p">"coin"</span>: <span class="s-s">"BTC"</span>
      },
      <span class="s-p">"points"</span>: [
        {
          <span class="s-p">"Point"</span>: {
            <span class="s-p">"liquidations"</span>: <span class="s-n">0.223</span>,
            <span class="s-p">"timestamp"</span>: { <span class="s-p">"s"</span>: <span class="s-n">1774800000</span> }
          }
        }
      ]
    },
    {
      <span class="s-p">"id"</span>: {
        <span class="s-p">"type"</span>: <span class="s-s">"LIQUIDATION_AGG"</span>,
        <span class="s-p">"exchange"</span>: <span class="s-s">"BINANCE_FUTURES"</span>,
        <span class="s-p">"rawSymbol"</span>: <span class="s-s">"BTCUSDT"</span>,
        <span class="s-p">"normalizedSymbol"</span>: <span class="s-s">"BTC-USDT"</span>,
        <span class="s-p">"category"</span>: <span class="s-s">"PERPETUAL"</span>,
        <span class="s-p">"interval"</span>: <span class="s-s">"HOUR"</span>,
        <span class="s-p">"side"</span>: <span class="s-s">"BUY"</span>,
        <span class="s-p">"coin"</span>: <span class="s-s">"BTC"</span>
      },
      <span class="s-p">"points"</span>: [
        {
          <span class="s-p">"Point"</span>: {
            <span class="s-p">"liquidations"</span>: <span class="s-n">1.529</span>,
            <span class="s-p">"timestamp"</span>: { <span class="s-p">"s"</span>: <span class="s-n">1774800000</span> }
          }
        }
      ]
    }
  ]
}</pre>
</CodeBlock>