# CoinGlass Liquidation Map API (`api_merge/coinglass-liquidation-map`) Actor

Fetch CoinGlass liquidation map data for futures trading pairs. Search supported instruments, select a range, and get clean JSON output showing mapped liquidation price levels, liquidation size, and leverage ratio

- **URL**: https://apify.com/api\_merge/coinglass-liquidation-map.md
- **Developed by:** [Api Merge](https://apify.com/api_merge) (community)
- **Categories:** Automation, Integrations
- **Stats:** 16 total users, 6 monthly users, 97.2% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $10.00 / 1,000 liquidation maps

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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

## 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

### What does CoinGlass Liquidation Map do?

CoinGlass Liquidation Map helps you search supported futures instruments and fetch liquidation map data for a selected instrument and range. Use `search_symbols` to find the correct `symbol` value, then send that value to `liquidation_map` to get clean JSON liquidation map output.

### Why use CoinGlass Liquidation Map?

Use this Actor when you need structured liquidation map data for dashboards, market analysis, alerts, or automated workflows.

- Search futures instruments by keyword
- Fetch liquidation map data by instrument and range
- Use separate pay-per-event pricing for symbol searches and liquidation map data
- Export results as JSON, CSV, Excel, HTML, or RSS

### How to use CoinGlass Liquidation Map

1. Open the Actor on Apify.
2. Select `search_symbols` to find an instrument, or `liquidation_map` to fetch map data.
3. Fill the matching input fields.
4. Click **Start**.
5. Read the output from the default dataset.

### Input

| Field | Required | Default | Description |
| --- | --- | --- | --- |
| `mode` | Yes | `search_symbols` | Operation to run. Supported values: `search_symbols`, `liquidation_map`. |
| `keyword` | No | empty | Optional search keyword used with `search_symbols`. Leave it empty to return the default futures symbol list. |
| `symbol` | Required for `liquidation_map` | `Binance_BTCUSDT` | Symbol value returned by `search_symbols`, such as `Binance_BTCUSDT`. |
| `range` | Required for `liquidation_map` | `1d` | Liquidation map range. Supported values: `1d`, `7d`, `30d`, `90d`, `180d`, `365d`. |

### Search symbols input example

```json
{
    "mode": "search_symbols",
    "keyword": "btc"
}
```

`keyword` is optional. You can also leave it empty when using `search_symbols`.

### Search symbols output example

```json
{
    "success": true,
    "message": "Futures symbols fetched successfully.",
    "mode": "search_symbols",
    "keyword": "btc",
    "data": [
        {
            "base_asset": "BTC",
            "quote_asset": "USDT",
            "exchange": "Binance",
            "symbol": "Binance_BTCUSDT"
        }
    ]
}
```

Use the `symbol` value from the `search_symbols` response as the `symbol` input for `liquidation_map`.

### Liquidation map input example

```json
{
    "mode": "liquidation_map",
    "symbol": "Binance_BTCUSDT",
    "range": "1d"
}
```

### Liquidation map output example

```json
{
    "success": true,
    "message": "Liquidation map data fetched successfully.",
    "mode": "liquidation_map",
    "symbol": "Binance_BTCUSDT",
    "range": "1d",
    "data": {
        "48935": [ // Liquidation price
            [
                48935, // Liquidation price
                1579370.77, // Liquidation level
                25, // Leverage ratio
                null
            ]
        ]
    }
}
```

### Data table

| Field | Description |
| --- | --- |
| `success` | `true` when the Actor completed cleanly. |
| `message` | Human-readable result or warning message. |
| `mode` | Operation used for the run. |
| `keyword` | Search keyword, when `search_symbols` is used. |
| `symbol` | Search result symbol used for `liquidation_map`. |
| `range` | Liquidation map range, when `liquidation_map` is used. |
| `data` | Symbol search results or liquidation map data. |
| `data.<price>` | Liquidation price level key. |
| `data.<price>[0][0]` | Liquidation price. |
| `data.<price>[0][1]` | Liquidation level. |
| `data.<price>[0][2]` | Leverage ratio. |

### Pay-per-event pricing

This Actor uses separate charge events for each operation:

| Event name | Used for |
| --- | --- |
| `SEARCH_SYMBOLS` | Searching futures instruments. |
| `LIQUIDATION_MAP` | Fetching liquidation map data. |

### Tips

- Run `search_symbols` first if you do not know the exact `symbol`.
- Use the returned `symbol` as the `symbol` input for `liquidation_map`.
- Use longer ranges such as `90d`, `180d`, or `365d` for wider liquidation map snapshots.

# Actor input Schema

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

Choose whether to search futures symbols or fetch liquidation map data.

## `keyword` (type: `string`):

Search keyword used only when mode is search\_symbols.

## `symbol` (type: `string`):

Symbol value returned by search\_symbols, used only when mode is liquidation\_map, such as Binance\_BTCUSDT.

## `range` (type: `string`):

Time range used only when mode is liquidation\_map.

## Actor input object example

```json
{
  "mode": "liquidation_map",
  "symbol": "Binance_BTCUSDT",
  "range": "1d"
}
```

# Actor output Schema

## `dataset` (type: `string`):

Dataset items with symbol search results, liquidation map data, or a warning.

# 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 = {
    "mode": "liquidation_map",
    "symbol": "Binance_BTCUSDT",
    "range": "1d"
};

// Run the Actor and wait for it to finish
const run = await client.actor("api_merge/coinglass-liquidation-map").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 = {
    "mode": "liquidation_map",
    "symbol": "Binance_BTCUSDT",
    "range": "1d",
}

# Run the Actor and wait for it to finish
run = client.actor("api_merge/coinglass-liquidation-map").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 '{
  "mode": "liquidation_map",
  "symbol": "Binance_BTCUSDT",
  "range": "1d"
}' |
apify call api_merge/coinglass-liquidation-map --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=api_merge/coinglass-liquidation-map",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/MkSL4fBoFqI5dZ508/builds/cV2e6vDFzwyKRQUb1/openapi.json