coinglass

套餐等级（平台密钥 = Startup，已于 2026-09 验证）

平台注入的 COINGLASS_API_KEY 属于 Startup 套餐。工具层实际可访问的端点：

✅ Startup 套餐可用（常规数据）：

• 资金费率（v2/v4）、支持的币种/交易所/交易对、交易对市场
• 未平仓合约量（当前值 / OHLC 历史数据 / 汇总历史数据）
• 多空比（全局 / 大户账户 / 大户持仓）
• 主动买入/卖出量（单个交易所 + 汇总；汇总需要 exchange_list）
• CVD、净持仓（v1/v2）、币种净流入
• 清算：币种列表、币种/交易对历史数据（交易对需使用 BTCUSDT 格式）、汇总历史数据（需要 exchange_list）
• ETF 流量 / 列表 / 溢价（BTC、ETH、SOL、XRP、HK）
• 巨鲸转账、Hyperliquid 巨鲸提醒（仅提醒信息流）
• 价格历史（symbol 必须为交易对格式，例如 BTCUSDT）

❌ Startup 套餐不可用（401「Upgrade plan」——跳过这些端点，不要调用）：

• api/futures/coins-markets（全币种市场摘要，即 cg_coins_market_data）——不要调用；请使用下方“全市场 / 多币种 OI 路由”
• api/futures/liquidation/order（单笔清算订单）
• api/futures/liquidation/heatmap/model1 + aggregated-heatmap/model1（清算热力图完全不可用）
• api/hyperliquid/position、api/hyperliquid/wallet/position-distribution（Hyperliquid 持仓分布；仅巨鲸提醒可用）

替代方案（按优先级排序）：

1. 用户提供自己的密钥（Basic+ 套餐）：设置 COINGLASS_API_KEY 并直接调用 https://open-api-v4.coinglass.com，绕过 sc-proxy（sc-proxy 会覆盖该请求头，因此用户密钥对代理路径不起作用）。
2. Apify 抓取工具：使用 apify 技能抓取 coinglass.com 上的清算热力图 / Hyperliquid 持仓页面。

收到 401「Upgrade plan」响应时，cg_request 会抛出 CoinglassPlanError，错误消息中已包含这些指引。

全市场 / 多币种 OI 路由（coins-markets 不可用）

需求	使用方式	备注
单个币种的当前 OI 和 4 小时 / 24 小时变化	cg_open_interest(symbol)（取 exchangeName=="All" 的行）	Startup 套餐可用
单个币种的资金费率	funding_rate(symbol)	返回带 % 的字符串
跨币种 OI 历史数据	按币种获取 OI 历史数据，并按时间戳求和	标注为“Top-N 汇总”并注明柱状图间隔；绝不可将其标示为全市场数据
全市场当前 OI 总量 / 各币种当前 OI	coingecko 技能 cg_derivatives(include_tickers='unexpired')：保留 contract_type=="perpetual" 的记录，按 index_id 汇总 open_interest（USD）	交易所报告数据，包含小型交易所，数值高于 CoinGlass；仅提供当前值，没有历史数据；图表和正文中始终注明来源

不要在同一张图表上绘制来自不同来源（CoinGlass Top-N、CoinGecko 全市场、Bloomberg 或其他第三方）的数据，并将其作为对比或参考线。

清算热力图（❌ Startup 套餐不可用 — 已归档用法）

cg_liquidation_analysis 返回的全为零，无法使用。两个热力图端点（heatmap/model1 和 aggregated-heatmap/model1）在 Startup 套餐下均返回 401 Upgrade plan。

如果需要热力图数据：请用户提供 Basic+ 密钥并直接调用（见上方替代方案），或使用 Apify 抓取页面。

# Only works with a user-owned higher-tier key (direct, not via sc-proxy)
from tools._api import cg_request

# Full-market aggregated heatmap (recommended, no exchange needed)
# range supports: 12h, 24h, 3d, 7d, 30d, 90d, 180d, 1y
data = cg_request("api/futures/liquidation/aggregated-heatmap/model1",
                  params={"symbol": "BTC", "range": "24h"})

# Response structure:
# data["y_axis"]                   → price levels (low to high)
# data["liquidation_leverage_data"] → [[y_idx, leverage, usd_value], ...]
# data["price_candlesticks"]        → OHLCV candles; last close = current price
# data["update_time"]               → update timestamp

