Liquidation Heatmap（真正的价格区间清算压力）

cgliquidationanalysis 返回全0，不可用。正确做法是直接调 API：

from tools._api import cg_request

# 全市场聚合热力图（推荐，无需指定交易所）
# range 支持: 12h, 24h, 3d, 7d, 30d, 90d, 180d, 1y
data = cg_request("api/futures/liquidation/aggregated-heatmap/model1",
                  params={"symbol": "BTC", "range": "24h"})

# 返回结构：
# data["y_axis"]                   → 价格档位列表（从低到高）
# data["liquidation_leverage_data"] → [[y_idx, leverage, usd_value], ...]
# data["price_candlesticks"]        → OHLCV K线，最后一根收盘价 = 当前价
# data["update_time"]               → 更新时间戳

# 解析方法：
from collections import defaultdict
y_axis = data["y_axis"]
current_price = float(data["price_candlesticks"][-1][4])
price_liq = defaultdict(float)
for y_idx, leverage, usd_val in data["liquidation_leverage_data"]:
    if 0 <= y_idx < len(y_axis):
        price_liq[y_axis[y_idx]] += usd_val

longs  = {p: v for p, v in price_liq.items() if p < current_price}  # 多头清算（↓触发）
shorts = {p: v for p, v in price_liq.items() if p > current_price}  # 空头清算（↑触发）

注意：单交易所版本（heatmap/model1 带 exchange 参数）当前会报 400 错误，改用 aggregated 版本。

Script Usage

Script-mode skill — read this file, then invoke from a bash block:

python3 - <<'EOF'
import sys, json
sys.path.insert(0, "/data/workspace/skills/coinglass")
from exports import funding_rate, cg_open_interest, cg_liquidations

print(funding_rate(symbol="BTC"))
print(cg_open_interest(symbol="BTC"))
EOF

Read exports.py for the full list of available functions and exact signatures. Common ones: fundingrate, longshortratio, cgopeninterest, cgliquidations, cgliquidationanalysis, cgglobalaccountratio, cgtopaccountratio, cgtoppositionratio, cgtakerexchanges, cgnetposition, cgsupportedcoins, cgsupportedexchanges, cgcoinsmarketdata, cgpairmarketdata, cgohlchistory, cghyperliquidwhalealerts, cghyperliquidwhalepositions, cgtakervolumehistory, cgaggregatedtakervolume, cgcumulativevolumedelta, cgcoinnetflow, cgwhaletransfers, cgbtcetfflows, cgethetfflows, cgsoletf_flows.

Coinglass

Coinglass provides the most comprehensive crypto derivatives and institutional data available. 37 tools covering futures positioning, whale tracking, volume analysis, liquidations, and ETF flows.

API Plan: Professional ($699/month) Rate Limit: 6000 requests/minute API Version: V4 (with V2 backward compatibility) Total Tools: 37 across 8 categories

Function Reference (full signatures + return shapes)

All functions live in exports.py. Most return Optional[List[Dict]] or Optional[Dict]. None means the upstream call failed or returned empty — always check before indexing.

⚠️ Field naming convention (READ THIS FIRST)

CoinGlass v4 API uses camelCase for almost all data fields, with a few legacy snakecase exceptions in liquidation endpoints. Don't assume snakecase — inspect the dict before scripting.

• camelCase: openInterest, volUsd, longRate, shortVolUsd,

exchangeName, nextFundingTime, fundingIntervalHours, oichangePercent, h4OIChangePercent, avgFundingRateBySymbol, tokenAmount, liquidationUsd (in some endpoints)

• snakecase (legacy, only in cgliquidations): liquidation_usd,

longLiquidationusd, shortLiquidationusd

• rate fields (funding) are STRINGS with "+" / "-" / "%" — parse with

float(r.rstrip('%').lstrip('+')) to compare numerically

• timestamps are millisecond unix epoch (e.g. 1777881600000)

Funding & Open Interest

Long/Short Ratios

Liquidations

Futures Market Data

Hyperliquid Whale Tracking

Volume / Flow

ETF Flows

Sample responses (most-used functions)

funding_rate(symbol="BTC"):

{
  "symbol": "BTC",
  "exchange": "average",
  "rate": "-0.0016%",
  "num_exchanges": 21,
  "exchanges_data": [
    {"exchangeName": "Binance", "rate": "+0.0050%",
     "nextFundingTime": 1777881600000, "fundingIntervalHours": 8, "status": 1}
  ]
}

