coinglass

Plan 权限分级（平台 key = Startup 级，2026-09 实测）

平台注入的 COINGLASS_API_KEY 已降级为 Startup 计划。工具层对端点的实际权限：

✅ Startup 可用（全部正常数据）：

• Funding rates（v2/v4）、Supported coins/exchanges/pairs、Pairs markets
• Open interest（当前值 / OHLC history / aggregated history）
• Long/Short ratios（global / top-account / top-position）
• Taker buy/sell volume（单所 + aggregated，需 exchange_list）
• CVD、Net position（v1/v2）、Coin netflow
• Liquidations：coin-list、coin/pair history（pair 需 BTCUSDT 格式）、aggregated history（需 exchange_list）
• ETF flows / lists / premium（BTC、ETH、SOL、XRP、HK）
• Whale transfers、Hyperliquid whale alerts（仅 alert 流）
• Price history（symbol 需 pair 格式 BTCUSDT）

❌ Startup 不可用（401 "Upgrade plan"，调用前直接跳过）：

• api/futures/coins-markets（币种市场汇总）
• api/futures/liquidation/order（逐笔清算单）
• api/futures/liquidation/heatmap/model1 + aggregated-heatmap/model1（清算热力图整个不可用）
• api/hyperliquid/position、api/hyperliquid/wallet/position-distribution（Hyperliquid 持仓分布；仅 whale-alert 可用）

替代方案（按优先级）：

1. 用户提供自己的 key（Basic+ 计划）：设 COINGLASS_API_KEY 并绕过 sc-proxy 直连 https://open-api-v4.coinglass.com（sc-proxy 会强制覆盖该 header，代理路径下自带 key 无效）。
2. Apify 爬虫：用 apify skill 抓 coinglass.com 页面上的清算热力图 / Hyperliquid 持仓数据。

对 401 "Upgrade plan" 错误，cg_request 会抛 CoinglassPlanError，错误信息已含上述引导。

Liquidation Heatmap（❌ Startup 不可用 — 历史用法存档）

cg_liquidation_analysis 返回全0，不可用。热力图两个端点（heatmap/model1 与 aggregated-heatmap/model1）在 Startup 计划下均返回 401 Upgrade plan。

如需热力图数据：让用户自带 Basic+ key 直连（见上文替代方案），或用 Apify 爬取页面。

# 以下仅在用户自有高级 key 下可用（直连，不走 sc-proxy）
from tools._api import cg_request
 
# 全市场聚合热力图（推荐，无需指定交易所）

Script Usage

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

Read exports.py for the full list of available functions and exact signatures. Common ones: funding_rate, long_short_ratio, cg_open_interest, cg_liquidations, cg_liquidation_analysis, cg_global_account_ratio, cg_top_account_ratio, cg_top_position_ratio, cg_taker_exchanges, cg_net_position, cg_supported_coins, cg_supported_exchanges, cg_coins_market_data, cg_pair_market_data, cg_ohlc_history, cg_hyperliquid_whale_alerts, cg_hyperliquid_whale_positions, cg_taker_volume_history, cg_aggregated_taker_volume, cg_cumulative_volume_delta, cg_coin_netflow, cg_whale_transfers, cg_btc_etf_flows, cg_eth_etf_flows, cg_sol_etf_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: Startup (平台 key 已降级，见顶部「Plan 权限分级」) Rate Limit: 请求级限制随计划降低，控制批量调用频率 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 snake_case exceptions in liquidation endpoints. Don't assume snake_case — inspect the dict before scripting.

• camelCase: openInterest, volUsd, longRate, shortVolUsd, exchangeName, nextFundingTime, fundingIntervalHours, oichangePercent, h4OIChangePercent, avgFundingRateBySymbol, tokenAmount, liquidationUsd (in some endpoints)
• snake_case (legacy, only in cg_liquidations): liquidation_usd, longLiquidation_usd, shortLiquidation_usd
• 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"):

cg_liquidations(symbol="BTC", time_type="h24"):

cg_open_interest(symbol="BTC"):

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

Tool Selection Guide

Decision Tree

Step 1: Is this about LIQUIDATIONS?

Step 2: Is this about LONG/SHORT RATIO?

Step 3: Is this about OPEN INTEREST?

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

Keyword → Tool Lookup

Common Mistakes

Mistake 1 (most common — 8x failure): Using cg_liquidations when you need cg_liquidation_coin_list

• cg_liquidations → one coin, one timeframe, basic total only
• cg_liquidation_coin_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 cg_liquidation_coin_list

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

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

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

• long_short_ratio is a current snapshot (no time-series)
• cg_global_account_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 cg_global_account_ratio AND cg_top_account_ratio

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

• cg_coins_market_data is a bulk snapshot of many coins — not a replacement for dedicated OI or L/S tools
• Rule: OI question → cg_open_interest. L/S question → long_short_ratio or cg_global_account_ratio. Never route either to cg_coins_market_data.

Rules

Tool Call Guidance

❌ FORBIDDEN TOOLS — NEVER USE:

• bash — Do NOT write scripts to process/format data. Use natural language.
• write_file / read_file / 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:

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
• long_short_ratio(symbol, exchange?, interval?) - Basic L/S ratios
• cg_open_interest(symbol) - Current OI across exchanges
• cg_liquidations(symbol, time?) - Recent liquidations
• cg_liquidation_analysis(symbol) - ❌ Startup 下不可用（依赖 heatmap 端点）
• cg_supported_coins() - All supported coins
• cg_supported_exchanges() - All exchanges with pairs

2. Advanced Long/Short Ratios (6 tools)

Deep positioning analysis with multiple metrics:

• cg_global_account_ratio(symbol, interval?) - Global account-based L/S ratio
• cg_top_account_ratio(symbol, exchange, interval?) - Top trader accounts ratio
• cg_top_position_ratio(symbol, exchange, interval?) - Top positions by size
• cg_taker_exchanges(symbol) - Taker buy/sell by exchange
• cg_net_position(symbol, exchange) - Net long/short positions
• cg_net_position_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:

• cg_coin_liquidation_history(symbol, interval?, limit?, start_time?, end_time?) - Aggregated across all exchanges
• cg_pair_liquidation_history(symbol, exchange, interval?, limit?, start_time?, end_time?) - Exchange-specific pair
• cg_liquidation_coin_list(exchange) - All coins on an exchange
• cg_liquidation_orders(symbol, exchange, min_liquidation_amount, start_time?, end_time?) - 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):

• cg_hyperliquid_whale_alerts() - Recent large position opens/closes (>$1M)
• cg_hyperliquid_whale_positions() - Current whale positions with PnL
• cg_hyperliquid_positions_by_coin() - All positions grouped by coin
• cg_hyperliquid_position_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:

• cg_coins_market_data() - ALL coins data in one call (100+ coins)
• cg_pair_market_data(symbol, exchange) - Specific pair metrics
• cg_ohlc_history(symbol, exchange, interval, limit?) - OHLC candlesticks
• cg_taker_volume_history(symbol, exchange, interval, limit?, start_time?, end_time?) - Pair-specific taker volume
• cg_aggregated_taker_volume(symbol, interval, limit?, start_time?, 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:

• cg_cumulative_volume_delta(symbol, exchange, interval, limit?, start_time?, end_time?) - CVD = Running total of (buy - sell)
• cg_coin_netflow() - Capital flowing into/out of coins
• cg_whale_transfers() - 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:

• cg_btc_etf_flows() - Daily net inflows/outflows
• cg_btc_etf_premium_discount() - ETF price vs NAV
• cg_btc_etf_history() - Comprehensive history (price, NAV, premium%, shares, assets)
• cg_btc_etf_list() - List of Bitcoin ETFs
• cg_hk_btc_etf_flows() - 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:

• cg_eth_etf_flows() - Ethereum ETF flows
• cg_eth_etf_list() - Ethereum ETF list
• cg_eth_etf_premium_discount() - ETH ETF premium/discount
• cg_sol_etf_flows() - Solana ETF flows
• cg_sol_etf_list() - Solana ETF list
• cg_xrp_etf_flows() - XRP ETF flows
• cg_xrp_etf_list() - XRP ETF list
• cg_hk_eth_etf_flows() - Hong Kong Ethereum ETF flows

Use cases:

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

Common Workflows

Quick Market Scan

Deep Position Analysis

ETF Flow Monitoring

Whale Tracking

Volume Analysis

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:

• cg_top_account_ratio (smart money) vs cg_global_account_ratio (retail)
• Hyperliquid whale positions vs overall long/short ratios

Cascade prediction: Use liquidation tools to predict volatility:

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

Flow divergence: Track capital movements:

• cg_coin_netflow shows where money is flowing
• cg_whale_transfers reveals large movements
• ETF flows show institutional demand

Performance Optimization

Batch vs Individual Calls

✅ OPTIMAL: Use batch endpoints

❌ INEFFICIENT: Multiple individual calls

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:

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 cg_supported_exchanges() for complete list with pair details.

Important Notes

• API Key: Requires COINGLASS_API_KEY environment variable
• Symbols: Use standard symbols (BTC, ETH, SOL, etc.) - check with cg_supported_coins()
• Exchanges: Check cg_supported_exchanges() 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 COINGLASS_API_KEY environment variable
• Rate Limits: Startup plan — keep batch polling modest; avoid tight loops
• 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
• Plan gating (Startup): heatmap、liquidation/order、coins-markets、 Hyperliquid position 返回 401 Upgrade plan（会抛 CoinglassPlanError）。 用户需要这些数据 → 让用户提供自己的 key（COINGLASS_DIRECT=1 + 自有 COINGLASS_API_KEY 直连），或用 Apify skill 爬 coinglass.com 页面。

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.1.0 (2026-09): Startup plan adaptation
  • Platform key downgraded to Startup; documented full endpoint permission map
  • Added CoinglassPlanError with BYOK / Apify guidance on 401 "Upgrade plan"
  • Added COINGLASS_DIRECT=1 direct mode for user-supplied keys (sc-proxy overwrites user keys)
  • Fixed 4 parameter bugs: coin/pair liquidation history (exchange_list / pair symbol), aggregated taker volume (exchange_list), price history (pair symbol)
• 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