# How to parse:
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}  # long liquidations (triggered on the way down)
shorts = {p: v for p, v in price_liq.items() if p > current_price}  # short liquidations (triggered on the way up)

脚本用法

脚本模式技能 — 阅读此文件，然后在 bash 代码块中调用：

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

阅读 exports.py，查看可用函数的完整列表和准确签名。常用函数：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 提供最全面的加密货币衍生品和机构数据。37 个工具涵盖期货持仓、巨鲸追踪、成交量分析、清算和 ETF 资金流。

API 计划：Startup（平台密钥已降级；请参阅顶部的“计划层级”） 速率限制：此计划的请求限额较低；请控制批量调用的规模 API 版本：V4（向后兼容 V2） 工具总数：8 个类别共 37 个

函数参考（完整签名和返回结构）

所有函数均位于 exports.py 中。大多数函数返回 Optional[List[Dict]] 或 Optional[Dict]。None 表示上游调用失败或返回空值 — 索引前务必检查。

⚠️ 字段命名约定（请先阅读）

CoinGlass v4 API 的几乎所有数据字段都采用驼峰命名法，清算端点中有少数旧版蛇形命名例外。不要假设字段采用 蛇形命名法 — 请先用 inspect 检查字典。

• 驼峰命名：openInterest、volUsd、longRate、shortVolUsd、 exchangeName、nextFundingTime、fundingIntervalHours、 oichangePercent、h4OIChangePercent、avgFundingRateBySymbol、 tokenAmount、liquidationUsd（部分端点中）
• 蛇形命名（旧版，仅用于 cg_liquidations）：liquidation_usd、 longLiquidation_usd、shortLiquidation_usd
• rate 字段（资金费率）是包含“+”“-”“%”的字符串 — 使用 float(r.rstrip('%').lstrip('+')) 转换后再进行数值比较
• avgFundingRateBySymbol（cg_open_interest 的行中）是数值，且 已经是百分比 — 0.005313 表示 0.0053%/8h。不要乘以 100。合理性范围：BTC 资金费率通常约为 ±0.01%/8h；高于 ~0.1%/8h 的数值几乎肯定是单位错误。
• 时间戳是毫秒级 Unix 纪元时间（例如 1777881600000）

资金费率和未平仓合约

函数	签名
funding_rate(symbol, exchange=None)	dict — 键：symbol、exchange、rate（str）、num_exchanges、exchanges_data（包含 {exchangeName、rate、nextFundingTime、fundingIntervalHours、status} 的列表）
cg_open_interest(symbol='BTC', interval='0')	dict 列表（每个交易所一项）— 键：symbol、openInterest、volUsd、oichangePercent、h4OIChangePercent、h24VolChangePercent、volChangePercent7d、avgFundingRateBySymbol、exchangeName、exchangeLogo

多空比

函数	签名
long_short_ratio(symbol='BTC', interval='h4')	LIST — 第一项为汇总数据；内部的 list 字段包含各交易所的明细。键：longRate、shortRate、longVolUsd、shortVolUsd、totalVolUsd、list
cg_global_account_ratio(symbol='BTC', exchange='Binance', interval='1h')	历史柱列表
cg_top_account_ratio(symbol='BTC', exchange='Binance', interval='1h')	list — 顶级交易者账户数量比
cg_top_position_ratio(symbol='BTC', exchange='Binance', interval='1h')	list — 顶级交易者持仓规模比
cg_taker_exchanges(symbol='BTC', range_type='4h')	list — 各交易所的 Taker 买入/卖出数据
cg_net_position(symbol='BTC', exchange='Binance', interval='1h')	list — 随时间变化的净多空美元金额

强平

Function	Signature
cg_liquidations(symbol='BTC', time_type='h24')	字典列表（每个交易所一项，并以 'All' 行开头）。键：exchange、liquidation_usd、longLiquidation_usd、shortLiquidation_usd（注意：历史遗留的蛇形命名字段）
cg_liquidation_analysis(symbol='BTC', time_type='h24')	字典 — 全网汇总统计数据
cg_coin_liquidation_history(symbol='BTC', interval='h4')	列表 — 历史强平柱状数据
cg_pair_liquidation_history(symbol='BTC', exchange='Binance', interval='h4')	列表 — 单个交易所中某个交易对的历史强平数据
cg_liquidation_coin_list(symbol=None)	所有币种及其强平摘要的列表
cg_liquidation_orders(symbol='BTC', exchange=None)	列表 — 最近的单笔强平订单

