# Crypto Liquidations Tracker: Forced Long & Short Closeouts (`scrapemint/crypto-liquidations-tracker`) Actor

Keyless crypto liquidation data from OKX and Gate.io: how much was liquidated long versus short in USD per coin, every forced closeout with its dollar size, and the OKX long/short account ratio behind a cascade. Contract sizes converted to dollars. Pay per row.

- **URL**: https://apify.com/scrapemint/crypto-liquidations-tracker.md
- **Developed by:** [Ken M](https://apify.com/scrapemint) (community)
- **Categories:** Business, News
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-usage

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Crypto Liquidations Tracker: Forced Long & Short Closeouts

Keyless **crypto liquidation** data from **OKX** and **Gate.io**. No API key, no account. Funding rates and open interest show leverage building up; liquidations show it breaking, and a cascade of forced closeouts is the mechanic behind most violent moves in crypto.

- **Summary** — one row per coin per venue: how much was liquidated **long** versus **short** in dollars, event counts, the largest single hit, and the ratio between the two sides.
- **Liquidations** — one row per forced closeout, newest first, with its dollar size, the price it was closed at, and which side got taken out.
- **Positioning** — the OKX long/short account ratio over time. This is the build up rather than the break: a crowded long book is the precondition for a downside cascade.

### Who uses it

- **Leveraged traders** — long liquidations clustering into a drop is the capitulation read; short liquidations clustering into a rally is a squeeze.
- **Risk and desk monitoring** — a running dollar figure for what is being forced out of the market, per coin.
- **Quants and dashboard builders** — schedule it and store snapshots to build your own liquidation history.
- **Newsletters and analysts** — "$40m of longs were liquidated in an hour" is a story, and this is where the number comes from.

Pairs with our [Crypto Funding Rates & Open Interest Tracker](https://apify.com/scrapemint/crypto-funding-rates-tracker) for the leverage that precedes the liquidation, and the [Deribit Options Tracker](https://apify.com/scrapemint/deribit-options-tracker) for the volatility side.

### Input

| Field | Description |
|-------|-------------|
| `mode` | `summary`, `liquidations`, or `positioning`. |
| `coins` | Base coins, e.g. `BTC`, `ETH`, `SOL`. Max 30 per run. |
| `venues` | `okx`, `gate`, or both. |
| `side` | `both` / `long` / `short`. |
| `minValueUsd` | Skip small liquidations and keep the ones that move price. |
| `period` | Candle size for the positioning series. |
| `positioningPoints` | How many ratio readings per coin. |
| `maxRows` | Row cap per run. |

### Output

- **Summary**: `venue`, `coin`, `instrument`, `events`, `longEvents`, `shortEvents`, `longLiquidatedUsd`, `shortLiquidatedUsd`, `totalLiquidatedUsd`, `longShortLiquidationRatio`, `largestLiquidationUsd`, `largestLiquidationSide`, `averageLiquidationUsd`, `windowStart`, `windowEnd`.
- **Liquidations**: `venue`, `coin`, `instrument`, `side`, `price`, `contracts`, `coinAmount`, `valueUsd`, `liquidatedAt`.
- **Positioning**: `coin`, `timestamp`, `longShortAccountRatio`, `longAccountPercent`, `period`.

`side` is always the side that **got liquidated**. A liquidated short is reported as `short`, even though the exchange's own offsetting trade was a buy.

### Notes on the data

- **Sizes are published in contracts, not coins, and the multiplier differs per contract and per venue.** An OKX BTC perpetual contract is 0.01 BTC; a Gate one is 0.0001 BTC. ETH is 0.1 on OKX and 0.01 on Gate. Every row is converted through the venue's own contract table before being reported, so `valueUsd` is comparable across venues and coins. A raw contract count is not.
- **Gate reports a running position, not a per event quantity.** Its `size` field is what is left of the position as the engine works it down, while `order_size` is what each event actually closed. Rows here use the quantity closed, so one large liquidation is counted once rather than once per partial fill.
- **Coverage is OKX and Gate because those are the venues that answer.** Binance and Bybit block datacenter IPs, and Bitget publishes no liquidation endpoint. These figures are therefore two venues' worth of liquidations, not the whole market, and OKX carries the large majority of the events.
- Each venue returns its own rolling window rather than a range you choose, so `windowStart` and `windowEnd` tell you what period a summary row actually covers. It is typically hours, and it differs by coin and by venue.
- Inverse (coin margined) contracts are excluded rather than guessed at, since they are sized in dollars rather than in the base coin.
- `longAccountPercent` restates the account ratio as a share of accounts, so 1.55 becomes 60.8% of accounts positioned long.
- Nothing to report is a free note row, not an error.

### Pricing

Pay per event: **$0.003 per row**. The first 2 rows of every run are free.

Data sources: OKX and Gate.io public APIs.

# Actor input Schema

## `mode` (type: `string`):

summary = one row per coin per venue with long vs short liquidated in USD and the ratio between them. liquidations = one row per forced closeout. positioning = the OKX long/short account ratio over time, which is the build up a cascade needs.

## `coins` (type: `array`):

Base coins to track, e.g. BTC, ETH, SOL. USDT perpetuals are used on both venues. Maximum 30 per run.

## `venues` (type: `array`):

Which venues to read: okx, gate. OKX carries far more events; Gate is a thin second source.

## `side` (type: `string`):

Return only long liquidations (forced selling into a drop), only short liquidations (a squeeze), or both.

## `minValueUsd` (type: `integer`):

Skip liquidations smaller than this. Raise it to see only the large forced closeouts that actually move price. 0 = every event.

## `period` (type: `string`):

Candle size for the long/short account ratio series.

## `positioningPoints` (type: `integer`):

How many of the most recent ratio readings to return for each coin.

## `maxRows` (type: `integer`):

Cap on rows returned. Controls total cost. Busy coins can produce thousands of liquidation events per day.

## Actor input object example

```json
{
  "mode": "summary",
  "coins": [
    "BTC",
    "ETH",
    "SOL"
  ],
  "venues": [
    "okx",
    "gate"
  ],
  "side": "both",
  "minValueUsd": 0,
  "period": "1H",
  "positioningPoints": 48,
  "maxRows": 200
}
```

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "coins": [
        "BTC",
        "ETH",
        "SOL"
    ],
    "venues": [
        "okx",
        "gate"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("scrapemint/crypto-liquidations-tracker").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "coins": [
        "BTC",
        "ETH",
        "SOL",
    ],
    "venues": [
        "okx",
        "gate",
    ],
}

# Run the Actor and wait for it to finish
run = client.actor("scrapemint/crypto-liquidations-tracker").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "coins": [
    "BTC",
    "ETH",
    "SOL"
  ],
  "venues": [
    "okx",
    "gate"
  ]
}' |
apify call scrapemint/crypto-liquidations-tracker --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=scrapemint/crypto-liquidations-tracker",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/3x9zBzIoN0AoWS7lQ/builds/FMLjvQO0ank8MrSBg/openapi.json