# Coinglass Liquidation Heatmap (`itsoul/coinglass-liquidation-heatmap`) Actor

Captures high-resolution CoinGlass liquidation heatmap screenshots with Playwright. Supports custom coin, chart type, dimensions, and wait time. Saves images to Key-Value Store and returns direct URLs with full metadata in the dataset.

- **URL**: https://apify.com/itsoul/coinglass-liquidation-heatmap.md
- **Developed by:** [Mahmoud Alhamdo](https://apify.com/itsoul) (community)
- **Categories:** Integrations, Other, News
- **Stats:** 154 total users, 1 monthly users, 100.0% runs succeeded, 1 bookmarks
- **User rating**: No ratings yet

## Pricing

from $6.00 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

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

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## CoinGlass Liquidation Heatmap Capture

An Apify Actor that captures CoinGlass liquidation heatmap charts as PNG screenshots. The actor navigates to CoinGlass liquidation heatmap pages and captures high-quality screenshots of the heatmap canvas.

### Features

- 📊 Capture CoinGlass liquidation heatmaps for any cryptocurrency
- 🎯 Automatic canvas detection and capture
- 🖼️ High-resolution PNG screenshots
- 📦 Base64 encoded images in dataset output
- ☁️ Fully compatible with Apify platform
- 🚀 Can run locally or in the cloud
- 🎨 Support for custom viewport sizes
- ⏱️ Configurable wait times for page loading

### Prerequisites

- Python 3.8+ (for local development)
- Apify account (for cloud deployment)
- Git (for version control)

### Local Development

#### 1. Install Dependencies

```bash
## Install Python dependencies
pip install -r requirements.txt

## Install Playwright browsers
playwright install chromium
```

#### 2. Run Locally with Apify SDK

The actor uses Apify SDK which works automatically in local environment:

```bash
## Run the actor (Apify CLI automatically reads storage/key_value_stores/default/INPUT.json)
apify run

## Or specify custom input file
apify run --input storage/key_value_stores/default/INPUT.json
```

#### 3. Local Storage

When running locally, Apify SDK automatically creates:

- `storage/key_value_stores/default/` - Screenshots stored here
- `storage/datasets/default/` - Dataset JSON files stored here

#### 4. Test Input Example

Create `storage/key_value_stores/default/INPUT.json` file:

```json
{
  "coin": "SOL",
  "type": "symbol",
  "width": 1920,
  "height": 1080,
  "waitTime": 5,
  "headless": false
}
```

**Note:**

- Apify SDK works automatically in local mode - no API token required for local testing
- On Apify platform, input is provided via Actor input in the console

### Input Schema

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `coin` | string | `"SOL"` | Cryptocurrency symbol (e.g., `SOL`, `BTC`, `ETH`) |
| `type` | string | `"symbol"` | Chart type (usually `"symbol"`) |
| `width` | integer | `1920` | Screenshot width in pixels (800-3840) |
| `height` | integer | `1080` | Screenshot height in pixels (600-2160) |
| `waitTime` | integer | `5` | Time to wait for page to fully load before screenshot (in seconds, 1-30) |
| `outputFileName` | string | `null` | Custom filename (auto-generated if not provided) |
| `headless` | boolean | `false` (locally) | Run browser in headless mode (hidden). Default: false locally, true on Apify platform |

### Output

The actor saves:

- **Screenshot**: PNG image in Apify Key-Value store
- **Metadata**: JSON record in Apify Dataset with:
  - Coin symbol, type, URL
  - **`screenshotBase64`**: Base64 encoded image string (ready to use)
  - **`screenshotDataUrl`**: Data URL format (`data:image/png;base64,...`)
  - Screenshot URL and key (for direct access)
  - Timestamp

**Example output:**

```json
{
  "coin": "SOL",
  "type": "symbol",
  "url": "https://www.coinglass.com/pro/futures/LiquidationHeatMap?coin=SOL&type=symbol",
  "width": 1920,
  "height": 1080,
  "screenshotBase64": "iVBORw0KGgoAAAANSUhEUgAA...",
  "screenshotDataUrl": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
  "screenshotUrl": "https://api.apify.com/v2/key-value-stores/.../coinglass_SOL_2024-01-01T12-00-00.png",
  "screenshotKey": "coinglass_SOL_2024-01-01T12-00-00.png",
  "timestamp": "2024-01-01T12:00:00.000Z"
}
```

### Supported Coins

The actor supports all cryptocurrencies available on CoinGlass, including:

- **SOL** (Solana)
- **BTC** (Bitcoin)
- **ETH** (Ethereum)
- **BNB** (Binance Coin)
- And many more...

### GitHub Setup & Deployment

#### 1. Initialize Git Repository

```bash
## Initialize git (if not already done)
git init

## Add all files
git add .

## Create initial commit
git commit -m "Initial commit: CoinGlass heatmap capture actor"
```

#### 2. Push to GitHub

```bash
## Create a new repository on GitHub, then:
git remote add origin https://github.com/YOUR_USERNAME/coinglass-heatmap-capture.git
git branch -M main
git push -u origin main
```

#### 3. Deploy to Apify

##### Option A: Deploy from GitHub (Recommended)

1. Go to [Apify Console](https://console.apify.com/)
2. Click **"Create new"** → **"Actor"**
3. Select **"Deploy from GitHub"**
4. Connect your GitHub account
5. Select the repository: `coinglass-heatmap-capture`
6. Apify will automatically build and deploy your actor

##### Option B: Deploy via CLI

```bash
## Login to Apify
apify login

## Build the actor
apify build

## Push to Apify
apify push
```

#### 4. Configure GitHub Actions (Optional)

The project includes a GitHub Actions workflow (`.github/workflows/deploy.yml`) that automatically:

- Installs dependencies
- Builds the actor
- Pushes to Apify on every push to `main` branch

**Setup:**

1. Go to your GitHub repository
2. Navigate to **Settings** → **Secrets and variables** → **Actions**
3. Add a new secret named `APIFY_TOKEN` with your Apify API token
4. Get your token from: [Apify Settings → Integrations](https://console.apify.com/account/integrations)

### Project Structure

```
coinglass-heatmap-capture/
├── src/
│   ├── main.py              # Main actor logic
│   ├── __init__.py
│   └── __main__.py
├── .actor/
│   ├── actor.json          # Apify actor configuration
│   ├── input_schema.json   # Input schema definition
│   ├── dataset_schema.json # Dataset output schema
│   └── output_schema.json  # Output schema
├── storage/                # Local storage (gitignored)
│   ├── datasets/           # Local dataset storage
│   └── key_value_stores/   # Local key-value storage
├── requirements.txt        # Python dependencies
├── Dockerfile             # Docker image for Apify platform
├── .gitignore            # Git ignore rules
├── README.md             # This file
└── AGENTS.md             # AI agent instructions
```

### How It Works

1. **Launch Browser**: Opens Chromium via Playwright
2. **Navigate**: Goes to CoinGlass liquidation heatmap URL with specified coin
3. **Wait for Canvas**: Waits for the heatmap canvas to load and render
4. **Capture**: Takes PNG screenshot of the canvas element
5. **Save**: Stores screenshot in Key-Value store and metadata (with base64) in Dataset

### Troubleshooting

#### Canvas Not Found

- Increase `waitTime` value to allow more time for page loading
- Check if CoinGlass is accessible from your network
- Verify the coin symbol is correct

#### Screenshot Quality

- Increase `width` and `height` for higher resolution
- Ensure `waitTime` is sufficient for chart to fully render

#### Page Not Loading

- Check internet connection
- Verify CoinGlass website is accessible
- Increase timeout values if needed

### License

ISC

### Support

For issues and questions:

- Check [Apify Documentation](https://docs.apify.com/)
- Visit [Apify Community](https://forum.apify.com/)
- Review [CoinGlass Terms of Service](https://www.coinglass.com/)

***

**Note**: This actor is for educational and personal use. Ensure compliance with CoinGlass's Terms of Service when using this tool.

# Actor input Schema

## `coin` (type: `string`):

Cryptocurrency symbol (e.g., SOL, BTC, ETH)

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

Chart type

## `width` (type: `integer`):

Screenshot width in pixels

## `height` (type: `integer`):

Screenshot height in pixels

## `waitTime` (type: `integer`):

Time to wait for page to fully load before screenshot (in seconds)

## `outputFileName` (type: `string`):

Custom output filename (without extension). If not provided, will use coinglass_COIN_TIMESTAMP format

## `headless` (type: `boolean`):

Run browser in headless mode (hidden). Default: true (headless mode enabled)

## Actor input object example

```json
{
  "coin": "SOL",
  "type": "symbol",
  "width": 1920,
  "height": 1080,
  "waitTime": 5,
  "headless": true
}
```

# Actor output Schema

## `overview` (type: `string`):

No description

# 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 = {
    "coin": "SOL",
    "type": "symbol",
    "width": 1920,
    "height": 1080,
    "waitTime": 5,
    "headless": true
};

// Run the Actor and wait for it to finish
const run = await client.actor("itsoul/coinglass-liquidation-heatmap").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 = {
    "coin": "SOL",
    "type": "symbol",
    "width": 1920,
    "height": 1080,
    "waitTime": 5,
    "headless": True,
}

# Run the Actor and wait for it to finish
run = client.actor("itsoul/coinglass-liquidation-heatmap").call(run_input=run_input)

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

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

```

## CLI example

```bash
echo '{
  "coin": "SOL",
  "type": "symbol",
  "width": 1920,
  "height": 1080,
  "waitTime": 5,
  "headless": true
}' |
apify call itsoul/coinglass-liquidation-heatmap --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,itsoul/coinglass-liquidation-heatmap"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

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