期货市场数据

Function	Signature
cg_supported_coins()	List[str] — CoinGlass 支持的交易代码
cg_supported_exchanges()	交易所信息字典列表
cg_coins_market_data(symbol=None)	❌ Startup 不可用（401）— 请参阅“全市场 / 多币种 OI 路由”
cg_pair_market_data(symbol='BTC', exchange=None)	列表 — 交易对级别快照
cg_ohlc_history(symbol='BTC', interval='h4', exchange=None)	OHLCV 柱状数据列表

Hyperliquid 鲸鱼追踪

Function	Signature
cg_hyperliquid_whale_alerts()	列表 — 最近的大额持仓提醒
cg_hyperliquid_whale_positions()	列表 — 当前未平仓的鲸鱼持仓
cg_hyperliquid_positions_by_coin(symbol='BTC')	列表 — 持有特定币种的鲸鱼
cg_hyperliquid_position_distribution(symbol='BTC')	字典 — 多头 / 空头持仓规模分布

成交量 / 资金流

Function	Signature
cg_taker_volume_history(symbol='BTC', exchange='Binance', interval='1h', limit=1000, start_time=None, end_time=None)	列表 — Taker 买入 / 卖出成交量柱状数据
cg_aggregated_taker_volume(symbol='BTC', interval='h4')	列表 — 所有交易所的汇总数据
cg_cumulative_volume_delta(symbol='BTC', exchange='Binance', interval='1h', limit=1000, start_time=None, end_time=None)	列表 — CVD 柱状数据
cg_coin_netflow(symbol=None)	列表 — 各币种的净流入 / 流出
cg_whale_transfers()	字典 — 最近的大额链上转账

ETF 资金流

Function	Signature
cg_btc_etf_flows()	列表 — 各美国 BTC ETF 的每日资金流
cg_btc_etf_history(etf_ticker=None)	列表 — 历史 AUM / 资金流
cg_btc_etf_list()	BTC ETF 代码及 AUM 列表
cg_btc_etf_premium_discount()	列表 — 相对于 NAV 的溢价 / 折价百分比
cg_hk_btc_etf_flows()	列表 — 香港 BTC ETF 资金流
cg_eth_etf_flows() / cg_eth_etf_list() / cg_eth_etf_premium_discount() / cg_hk_eth_etf_flows()	ETH ETF 对应数据
cg_sol_etf_flows() / cg_sol_etf_list()	SOL ETF 数据
cg_xrp_etf_flows() / cg_xrp_etf_list()	XRP ETF 数据

示例响应（最常用的函数）

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}
  ]
}

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

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

cg_open_interest(symbol="BTC")：

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

long_short_ratio(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, ...}
  ]
}]

工具选择指南

决策树

步骤 1：是否与强平有关？

Liquidation query?
├─ YES → How many coins?
│   ├─ ALL coins / ranking / summary
│   │   └─ → 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")

步骤 2：是否与多空比有关？

Long/short query?
├─ Historical time-series, trend over time, L/S ratio change
│   └─ → 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

步骤 3：是否与未平仓合约量有关？

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

步骤 4：是否为市场概览 / 情绪查询？

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

---

关键词 → 工具查找

关键词 / 模式	正确工具	❌ 请勿使用
强平排名 / 今日强平 / 所有币种强平	cg_liquidation_coin_list	cg_liquidations
24 小时强平摘要	cg_liquidation_coin_list	cg_liquidation_analysis
全局账户多空比	cg_global_account_ratio	long_short_ratio
顶级交易者多空比	cg_top_account_ratio	long_short_ratio
未平仓合约量	cg_open_interest	cg_coins_market_data
市场情绪 / 持仓分析	funding_rate + long_short_ratio + cg_open_interest	cg_coins_market_data
BTC 做多交易前检查清单	funding_rate + cg_global_account_ratio + cg_liquidation_coin_list	—

---

常见错误

错误 1（最常见 — 失败率高 8 倍）：需要使用 cg_liquidation_coin_list 时却用了 cg_liquidations

• cg_liquidations → 单个币种、单个时间范围，仅提供基本总量
• cg_liquidation_coin_list(exchange) → 所有币种、多时间范围（1h/4h/12h/24h），按交易所细分
• 规则： 如果问题询问排名、概览，或未指定单个币种 → 使用 cg_liquidation_coin_list

