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

# 全市场聚合热力图（推荐，无需指定交易所）
# 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}  # 空头清算（↑触发）

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