cgliquidations(symbol="BTC", timetype="h24"):

[
  {"exchange": "All", "liquidation_usd": 170497688.16,
   "longLiquidation_usd": 8179073.80, "shortLiquidation_usd": 162318614.36},
  {"exchange": "Bybit", "liquidation_usd": 40454694.98, ...}
]

cgopeninterest(symbol="BTC"):

[
  {"symbol": "BTC", "openInterest": 61395303653.62, "volUsd": 56349328748.42,
   "oichangePercent": 7.17, "h4OIChangePercent": 5.33,
   "avgFundingRateBySymbol": -0.001874, "exchangeName": "Binance"}
]

longshortratio(symbol="BTC", interval="h4"):

[{
  "symbol": "BTC", "longRate": 53.65, "shortRate": 46.35,
  "longVolUsd": 12558668895.91, "shortVolUsd": 10848776476.99,
  "totalVolUsd": 23407445372.91,
  "list": [
    {"exchangeName": "Binance", "longRate": 55.75, "shortRate": 44.25, ...}
  ]
}]

Tool Selection Guide

Decision Tree

Step 1: Is this about LIQUIDATIONS?

Liquidation query?
├─ YES → How many coins?
│   ├─ ALL coins / ranking / 排行 / 汇总
│   │   └─ → cg_liquidation_coin_list  ✅ (most liquidation queries land here)
│   ├─ ONE coin, need history over time
│   │   └─ → cg_coin_liquidation_history
│   ├─ ONE coin, specific orders (price/side/USD)
│   │   └─ → cg_liquidation_orders
│   └─ ONE coin, just a quick total + sentiment label
│       └─ → cg_liquidation_analysis  (rarely needed; only if explicitly "simple summary")

Step 2: Is this about LONG/SHORT RATIO?

Long/short query?
├─ Historical time-series, trend over time, 多空比变化
│   └─ → cg_global_account_ratio  (ALL accounts)
│      or cg_top_account_ratio    (top traders only)
│      or cg_top_position_ratio   (by position size)
└─ Current snapshot only (no history needed)
    └─ → long_short_ratio

Step 3: Is this about OPEN INTEREST?

OI query?
└─ → cg_open_interest  (always — do NOT use cg_coins_market_data for OI)

Step 4: Is this a MARKET OVERVIEW / SENTIMENT query?

Sentiment / 市场情绪 / pre-trade check?
└─ Use: funding_rate + long_short_ratio + cg_open_interest
   DO NOT use cg_coins_market_data as a substitute for any of the above

Keyword → Tool Lookup

Common Mistakes

Mistake 1 (most common — 8x failure): Using cgliquidations when you need cgliquidationcoinlist

• cg_liquidations → one coin, one timeframe, basic total only
• cgliquidationcoin_list(exchange) → ALL coins, multi-timeframe (1h/4h/12h/24h), per-exchange breakdown
• Rule: If the question asks for a ranking, overview, or doesn't specify a single coin → use cgliquidationcoin_list

Mistake 2 (5x failure): Using cgliquidationanalysis for liquidation rankings

• cgliquidationanalysis adds a sentiment label to a single-coin total — it is NOT a ranking tool
• Rule: "今日爆仓排行" / "各币种爆仓" → always cgliquidationcoin_list

Mistake 3 (3x failure): Using longshortratio for historical L/S analysis

• longshortratio is a current snapshot (no time-series)
• cgglobalaccount_ratio returns history — use it when the user wants trends or comparison over time
• Rule: If the question compares 全网 (global) vs 头部 (top traders) → call BOTH cgglobalaccountratio AND cgtopaccountratio

Mistake 4 (2x failure): Using cgcoinsmarket_data for open interest

• cgcoinsmarket_data is a bulk snapshot of many coins — not a replacement for dedicated OI or L/S tools
• Rule: OI question → cgopeninterest. L/S question → longshortratio or cgglobalaccountratio. Never route either to cgcoinsmarketdata.

Rules

Tool Call Guidance

❌ FORBIDDEN TOOLS — NEVER USE:

• bash — Do NOT write scripts to process/format data. Use natural language.
• writefile / readfile / edit_file — Do NOT save intermediate data. Answer directly.
• learning_log — ONLY for genuine skill bugs or persistent API errors. NOT for empty responses.
• echo — Do NOT use for debugging or output.

✅ CORRECT PATTERN:

• Tool returns data → Summarize in natural language → Done
• Tool returns empty/null → Report "no data available" → Done
• Need calculation (%, change, ratio) → Do mental math in reply

Match tool count to question scope: - 单一指标问题（"BTC 资金费率"、"ETH 多空比"）→ 1 个工具，直接返回 - 多维度分析（"做多是否合适"、"衍生品体检"）→ 3-5 个工具，综合分析 - 对比问题（"ETH vs SOL"）→ 每个币种调相同工具，并列对比

• 避免重复调用同一工具。 除非用户明确要求不同币种/交易所的对比。

Learning Log Usage (CRITICAL)

learning_log is FORBIDDEN for:

• ❌ Empty API responses — just report "no data available"
• ❌ Tool returning None/null — handle gracefully
• ❌ Uncertainty about tool selection — check decision tree first
• ❌ Normal tool errors — retry once, then report failure

learning_log is ONLY for:

• ✅ Genuine bugs in skill code (wrong data format returned)
• ✅ Persistent API rate limit errors after 2+ retries
• ✅ Missing tools that should exist per skill definition

ETF Tool Selection

ETF 对比问题 workflow:

# BTC vs ETH ETF 对比
btc = cg_btc_etf_flows()
eth = cg_eth_etf_flows()
# Compare the latest day's net flows, summarize in 2-3 sentences

Quick Routing (use this first)

When to Use Coinglass

Use Coinglass for:

• Derivatives positioning - What are leveraged traders doing?
• Whale tracking - Track large positions on Hyperliquid DEX
• Funding rates - Cost of holding perpetual futures
• Open interest - Total notional value of open positions
• Long/Short ratios - Sentiment among leveraged traders (global, top accounts, top positions)
• Liquidations - Forced position closures with heatmaps and individual orders
• Volume analysis - Taker volume, CVD, netflow patterns
• ETF flows - Institutional adoption (Bitcoin, Ethereum, Solana, XRP, Hong Kong)
• Whale transfers - Large on-chain movements (>$10M)
• Futures market data - Supported coins, exchanges, pairs, and OHLC price history

Tool Categories

1. Basic Derivatives Analytics (7 tools)

Core derivatives data for market analysis:

• funding_rate(symbol, exchange?) - Current funding rates
• longshortratio(symbol, exchange?, interval?) - Basic L/S ratios
• cgopeninterest(symbol) - Current OI across exchanges
• cg_liquidations(symbol, time?) - Recent liquidations
• cgliquidationanalysis(symbol) - Liquidation heatmap analysis
• cgsupportedcoins() - All supported coins
• cgsupportedexchanges() - All exchanges with pairs

2. Advanced Long/Short Ratios (6 tools)

Deep positioning analysis with multiple metrics:

• cgglobalaccount_ratio(symbol, interval?) - Global account-based L/S ratio
• cgtopaccount_ratio(symbol, exchange, interval?) - Top trader accounts ratio
• cgtopposition_ratio(symbol, exchange, interval?) - Top positions by size
• cgtakerexchanges(symbol) - Taker buy/sell by exchange
• cgnetposition(symbol, exchange) - Net long/short positions
• cgnetposition_v2(symbol) - Enhanced net position data

Use cases:

• Smart money tracking (top accounts vs retail)
• Exchange-specific sentiment
• Position size distribution analysis

3. Advanced Liquidations (4 tools)

Granular liquidation tracking for cascade prediction:

• cgcoinliquidationhistory(symbol, interval?, limit?, starttime?, end_time?) - Aggregated across all exchanges
• cgpairliquidationhistory(symbol, exchange, interval?, limit?, starttime?, end_time?) - Exchange-specific pair
• cgliquidationcoin_list(exchange) - All coins on an exchange
• cgliquidationorders(symbol, exchange, minliquidationamount, starttime?, endtime?) - Individual orders (past 7 days, max 200)

Use cases:

• Identifying liquidation clusters
• Tracking liquidation patterns over time
• Finding large liquidation events

4. Hyperliquid Whale Tracking (4 tools)

Track large traders on Hyperliquid DEX (~200 recent alerts):