错误 2（失败率高 5 倍）：使用 cg_liquidation_analysis 查询强平排名

• cg_liquidation_analysis 会为单个币种的强平总量添加情绪标签——它不是排名工具
• 规则：“今日强平排名” / “按币种划分的强平” → 始终使用 cg_liquidation_coin_list

错误 3（失败率高 3 倍）：使用 long_short_ratio 进行历史多空比分析

• long_short_ratio 是当前快照（不含时间序列）
• cg_global_account_ratio 返回历史数据——用户想了解趋势或进行跨时间比较时使用它
• 规则： 如果问题比较全局账户和顶级交易者 → 同时调用 cg_global_account_ratio 和 cg_top_account_ratio

错误 4（失败率高 2 倍）：使用 cg_coins_market_data 查询未平仓合约量

• cg_coins_market_data 是多个币种的批量快照——不能替代专用的未平仓合约量或多空比工具
• 规则： 未平仓合约量问题 → cg_open_interest。多空比问题 → long_short_ratio 或 cg_global_account_ratio。绝不要将这两类问题交给 cg_coins_market_data。

规则

工具调用指南

❌ 禁止使用的工具——绝不要使用：

• bash — 不要编写脚本来处理或整理数据。请使用自然语言。
• write_file / read_file / edit_file — 不要保存中间数据。直接作答。
• learning_log — 仅用于真正的技能错误或持续出现的 API 错误。不要用于空响应。
• echo — 不要用于调试或输出。

✅ 正确模式：

• 工具返回数据 → 用自然语言总结 → 完成
• 工具返回空值或 null → 报告“无可用数据” → 完成
• 需要计算（百分比、变化、比率） → 在回复中进行心算

根据问题范围匹配工具数量：

• 单一指标问题（“BTC 资金费率”“ETH 多空比”） → 1 个工具，直接作答
• 多维分析（“现在适合做多吗”“衍生品健康检查”） → 3–5 个工具，综合分析
• 比较（“ETH 与 SOL”） → 对每个币种使用相同的工具，并排比较
• 避免重复调用同一工具，除非用户明确要求跨币种 / 跨交易所比较。

学习日志用法（重要）

以下情况禁止使用 learning_log：

• ❌ API 响应为空——只需报告“无可用数据”
• ❌ 工具返回 None/null——妥善处理
• ❌ 不确定该选哪个工具——先查看决策树
• ❌ 常规工具错误——重试一次，然后报告失败

learning_log 仅用于：

• ✅ 技能代码中存在真正的错误（返回的数据格式不正确）
• ✅ 重试 2 次以上后仍持续出现 API 速率限制错误
• ✅ 技能定义中应存在但缺失的工具

ETF 工具选择

查询	主要工具	次要工具
BTC ETF 流入／流出	cg_btc_etf_flows()	使用 cg_btc_etf_history() 查看详细历史记录
ETH ETF 流入／流出	cg_eth_etf_flows()	—
SOL/XRP ETF 流量	cg_sol_etf_flows() / cg_xrp_etf_flows()	—
香港 ETF 流量	cg_hk_btc_etf_flows() / cg_hk_eth_etf_flows()	—
ETF 列表／代码	cg_btc_etf_list() / cg_eth_etf_list()	—
ETF 溢价／折价	cg_btc_etf_premium_discount()	—

ETF 对比工作流：

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

快速路由（请先使用）

查询类型	工具
清算摘要（24 小时，按币种）	cg_liquidation_coin_list
单笔清算订单	cg_liquidation_orders
某币种的清算历史	cg_coin_liquidation_history
资金费率	funding_rate
多空比（全局）	cg_global_account_ratio
未平仓合约量	cg_open_interest
Hyperliquid 上的巨鲸活动	cg_hyperliquid_whale_alerts
ETF 流量（BTC）	cg_btc_etf_flows

何时使用 Coinglass

在以下情况使用 Coinglass：

• 衍生品仓位 - 杠杆交易者在做什么？
• 巨鲸追踪 - 追踪 Hyperliquid DEX 上的大额仓位
• 资金费率 - 持有永续期货的成本
• 未平仓合约量 - 未平仓仓位的名义价值总额
• 多空比 - 杠杆交易者的情绪（全局、顶级账户、顶级仓位）
• 清算 - 强制平仓，包含热力图和单笔订单
• 交易量分析 - 主动买卖量、CVD、净流量模式
• ETF 流量 - 机构采用情况（Bitcoin、Ethereum、Solana、XRP、香港）
• 巨鲸转账 - 大额链上资金转移（>10M 美元）
• 期货市场数据 - 支持的币种、交易所、交易对和 OHLC 价格历史

工具类别

1. 基础衍生品分析（7 个工具）

用于市场分析的核心衍生品数据：

• funding_rate(symbol, exchange?) - 当前资金费率
• long_short_ratio(symbol, exchange?, interval?) - 基础多空比
• cg_open_interest(symbol) - 各交易所当前 OI
• cg_liquidations(symbol, time?) - 近期清算
• cg_liquidation_analysis(symbol) - ❌ Startup 版本不可用（依赖热力图端点）
• cg_supported_coins() - 所有受支持的币种
• cg_supported_exchanges() - 所有提供交易对的交易所

2. 高级多空比（6 个工具）

使用多种指标深入分析仓位：

• cg_global_account_ratio(symbol, interval?) - 基于账户的全局多空比
• cg_top_account_ratio(symbol, exchange, interval?) - 顶级交易者账户多空比
• cg_top_position_ratio(symbol, exchange, interval?) - 按规模划分的顶级仓位
• cg_taker_exchanges(symbol) - 各交易所主动买入／卖出情况
• cg_net_position(symbol, exchange) - 净多头／空头仓位
• cg_net_position_v2(symbol) - 增强版净仓位数据

使用场景：

• 追踪聪明资金（对比顶级账户与散户）
• 分析特定交易所的市场情绪
• 分析仓位规模分布

3. 高级清算分析（4 个工具）

精细追踪清算情况，以预测清算连锁反应：

• cg_coin_liquidation_history(symbol, interval?, limit?, start_time?, end_time?) - 汇总所有交易所的数据
• cg_pair_liquidation_history(symbol, exchange, interval?, limit?, start_time?, end_time?) - 特定交易所的交易对
• cg_liquidation_coin_list(exchange) - 某交易所的所有币种
• cg_liquidation_orders(symbol, exchange, min_liquidation_amount, start_time?, end_time?) - 单笔订单（过去 7 天，最多 200 笔）

使用场景：

• 识别清算密集区
• 追踪清算模式随时间的变化
• 查找大额清算事件

4. Hyperliquid 巨鲸追踪（4 个工具）

追踪 Hyperliquid DEX 上的大额交易者（约 200 条近期提醒）：

• cg_hyperliquid_whale_alerts() - 近期大额仓位开仓／平仓（>$1M）
• cg_hyperliquid_whale_positions() - 巨鲸当前仓位及盈亏
• cg_hyperliquid_positions_by_coin() - 按币种分组的所有仓位
• cg_hyperliquid_position_distribution() - 按规模划分的仓位分布及市场情绪

适用场景：

• 跟踪 Hyperliquid 上的聪明资金
• 检测大额仓位变动
• 追踪巨鲸的盈亏和市场情绪

5. 期货市场数据（5 个工具）

市场概览和价格数据：

• cg_coins_market_data() - ❌ Startup 版不提供；多币种数据请参阅“全市场／多币种 OI 路由”
• cg_pair_market_data(symbol, exchange) - 特定交易对指标
• cg_ohlc_history(symbol, exchange, interval, limit?) - OHLC K 线
• cg_taker_volume_history(symbol, exchange, interval, limit?, start_time?, end_time?) - 特定交易对的主动成交量
• cg_aggregated_taker_volume(symbol, interval, limit?, start_time?, end_time?) - 跨交易所汇总的主动成交量

适用场景：

• 市场筛选（一次扫描所有币种）
• 价格走势分析
• 成交量模式识别

6. 成交量与资金流分析（4 个工具）

追踪订单流和资金流动：

• cg_cumulative_volume_delta(symbol, exchange, interval, limit?, start_time?, end_time?) - CVD =（买入量 - 卖出量）的累计值
• cg_coin_netflow() - 流入／流出币种的资金
• cg_whale_transfers() - 大额链上转账（>$10M，过去 6 个月）

适用场景：

• 检测订单流背离
• 追踪聪明资金
• 监控机构资金动向