• cghyperliquidwhale_alerts() - Recent large position opens/closes (>$1M)
• cghyperliquidwhale_positions() - Current whale positions with PnL
• cghyperliquidpositionsbycoin() - All positions grouped by coin
• cghyperliquidposition_distribution() - Distribution by size with sentiment

Use cases:

• Following smart money on Hyperliquid
• Detecting large position changes
• Tracking whale PnL and sentiment

5. Futures Market Data (5 tools)

Market overview and price data:

• cgcoinsmarket_data() - ALL coins data in one call (100+ coins)
• cgpairmarket_data(symbol, exchange) - Specific pair metrics
• cgohlchistory(symbol, exchange, interval, limit?) - OHLC candlesticks
• cgtakervolumehistory(symbol, exchange, interval, limit?, starttime?, end_time?) - Pair-specific taker volume
• cgaggregatedtakervolume(symbol, interval, limit?, starttime?, end_time?) - Aggregated across exchanges

Use cases:

• Market screening (scan all coins at once)
• Price action analysis
• Volume pattern recognition

6. Volume & Flow Analysis (4 tools)

Order flow and capital movement tracking:

• cgcumulativevolumedelta(symbol, exchange, interval, limit?, starttime?, end_time?) - CVD = Running total of (buy - sell)
• cgcoinnetflow() - Capital flowing into/out of coins
• cgwhaletransfers() - Large on-chain transfers (>$10M, past 6 months)

Use cases:

• Order flow divergence detection
• Smart money tracking
• Institutional movement monitoring

7. Bitcoin ETF Data (5 tools)

Track institutional Bitcoin adoption:

• cgbtcetf_flows() - Daily net inflows/outflows
• cgbtcetfpremiumdiscount() - ETF price vs NAV
• cgbtcetf_history() - Comprehensive history (price, NAV, premium%, shares, assets)
• cgbtcetf_list() - List of Bitcoin ETFs
• cghkbtcetfflows() - Hong Kong Bitcoin ETF flows

Use cases:

• Institutional demand tracking
• Premium/discount arbitrage
• Regional flow comparison (US vs Hong Kong)

8. Other ETF Data (8 tools)

Ethereum, Solana, XRP, and Hong Kong ETFs:

• cgethetf_flows() - Ethereum ETF flows
• cgethetf_list() - Ethereum ETF list
• cgethetfpremiumdiscount() - ETH ETF premium/discount
• cgsoletf_flows() - Solana ETF flows
• cgsoletf_list() - Solana ETF list
• cgxrpetf_flows() - XRP ETF flows
• cgxrpetf_list() - XRP ETF list
• cghkethetfflows() - Hong Kong Ethereum ETF flows

Use cases:

• Multi-asset institutional tracking
• Comparative flow analysis
• Regional preference analysis

Common Workflows

Quick Market Scan

# Get everything in 3 calls
all_coins = cg_coins_market_data()  # 100+ coins with full metrics
btc_liquidations = cg_liquidations("BTC")
whale_alerts = cg_hyperliquid_whale_alerts()

Deep Position Analysis

# BTC positioning across metrics
cg_global_account_ratio("BTC")  # Retail sentiment
cg_top_account_ratio("BTC", "Binance")  # Smart money
cg_net_position_v2("BTC")  # Net positioning
cg_liquidation_heatmap("BTC", "Binance")  # Cascade levels

ETF Flow Monitoring

# Institutional demand
btc_flows = cg_btc_etf_flows()
eth_flows = cg_eth_etf_flows()
sol_flows = cg_sol_etf_flows()

Whale Tracking

# Follow the whales
hyperliquid_whales = cg_hyperliquid_whale_alerts()
whale_positions = cg_hyperliquid_whale_positions()
onchain_whales = cg_whale_transfers()  # >$10M on-chain

Volume Analysis

# Order flow
cvd = cg_cumulative_volume_delta("BTC", "Binance", "1h", 100)
netflow = cg_coin_netflow()  # All coins
taker_vol = cg_aggregated_taker_volume("BTC", "1h", 100)

Interpretation Guides

Funding Rates

Extreme funding often precedes reversals. The crowd is usually wrong at extremes.

Open Interest + Price Matrix

Long/Short Ratio

CVD (Cumulative Volume Delta)

ETF Flows

Analysis Patterns

Multi-metric confirmation: Combine tools across categories for high-confidence signals:

• Funding + L/S ratio + liquidations = positioning extremes
• CVD + taker volume + whale alerts = smart money direction
• ETF flows + whale transfers + open interest = institutional conviction

Smart money vs retail: Compare metrics to identify divergence:

• cgtopaccountratio (smart money) vs cgglobalaccountratio (retail)
• Hyperliquid whale positions vs overall long/short ratios

Cascade prediction: Use liquidation tools to predict volatility:

• cgcoinliquidation_history shows liquidation patterns over time
• cgliquidationorders reveals recent forced closures
• Large liquidation events = cascade risk zones

Flow divergence: Track capital movements:

• cgcoinnetflow shows where money is flowing
• cgwhaletransfers reveals large movements
• ETF flows show institutional demand

Performance Optimization

Batch vs Individual Calls

✅ OPTIMAL: Use batch endpoints

# One call gets 100+ coins
all_coins = cg_coins_market_data()

# One call gets all whale alerts
whales = cg_hyperliquid_whale_alerts()

# One call gets all ETF flows
btc_etf = cg_btc_etf_flows()

❌ INEFFICIENT: Multiple individual calls

# Don't do this - wastes API quota
btc = cg_pair_market_data("BTC", "Binance")
eth = cg_pair_market_data("ETH", "Binance")
sol = cg_pair_market_data("SOL", "Binance")

Query Parameters

Most history endpoints support:

• interval: Time granularity (1h, 4h, 12h, 24h, etc.)
• limit: Number of records (default varies, max 1000)
• start_time: Unix timestamp (milliseconds)
• end_time: Unix timestamp (milliseconds)

Example:

cg_coin_liquidation_history(
    symbol="BTC",
    interval="1h",
    limit=100,
    start_time=1704067200000,  # 2024-01-01
    end_time=1704153600000     # 2024-01-02
)

Supported Exchanges

Major exchanges with futures data:

• Tier 1: Binance, OKX, Bybit, Gate, KuCoin, MEXC
• Traditional: CME (Bitcoin and Ethereum futures), Coinbase
• DEX: Hyperliquid, dYdX, ApeX
• Others: Bitfinex, Kraken, HTX, BingX, Crypto.com, CoinEx, Bitget

Use cgsupportedexchanges() for complete list with pair details.

Important Notes

• API Key: Requires COINGLASSAPIKEY environment variable
• Symbols: Use standard symbols (BTC, ETH, SOL, etc.) - check with cgsupportedcoins()
• Exchanges: Check cgsupportedexchanges() for full list with pairs
• Update Frequency:

- Market data: ≤ 1 minute - Funding rates: Every 8 hours (or 1 hour for some exchanges) - OHLC: Real-time to 1 minute depending on interval - ETF data: Daily (after market close) - Whale transfers: Real-time (within minutes)

• API Versions:

- V4 endpoints use CG-API-KEY header (most tools) - V2 endpoints use coinglassSecret header (some legacy tools) - Both work with the same COINGLASSAPIKEY environment variable

• Rate Limits: Professional plan allows 6000 requests/minute
• Historical Data Limits:

- Liquidation orders: Past 7 days, max 200 records - Whale transfers: Past 6 months, minimum $10M - Hyperliquid alerts: ~200 most recent large positions - Other endpoints: Typically months to years of history

Data Quality Notes

• Hyperliquid: Data is exchange-specific, doesn't include other DEXs
• Whale Transfers: Covers Bitcoin, Ethereum, Tron, Ripple, Dogecoin, Litecoin, Polygon, Algorand, Bitcoin Cash, Solana
• ETF Data: US ETFs updated after market close (4 PM ET), Hong Kong ETFs updated after Hong Kong market close
• Liquidation Orders: Limited to 200 most recent, use heatmap for broader view
• CVD: Cumulative metric - resets are not automatic, track changes not absolute values

Version History

• v3.0.0 (2025-03): Added 36 new tools

- Advanced liquidations (5 tools) - Hyperliquid whale tracking (5 tools) - Volume & flow analysis (5 tools) - Whale transfers (1 tool) - Bitcoin ETF (6 tools) - Other ETFs (8 tools) - Advanced L/S ratios (6 tools)

• v2.2.0 (2024): V4 API migration with futures market data
• v1.0.0 (2024): Initial release with basic derivatives data