7. Bitcoin ETF 数据（5 个工具）

追踪机构对 Bitcoin 的采用情况：

• cg_btc_etf_flows() - 每日净流入／流出
• cg_btc_etf_premium_discount() - ETF 价格与 NAV 的对比
• cg_btc_etf_history() - 全面历史数据（价格、NAV、溢价率、份额、资产）
• cg_btc_etf_list() - Bitcoin ETF 列表
• cg_hk_btc_etf_flows() - 香港 Bitcoin ETF 资金流

适用场景：

• 追踪机构需求
• 溢价／折价套利
• 比较不同地区的资金流（美国与香港）

8. 其他 ETF 数据（8 个工具）

Ethereum、Solana、XRP 和香港 ETF：

• cg_eth_etf_flows() - Ethereum ETF 资金流
• cg_eth_etf_list() - Ethereum ETF 列表
• cg_eth_etf_premium_discount() - ETH ETF 溢价／折价
• cg_sol_etf_flows() - Solana ETF 资金流
• cg_sol_etf_list() - Solana ETF 列表
• cg_xrp_etf_flows() - XRP ETF 资金流
• cg_xrp_etf_list() - XRP ETF 列表
• cg_hk_eth_etf_flows() - 香港 Ethereum ETF 资金流

适用场景：

• 追踪多种资产的机构动向
• 对比分析资金流
• 分析地区偏好

常见工作流

快速市场扫描

# Get everything in 3 calls
btc_oi = cg_open_interest("BTC")  # coins-markets is plan-gated on Startup
btc_liquidations = cg_liquidations("BTC")
whale_alerts = cg_hyperliquid_whale_alerts()

深入分析仓位

# 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
# Note: liquidation heatmap is unavailable on Startup; see "Plan Tiers" at the top

ETF 资金流监控

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

巨鲸追踪

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

成交量分析

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

解读指南

资金费率

费率（8h）	解读
> +0.05%	极度贪婪——多头拥挤，有挤仓风险
+0.01% 至 +0.05%	偏看涨，处于正常水平
-0.005% 至 +0.01%	中性
-0.05% 至 -0.005%	偏看跌，处于正常水平
< -0.05%	极度恐惧——空头拥挤，有反弹风险

极端资金费率通常预示着反转。市场参与者在极端情况下通常会判断错误。

未平仓合约 + 价格矩阵

OI	价格	解读
上升	上涨	新多头入场——看涨信心增强
上升	下跌	新空头入场——看跌信心增强
下降	上涨	空头回补——反弹较弱，信心不足
下降	下跌	多头清算——跌势较弱，出现投降式抛售

多空比

比率	解读
> 1.5	多头拥挤——反向看跌
1.1–1.5	温和看涨
0.9–1.1	均衡
0.7–0.9	温和看跌
< 0.7	空头拥挤——反向看涨

CVD（累计成交量差）

模式	解读
CVD 上升，价格上涨	买盘压力强劲，上涨趋势健康
CVD 下降，价格上涨	反弹乏力，处于派发阶段
CVD 上升，价格下跌	处于吸筹阶段，可能接近底部
CVD 下降，价格下跌	卖盘压力强劲，下跌趋势健康

ETF 资金流

资金流	解读
大量流入	机构买入，利好
持续流入	需求持续
大量流出	机构卖出，利空
溢价高于 NAV	需求旺盛，情绪看涨
折价低于 NAV	需求疲软，情绪看跌

分析模式

多指标确认：结合不同类别的工具，获取高置信度信号：

• 资金费率 + 多空比 + 强平 = 仓位极端情况
• CVD + 主动买卖量 + 巨鲸预警 = 聪明资金的动向
• ETF 资金流 + 巨鲸转账 + 未平仓合约 = 机构信心

聪明资金与散户对比：比较指标以识别背离：

• cg_top_account_ratio（聪明资金）与 cg_global_account_ratio（散户）
• Hyperliquid 巨鲸仓位与整体多空比

连锁强平预测：使用强平工具预测波动性：

• cg_coin_liquidation_history 显示强平模式随时间的变化
• cg_liquidation_orders 揭示近期的强制平仓
• 大规模强平事件 = 连锁强平风险区域

资金流背离：追踪资金流动：

• cg_coin_netflow 显示资金流向
• cg_whale_transfers 揭示大额资金流动
• ETF 资金流显示机构需求

性能优化

批量调用与单独调用

✅ 最优：使用批量端点

# Whole-market current OI: coingecko cg_derivatives (coins-markets is plan-gated)

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

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

❌ 效率低下：多次单独调用

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

查询参数

大多数历史数据端点支持：

• interval：时间粒度（1h、4h、12h、24h 等）
• limit：记录数量（默认值因端点而异，最大为 1000）
• start_time：Unix 时间戳（毫秒）
• end_time：Unix 时间戳（毫秒）

示例：

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

支持的交易所

提供期货数据的主要交易所：

• 一级：Binance、OKX、Bybit、Gate、KuCoin、MEXC
• 传统交易所：CME（Bitcoin 和 Ethereum 期货）、Coinbase
• DEX：Hyperliquid、dYdX、ApeX
• 其他：Bitfinex、Kraken、HTX、BingX、Crypto.com、CoinEx、Bitget

使用 cg_supported_exchanges() 获取包含交易对详情的完整列表。

重要说明

• API 密钥：需要 COINGLASS_API_KEY 环境变量
• 交易代码：使用标准交易代码（BTC、ETH、SOL 等），可通过 cg_supported_coins() 查看
• 交易所：通过 cg_supported_exchanges() 查看包含交易对的完整列表
• 更新频率：
  • 市场数据：≤ 1 分钟
  • 资金费率：每 8 小时更新一次（部分交易所为每 1 小时）
  • OHLC：根据时间间隔，从实时到 1 分钟不等
  • ETF 数据：每日更新（收盘后）
  • 巨鲸转账：实时更新（数分钟内）
• API 版本：
  • V4 端点使用 CG-API-KEY 请求头（大多数工具）
  • V2 端点使用 coinglassSecret 请求头（部分旧版工具）
  • 两者都使用同一个 COINGLASS_API_KEY 环境变量
• 速率限制：Startup 计划 — 控制批量轮询频率，避免紧密循环
• 历史数据限制：
  • 强平订单：过去 7 天，最多 200 条记录
  • 巨鲸转账：过去 6 个月，最低金额为 $10M
  • Hyperliquid 预警：约 200 个最新的大额仓位
  • 其他端点：通常提供数月至数年的历史数据
• 计划限制（Startup）：heatmap、liquidation/order、coins-markets、 Hyperliquid position 会返回 401 Upgrade plan（引发 CoinglassPlanError）。 如果用户需要这些数据 → 让他们提供自己的密钥（设置 COINGLASS_DIRECT=1 并使用自己的 COINGLASS_API_KEY 直接调用），或使用 Apify skill 抓取 coinglass.com 页面。

数据质量说明

• Hyperliquid：数据仅针对该交易所，不包含其他 DEX
• 巨鲸转账：覆盖 Bitcoin、Ethereum、Tron、Ripple、Dogecoin、Litecoin、Polygon、Algorand、Bitcoin Cash、Solana
• ETF 数据：美国 ETF 在收盘后（美国东部时间下午 4 点）更新，香港 ETF 在香港市场收盘后更新
• 清算订单：仅限最近 200 条，如需查看更广范围，请使用热力图
• CVD：累积指标——不会自动重置，请跟踪变化而非绝对值

版本历史

• v3.1.0（2026-09）：适配 Startup 计划
  • 将平台密钥降级为 Startup；记录完整的端点权限映射
  • 添加 CoinglassPlanError，并提供 BYOK / Apify 指南，说明 401「Upgrade plan」错误
  • 为用户提供的密钥添加 COINGLASS_DIRECT=1 直连模式（sc-proxy 会覆盖用户密钥）
  • 修复 4 个参数错误：币种/交易对清算历史（exchange_list / 交易对符号）、 聚合吃单量（exchange_list）、价格历史（交易对符号）
• v3.0.0（2025-03）：新增 36 个工具
  • 高级清算（5 个工具）
  • Hyperliquid 巨鲸追踪（5 个工具）
  • 成交量与资金流分析（5 个工具）
  • 巨鲸转账（1 个工具）
  • Bitcoin ETF（6 个工具）
  • 其他 ETF（8 个工具）
  • 高级多空比（6 个工具）
• v2.2.0（2024）：迁移至 V4 API，支持期货市场数据
• v1.0.0（2024）：初始版本，提供基础衍生品数据