1---
2name: coinglass
3version: 3.0.4
4description: |
5  Crypto derivatives data: funding rates, open interest, liquidations, long/short ratios.
6 
7  Use when researching perp markets, tracking Hyperliquid whale positions, or comparing ETF flows (e.g. BTC funding, ETH OI, liquidation heatmap).
8delivery: script
9metadata:
10  starchild:
11    emoji: 📈
12    skillKey: coinglass
13    plan: professional
14    api_version: v4
15    version: 3.0.3
16    total_tools: 37
17    requires:
18      env:
19      - COINGLASS_API_KEY
20user-invocable: false
21disable-model-invocation: false
22 
23---
24 
25## Liquidation Heatmap（真正的价格区间清算压力）
26 
27`cg_liquidation_analysis` 返回全0，不可用。正确做法是直接调 API：
28 
29```python
30from tools._api import cg_request
31 
32# 全市场聚合热力图（推荐，无需指定交易所）
33# range 支持: 12h, 24h, 3d, 7d, 30d, 90d, 180d, 1y
34data = cg_request("api/futures/liquidation/aggregated-heatmap/model1",
35                  params={"symbol": "BTC", "range": "24h"})
36 
37# 返回结构：
38# data["y_axis"]                   → 价格档位列表（从低到高）
39# data["liquidation_leverage_data"] → [[y_idx, leverage, usd_value], ...]
40# data["price_candlesticks"]        → OHLCV K线，最后一根收盘价 = 当前价
41# data["update_time"]               → 更新时间戳
42 
43# 解析方法：
44from collections import defaultdict
45y_axis = data["y_axis"]
46current_price = float(data["price_candlesticks"][-1][4])
47price_liq = defaultdict(float)
48for y_idx, leverage, usd_val in data["liquidation_leverage_data"]:
49    if 0 <= y_idx < len(y_axis):
50        price_liq[y_axis[y_idx]] += usd_val
51 
52longs  = {p: v for p, v in price_liq.items() if p < current_price}  # 多头清算（↓触发）
53shorts = {p: v for p, v in price_liq.items() if p > current_price}  # 空头清算（↑触发）
54```
55 
56注意：单交易所版本（`heatmap/model1` 带 exchange 参数）当前会报 400 错误，改用 aggregated 版本。
57 
58## Script Usage
59 
60Script-mode skill — read this file, then invoke from a `bash` block:
61 
62```bash
63python3 - <<'EOF'
64import sys, json
65sys.path.insert(0, "/data/workspace/skills/coinglass")
66from exports import funding_rate, cg_open_interest, cg_liquidations
67 
68print(funding_rate(symbol="BTC"))
69print(cg_open_interest(symbol="BTC"))
70EOF
71```
72 
73Read `exports.py` for the full list of available functions and exact
74signatures. Common ones: `funding_rate`, `long_short_ratio`,
75`cg_open_interest`, `cg_liquidations`, `cg_liquidation_analysis`,
76`cg_global_account_ratio`, `cg_top_account_ratio`, `cg_top_position_ratio`,
77`cg_taker_exchanges`, `cg_net_position`, `cg_supported_coins`,
78`cg_supported_exchanges`, `cg_coins_market_data`, `cg_pair_market_data`,
79`cg_ohlc_history`, `cg_hyperliquid_whale_alerts`,
80`cg_hyperliquid_whale_positions`, `cg_taker_volume_history`,
81`cg_aggregated_taker_volume`, `cg_cumulative_volume_delta`,
82`cg_coin_netflow`, `cg_whale_transfers`, `cg_btc_etf_flows`,
83`cg_eth_etf_flows`, `cg_sol_etf_flows`.
84 
85 
86# Coinglass
87 
88Coinglass provides the most comprehensive crypto derivatives and institutional data available. 37 tools covering futures positioning, whale tracking, volume analysis, liquidations, and ETF flows.
89 
90**API Plan**: Professional ($699/month)
91**Rate Limit**: 6000 requests/minute
92**API Version**: V4 (with V2 backward compatibility)
93**Total Tools**: 37 across 8 categories
94 
95 
96## Function Reference (full signatures + return shapes)
97 
98All functions live in `exports.py`. Most return `Optional[List[Dict]]` or
99`Optional[Dict]`. None means the upstream call failed or returned empty —
100always check before indexing.
101 
102### ⚠️ Field naming convention (READ THIS FIRST)
103 
104CoinGlass v4 API uses **camelCase** for almost all data fields, with a few
105legacy snake_case exceptions in liquidation endpoints. Don't assume
106snake_case — `inspect` the dict before scripting.
107 
108- camelCase: `openInterest`, `volUsd`, `longRate`, `shortVolUsd`,
109  `exchangeName`, `nextFundingTime`, `fundingIntervalHours`,
110  `oichangePercent`, `h4OIChangePercent`, `avgFundingRateBySymbol`,
111  `tokenAmount`, `liquidationUsd` (in some endpoints)
112- snake_case (legacy, only in `cg_liquidations`): `liquidation_usd`,
113  `longLiquidation_usd`, `shortLiquidation_usd`
114- `rate` fields (funding) are STRINGS with "+" / "-" / "%" — parse with
115  `float(r.rstrip('%').lstrip('+'))` to compare numerically
116- timestamps are millisecond unix epoch (e.g. `1777881600000`)
117 
118### Funding & Open Interest
119 
120| Function | Signature |
121|---|---|
122| `funding_rate(symbol, exchange=None)` | dict — keys: `symbol`, `exchange`, `rate` (str), `num_exchanges`, `exchanges_data` (list of {`exchangeName`, `rate`, `nextFundingTime`, `fundingIntervalHours`, `status`}) |
123| `cg_open_interest(symbol='BTC', interval='0')` | LIST of dicts (one per exchange) — keys: `symbol`, `openInterest`, `volUsd`, `oichangePercent`, `h4OIChangePercent`, `h24VolChangePercent`, `volChangePercent7d`, `avgFundingRateBySymbol`, `exchangeName`, `exchangeLogo` |
124 
125### Long/Short Ratios
126 
127| Function | Signature |
128|---|---|
129| `long_short_ratio(symbol='BTC', interval='h4')` | LIST — top item is aggregated; `list` field inside has per-exchange breakdown. Keys: `longRate`, `shortRate`, `longVolUsd`, `shortVolUsd`, `totalVolUsd`, `list` |
130| `cg_global_account_ratio(symbol='BTC', exchange='Binance', interval='1h')` | list of historical bars |
131| `cg_top_account_ratio(symbol='BTC', exchange='Binance', interval='1h')` | list — top trader account-count ratio |
132| `cg_top_position_ratio(symbol='BTC', exchange='Binance', interval='1h')` | list — top trader position-size ratio |
133| `cg_taker_exchanges(symbol='BTC', range_type='4h')` | list — taker buy/sell across exchanges |
134| `cg_net_position(symbol='BTC', exchange='Binance', interval='1h')` | list — net long-short USD over time |
135 
136### Liquidations
137 
138| Function | Signature |
139|---|---|
140| `cg_liquidations(symbol='BTC', time_type='h24')` | LIST of dicts (one per exchange + an `'All'` row first). Keys: `exchange`, `liquidation_usd`, `longLiquidation_usd`, `shortLiquidation_usd` (NOTE: snake_case legacy fields) |
141| `cg_liquidation_analysis(symbol='BTC', time_type='h24')` | dict — aggregated network-wide stats |
142| `cg_coin_liquidation_history(symbol='BTC', interval='h4')` | list — historical liq bars |
143| `cg_pair_liquidation_history(symbol='BTC', exchange='Binance', interval='h4')` | list — historical liq for one pair on one exchange |
144| `cg_liquidation_coin_list(symbol=None)` | list of all coins with liq summary |
145| `cg_liquidation_orders(symbol='BTC', exchange=None)` | list — recent individual liq orders |
146 
147### Futures Market Data
148 
149| Function | Signature |
150|---|---|
151| `cg_supported_coins()` | List[str] — symbols supported by CoinGlass |
152| `cg_supported_exchanges()` | list of exchange info dicts |
153| `cg_coins_market_data(symbol=None)` | list — current snapshot for all coins (or one if symbol given) |
154| `cg_pair_market_data(symbol='BTC', exchange=None)` | list — pair-level snapshot |
155| `cg_ohlc_history(symbol='BTC', interval='h4', exchange=None)` | list of OHLCV bars |
156 
157### Hyperliquid Whale Tracking
158 
159| Function | Signature |
160|---|---|
161| `cg_hyperliquid_whale_alerts()` | list — recent large-position alerts |
162| `cg_hyperliquid_whale_positions()` | list — current open whale positions |
163| `cg_hyperliquid_positions_by_coin(symbol='BTC')` | list — whales holding a specific coin |
164| `cg_hyperliquid_position_distribution(symbol='BTC')` | dict — long/short position-size distribution |
165 
166### Volume / Flow
167 
168| Function | Signature |
169|---|---|
170| `cg_taker_volume_history(symbol='BTC', exchange='Binance', interval='1h', limit=1000, start_time=None, end_time=None)` | list — taker buy/sell volume bars |
171| `cg_aggregated_taker_volume(symbol='BTC', interval='h4')` | list — aggregated across all exchanges |
172| `cg_cumulative_volume_delta(symbol='BTC', exchange='Binance', interval='1h', limit=1000, start_time=None, end_time=None)` | list — CVD bars |
173| `cg_coin_netflow(symbol=None)` | list — net inflow/outflow per coin |
174| `cg_whale_transfers()` | dict — recent on-chain large transfers |
175 
176### ETF Flows
177 
178| Function | Signature |
179|---|---|
180| `cg_btc_etf_flows()` | list — daily flows per US BTC ETF |
181| `cg_btc_etf_history(etf_ticker=None)` | list — historical AUM/flows |
182| `cg_btc_etf_list()` | list of BTC ETF tickers + AUM |
183| `cg_btc_etf_premium_discount()` | list — premium/discount % vs NAV |
184| `cg_hk_btc_etf_flows()` | list — Hong Kong BTC ETF flows |
185| `cg_eth_etf_flows()` / `cg_eth_etf_list()` / `cg_eth_etf_premium_discount()` / `cg_hk_eth_etf_flows()` | ETH ETF equivalents |
186| `cg_sol_etf_flows()` / `cg_sol_etf_list()` | SOL ETF data |
187| `cg_xrp_etf_flows()` / `cg_xrp_etf_list()` | XRP ETF data |
188 
189### Sample responses (most-used functions)
190 
191`funding_rate(symbol="BTC")`:
192```json
193{
194  "symbol": "BTC",
195  "exchange": "average",
196  "rate": "-0.0016%",
197  "num_exchanges": 21,
198  "exchanges_data": [
199    {"exchangeName": "Binance", "rate": "+0.0050%",
200     "nextFundingTime": 1777881600000, "fundingIntervalHours": 8, "status": 1}
201  ]
202}
203```
204 
205`cg_liquidations(symbol="BTC", time_type="h24")`:
206```json
207[
208  {"exchange": "All", "liquidation_usd": 170497688.16,
209   "longLiquidation_usd": 8179073.80, "shortLiquidation_usd": 162318614.36},
210  {"exchange": "Bybit", "liquidation_usd": 40454694.98, ...}
211]
212```
213 
214`cg_open_interest(symbol="BTC")`:
215```json
216[
217  {"symbol": "BTC", "openInterest": 61395303653.62, "volUsd": 56349328748.42,
218   "oichangePercent": 7.17, "h4OIChangePercent": 5.33,
219   "avgFundingRateBySymbol": -0.001874, "exchangeName": "Binance"}
220]
221```
222 
223`long_short_ratio(symbol="BTC", interval="h4")`:
224```json
225[{
226  "symbol": "BTC", "longRate": 53.65, "shortRate": 46.35,
227  "longVolUsd": 12558668895.91, "shortVolUsd": 10848776476.99,
228  "totalVolUsd": 23407445372.91,
229  "list": [
230    {"exchangeName": "Binance", "longRate": 55.75, "shortRate": 44.25, ...}
231  ]
232}]
233```
234 
235 
236## Tool Selection Guide
237 
238### Decision Tree
239 
240**Step 1: Is this about LIQUIDATIONS?**
241 
242```
243Liquidation query?
244├─ YES → How many coins?
245│   ├─ ALL coins / ranking / 排行 / 汇总
246│   │   └─ → cg_liquidation_coin_list  ✅ (most liquidation queries land here)
247│   ├─ ONE coin, need history over time
248│   │   └─ → cg_coin_liquidation_history
249│   ├─ ONE coin, specific orders (price/side/USD)
250│   │   └─ → cg_liquidation_orders
251│   └─ ONE coin, just a quick total + sentiment label
252│       └─ → cg_liquidation_analysis  (rarely needed; only if explicitly "simple summary")
253```
254 
255**Step 2: Is this about LONG/SHORT RATIO?**
256 
257```
258Long/short query?
259├─ Historical time-series, trend over time, 多空比变化
260│   └─ → cg_global_account_ratio  (ALL accounts)
261│      or cg_top_account_ratio    (top traders only)
262│      or cg_top_position_ratio   (by position size)
263└─ Current snapshot only (no history needed)
264    └─ → long_short_ratio
265```
266 
267**Step 3: Is this about OPEN INTEREST?**
268 
269```
270OI query?
271└─ → cg_open_interest  (always — do NOT use cg_coins_market_data for OI)
272```
273 
274**Step 4: Is this a MARKET OVERVIEW / SENTIMENT query?**
275 
276```
277Sentiment / 市场情绪 / pre-trade check?
278└─ Use: funding_rate + long_short_ratio + cg_open_interest
279   DO NOT use cg_coins_market_data as a substitute for any of the above
280```
281 
282---
283 
284### Keyword → Tool Lookup
285 
286| Keyword / Pattern | Correct Tool | ❌ Do NOT use |
287|---|---|---|
288| 爆仓排行 / 今日爆仓 / all coins liquidation | `cg_liquidation_coin_list` | `cg_liquidations` |
289| 24h爆仓汇总 / liquidation summary | `cg_liquidation_coin_list` | `cg_liquidation_analysis` |
290| 全网账户多空比 / account L/S ratio | `cg_global_account_ratio` | `long_short_ratio` |
291| 头部交易者多空 / top trader ratio | `cg_top_account_ratio` | `long_short_ratio` |
292| 未平仓合约 / open interest | `cg_open_interest` | `cg_coins_market_data` |
293| 市场情绪多空分析 | `funding_rate` + `long_short_ratio` + `cg_open_interest` | `cg_coins_market_data` |
294| BTC做多检查 / pre-trade checklist | `funding_rate` + `cg_global_account_ratio` + `cg_liquidation_coin_list` | — |
295 
296---
297 
298### Common Mistakes
299 
300**Mistake 1 (most common — 8x failure): Using `cg_liquidations` when you need `cg_liquidation_coin_list`**
301- `cg_liquidations` → one coin, one timeframe, basic total only
302- `cg_liquidation_coin_list(exchange)` → ALL coins, multi-timeframe (1h/4h/12h/24h), per-exchange breakdown
303- **Rule:** If the question asks for a ranking, overview, or doesn't specify a single coin → use `cg_liquidation_coin_list`
304 
305**Mistake 2 (5x failure): Using `cg_liquidation_analysis` for liquidation rankings**
306- `cg_liquidation_analysis` adds a sentiment label to a single-coin total — it is NOT a ranking tool
307- **Rule:** "今日爆仓排行" / "各币种爆仓" → always `cg_liquidation_coin_list`
308 
309**Mistake 3 (3x failure): Using `long_short_ratio` for historical L/S analysis**
310- `long_short_ratio` is a current snapshot (no time-series)
311- `cg_global_account_ratio` returns history — use it when the user wants trends or comparison over time
312- **Rule:** If the question compares 全网 (global) vs 头部 (top traders) → call BOTH `cg_global_account_ratio` AND `cg_top_account_ratio`
313 
314**Mistake 4 (2x failure): Using `cg_coins_market_data` for open interest**
315- `cg_coins_market_data` is a bulk snapshot of many coins — not a replacement for dedicated OI or L/S tools
316- **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`.
317 
318## Rules
319 
320### Tool Call Guidance
321 
322**❌ FORBIDDEN TOOLS — NEVER USE:**
323- `bash` — Do NOT write scripts to process/format data. Use natural language.
324- `write_file` / `read_file` / `edit_file` — Do NOT save intermediate data. Answer directly.
325- `learning_log` — ONLY for genuine skill bugs or persistent API errors. NOT for empty responses.
326- `echo` — Do NOT use for debugging or output.
327 
328**✅ CORRECT PATTERN:**
329- Tool returns data → Summarize in natural language → Done
330- Tool returns empty/null → Report "no data available" → Done
331- Need calculation (%, change, ratio) → Do mental math in reply
332 
333**Match tool count to question scope:**
334  - 单一指标问题（"BTC 资金费率"、"ETH 多空比"）→ 1 个工具，直接返回
335  - 多维度分析（"做多是否合适"、"衍生品体检"）→ 3-5 个工具，综合分析
336  - 对比问题（"ETH vs SOL"）→ 每个币种调相同工具，并列对比
337- **避免重复调用同一工具。** 除非用户明确要求不同币种/交易所的对比。
338 
339### Learning Log Usage (CRITICAL)
340 
341**`learning_log` is FORBIDDEN for:**
342- ❌ Empty API responses — just report "no data available"
343- ❌ Tool returning None/null — handle gracefully
344- ❌ Uncertainty about tool selection — check decision tree first
345- ❌ Normal tool errors — retry once, then report failure
346 
347**`learning_log` is ONLY for:**
348- ✅ Genuine bugs in skill code (wrong data format returned)
349- ✅ Persistent API rate limit errors after 2+ retries
350- ✅ Missing tools that should exist per skill definition
351 
352### ETF Tool Selection
353| Query | Primary Tool | Secondary Tool |
354|-------|--------------|----------------|
355| BTC ETF 资金流入/流出 | `cg_btc_etf_flows()` | `cg_btc_etf_history()` for detailed history |
356| ETH ETF 资金流入/流出 | `cg_eth_etf_flows()` | — |
357| SOL/XRP ETF flows | `cg_sol_etf_flows()` / `cg_xrp_etf_flows()` | — |
358| HK ETF flows | `cg_hk_btc_etf_flows()` / `cg_hk_eth_etf_flows()` | — |
359| ETF 列表/代码 | `cg_btc_etf_list()` / `cg_eth_etf_list()` | — |
360| ETF 溢价/折价 | `cg_btc_etf_premium_discount()` | — |
361 
362**ETF 对比问题 workflow:**
363```
364# BTC vs ETH ETF 对比
365btc = cg_btc_etf_flows()
366eth = cg_eth_etf_flows()
367# Compare the latest day's net flows, summarize in 2-3 sentences
368```
369 
370## Quick Routing (use this first)
371 
372| Query type | Tool |
373|---|---|
374| 爆仓/liquidation summary (24h, by coin) | `cg_liquidation_coin_list` |
375| Individual liquidation orders | `cg_liquidation_orders` |
376| Liquidation history for a coin | `cg_coin_liquidation_history` |
377| Funding rate | `funding_rate` |
378| Long/short ratio (global) | `cg_global_account_ratio` |
379| Open interest | `cg_open_interest` |
380| Whale activity on Hyperliquid | `cg_hyperliquid_whale_alerts` |
381| ETF flows (BTC) | `cg_btc_etf_flows` |
382 
383## When to Use Coinglass
384 
385Use Coinglass for:
386- **Derivatives positioning** - What are leveraged traders doing?
387- **Whale tracking** - Track large positions on Hyperliquid DEX
388- **Funding rates** - Cost of holding perpetual futures
389- **Open interest** - Total notional value of open positions
390- **Long/Short ratios** - Sentiment among leveraged traders (global, top accounts, top positions)
391- **Liquidations** - Forced position closures with heatmaps and individual orders
392- **Volume analysis** - Taker volume, CVD, netflow patterns
393- **ETF flows** - Institutional adoption (Bitcoin, Ethereum, Solana, XRP, Hong Kong)
394- **Whale transfers** - Large on-chain movements (>$10M)
395- **Futures market data** - Supported coins, exchanges, pairs, and OHLC price history
396 
397## Tool Categories
398 
399### 1. Basic Derivatives Analytics (7 tools)
400 
401Core derivatives data for market analysis:
402 
403- `funding_rate(symbol, exchange?)` - Current funding rates
404- `long_short_ratio(symbol, exchange?, interval?)` - Basic L/S ratios
405- `cg_open_interest(symbol)` - Current OI across exchanges
406- `cg_liquidations(symbol, time?)` - Recent liquidations
407- `cg_liquidation_analysis(symbol)` - Liquidation heatmap analysis
408- `cg_supported_coins()` - All supported coins
409- `cg_supported_exchanges()` - All exchanges with pairs
410 
411### 2. Advanced Long/Short Ratios (6 tools)
412 
413Deep positioning analysis with multiple metrics:
414 
415- `cg_global_account_ratio(symbol, interval?)` - Global account-based L/S ratio
416- `cg_top_account_ratio(symbol, exchange, interval?)` - Top trader accounts ratio
417- `cg_top_position_ratio(symbol, exchange, interval?)` - Top positions by size
418- `cg_taker_exchanges(symbol)` - Taker buy/sell by exchange
419- `cg_net_position(symbol, exchange)` - Net long/short positions
420- `cg_net_position_v2(symbol)` - Enhanced net position data
421 
422**Use cases**:
423- Smart money tracking (top accounts vs retail)
424- Exchange-specific sentiment
425- Position size distribution analysis
426 
427### 3. Advanced Liquidations (4 tools)
428 
429Granular liquidation tracking for cascade prediction:
430 
431- `cg_coin_liquidation_history(symbol, interval?, limit?, start_time?, end_time?)` - Aggregated across all exchanges
432- `cg_pair_liquidation_history(symbol, exchange, interval?, limit?, start_time?, end_time?)` - Exchange-specific pair
433- `cg_liquidation_coin_list(exchange)` - All coins on an exchange
434- `cg_liquidation_orders(symbol, exchange, min_liquidation_amount, start_time?, end_time?)` - Individual orders (past 7 days, max 200)
435 
436**Use cases**:
437- Identifying liquidation clusters
438- Tracking liquidation patterns over time
439- Finding large liquidation events
440 
441### 4. Hyperliquid Whale Tracking (4 tools)
442 
443Track large traders on Hyperliquid DEX (~200 recent alerts):
444 
445- `cg_hyperliquid_whale_alerts()` - Recent large position opens/closes (>$1M)
446- `cg_hyperliquid_whale_positions()` - Current whale positions with PnL
447- `cg_hyperliquid_positions_by_coin()` - All positions grouped by coin
448- `cg_hyperliquid_position_distribution()` - Distribution by size with sentiment
449 
450**Use cases**:
451- Following smart money on Hyperliquid
452- Detecting large position changes
453- Tracking whale PnL and sentiment
454 
455### 5. Futures Market Data (5 tools)
456 
457Market overview and price data:
458 
459- `cg_coins_market_data()` - ALL coins data in one call (100+ coins)
460- `cg_pair_market_data(symbol, exchange)` - Specific pair metrics
461- `cg_ohlc_history(symbol, exchange, interval, limit?)` - OHLC candlesticks
462- `cg_taker_volume_history(symbol, exchange, interval, limit?, start_time?, end_time?)` - Pair-specific taker volume
463- `cg_aggregated_taker_volume(symbol, interval, limit?, start_time?, end_time?)` - Aggregated across exchanges
464 
465**Use cases**:
466- Market screening (scan all coins at once)
467- Price action analysis
468- Volume pattern recognition
469 
470### 6. Volume & Flow Analysis (4 tools)
471 
472Order flow and capital movement tracking:
473 
474- `cg_cumulative_volume_delta(symbol, exchange, interval, limit?, start_time?, end_time?)` - CVD = Running total of (buy - sell)
475- `cg_coin_netflow()` - Capital flowing into/out of coins
476- `cg_whale_transfers()` - Large on-chain transfers (>$10M, past 6 months)
477 
478**Use cases**:
479- Order flow divergence detection
480- Smart money tracking
481- Institutional movement monitoring
482 
483### 7. Bitcoin ETF Data (5 tools)
484 
485Track institutional Bitcoin adoption:
486 
487- `cg_btc_etf_flows()` - Daily net inflows/outflows
488- `cg_btc_etf_premium_discount()` - ETF price vs NAV
489- `cg_btc_etf_history()` - Comprehensive history (price, NAV, premium%, shares, assets)
490- `cg_btc_etf_list()` - List of Bitcoin ETFs
491- `cg_hk_btc_etf_flows()` - Hong Kong Bitcoin ETF flows
492 
493**Use cases**:
494- Institutional demand tracking
495- Premium/discount arbitrage
496- Regional flow comparison (US vs Hong Kong)
497 
498### 8. Other ETF Data (8 tools)
499 
500Ethereum, Solana, XRP, and Hong Kong ETFs:
501 
502- `cg_eth_etf_flows()` - Ethereum ETF flows
503- `cg_eth_etf_list()` - Ethereum ETF list
504- `cg_eth_etf_premium_discount()` - ETH ETF premium/discount
505- `cg_sol_etf_flows()` - Solana ETF flows
506- `cg_sol_etf_list()` - Solana ETF list
507- `cg_xrp_etf_flows()` - XRP ETF flows
508- `cg_xrp_etf_list()` - XRP ETF list
509- `cg_hk_eth_etf_flows()` - Hong Kong Ethereum ETF flows
510 
511**Use cases**:
512- Multi-asset institutional tracking
513- Comparative flow analysis
514- Regional preference analysis
515 
516## Common Workflows
517 
518### Quick Market Scan
519```
520# Get everything in 3 calls
521all_coins = cg_coins_market_data()  # 100+ coins with full metrics
522btc_liquidations = cg_liquidations("BTC")
523whale_alerts = cg_hyperliquid_whale_alerts()
524```
525 
526### Deep Position Analysis
527```
528# BTC positioning across metrics
529cg_global_account_ratio("BTC")  # Retail sentiment
530cg_top_account_ratio("BTC", "Binance")  # Smart money
531cg_net_position_v2("BTC")  # Net positioning
532cg_liquidation_heatmap("BTC", "Binance")  # Cascade levels
533```
534 
535### ETF Flow Monitoring
536```
537# Institutional demand
538btc_flows = cg_btc_etf_flows()
539eth_flows = cg_eth_etf_flows()
540sol_flows = cg_sol_etf_flows()
541```
542 
543### Whale Tracking
544```
545# Follow the whales
546hyperliquid_whales = cg_hyperliquid_whale_alerts()
547whale_positions = cg_hyperliquid_whale_positions()
548onchain_whales = cg_whale_transfers()  # >$10M on-chain
549```
550 
551### Volume Analysis
552```
553# Order flow
554cvd = cg_cumulative_volume_delta("BTC", "Binance", "1h", 100)
555netflow = cg_coin_netflow()  # All coins
556taker_vol = cg_aggregated_taker_volume("BTC", "1h", 100)
557```
558 
559## Interpretation Guides
560 
561### Funding Rates
562 
563| Rate (8h) | Read |
564|------------|------|
565| > +0.05% | Extreme greed — crowded long, squeeze risk |
566| +0.01% to +0.05% | Bullish bias, normal |
567| -0.005% to +0.01% | Neutral |
568| -0.05% to -0.005% | Bearish bias, normal |
569| < -0.05% | Extreme fear — crowded short, bounce risk |
570 
571Extreme funding often precedes reversals. The crowd is usually wrong at extremes.
572 
573### Open Interest + Price Matrix
574 
575| OI | Price | Read |
576|----|-------|------|
577| Up | Up | New longs entering — bullish conviction |
578| Up | Down | New shorts entering — bearish conviction |
579| Down | Up | Short covering — weaker rally, less conviction |
580| Down | Down | Long liquidation — weaker selloff, capitulation |
581 
582### Long/Short Ratio
583 
584| Ratio | Read |
585|-------|------|
586| > 1.5 | Crowded long — contrarian bearish |
587| 1.1–1.5 | Moderately bullish |
588| 0.9–1.1 | Balanced |
589| 0.7–0.9 | Moderately bearish |
590| < 0.7 | Crowded short — contrarian bullish |
591 
592### CVD (Cumulative Volume Delta)
593 
594| Pattern | Read |
595|---------|------|
596| CVD rising, price rising | Strong buy pressure, healthy uptrend |
597| CVD falling, price rising | Weak rally, distribution |
598| CVD rising, price falling | Accumulation, potential bottom |
599| CVD falling, price falling | Strong sell pressure, healthy downtrend |
600 
601### ETF Flows
602 
603| Flow | Read |
604|------|------|
605| Large inflows | Institutional buying, bullish |
606| Consistent inflows | Sustained demand |
607| Large outflows | Institutional selling, bearish |
608| Premium to NAV | High demand, bullish sentiment |
609| Discount to NAV | Weak demand, bearish sentiment |
610 
611## Analysis Patterns
612 
613**Multi-metric confirmation**: Combine tools across categories for high-confidence signals:
614- Funding + L/S ratio + liquidations = positioning extremes
615- CVD + taker volume + whale alerts = smart money direction
616- ETF flows + whale transfers + open interest = institutional conviction
617 
618**Smart money vs retail**: Compare metrics to identify divergence:
619- `cg_top_account_ratio` (smart money) vs `cg_global_account_ratio` (retail)
620- Hyperliquid whale positions vs overall long/short ratios
621 
622**Cascade prediction**: Use liquidation tools to predict volatility:
623- `cg_coin_liquidation_history` shows liquidation patterns over time
624- `cg_liquidation_orders` reveals recent forced closures
625- Large liquidation events = cascade risk zones
626 
627**Flow divergence**: Track capital movements:
628- `cg_coin_netflow` shows where money is flowing
629- `cg_whale_transfers` reveals large movements
630- ETF flows show institutional demand
631 
632## Performance Optimization
633 
634### Batch vs Individual Calls
635 
636**✅ OPTIMAL**: Use batch endpoints
637```
638# One call gets 100+ coins
639all_coins = cg_coins_market_data()
640 
641# One call gets all whale alerts
642whales = cg_hyperliquid_whale_alerts()
643 
644# One call gets all ETF flows
645btc_etf = cg_btc_etf_flows()
646```
647 
648**❌ INEFFICIENT**: Multiple individual calls
649```
650# Don't do this - wastes API quota
651btc = cg_pair_market_data("BTC", "Binance")
652eth = cg_pair_market_data("ETH", "Binance")
653sol = cg_pair_market_data("SOL", "Binance")
654```
655 
656### Query Parameters
657 
658Most history endpoints support:
659- `interval`: Time granularity (1h, 4h, 12h, 24h, etc.)
660- `limit`: Number of records (default varies, max 1000)
661- `start_time`: Unix timestamp (milliseconds)
662- `end_time`: Unix timestamp (milliseconds)
663 
664Example:
665```
666cg_coin_liquidation_history(
667    symbol="BTC",
668    interval="1h",
669    limit=100,
670    start_time=1704067200000,  # 2024-01-01
671    end_time=1704153600000     # 2024-01-02
672)
673```
674 
675## Supported Exchanges
676 
677Major exchanges with futures data:
678- **Tier 1**: Binance, OKX, Bybit, Gate, KuCoin, MEXC
679- **Traditional**: CME (Bitcoin and Ethereum futures), Coinbase
680- **DEX**: Hyperliquid, dYdX, ApeX
681- **Others**: Bitfinex, Kraken, HTX, BingX, Crypto.com, CoinEx, Bitget
682 
683Use `cg_supported_exchanges()` for complete list with pair details.
684 
685## Important Notes
686 
687- **API Key**: Requires COINGLASS_API_KEY environment variable
688- **Symbols**: Use standard symbols (BTC, ETH, SOL, etc.) - check with `cg_supported_coins()`
689- **Exchanges**: Check `cg_supported_exchanges()` for full list with pairs
690- **Update Frequency**:
691  - Market data: ≤ 1 minute
692  - Funding rates: Every 8 hours (or 1 hour for some exchanges)
693  - OHLC: Real-time to 1 minute depending on interval
694  - ETF data: Daily (after market close)
695  - Whale transfers: Real-time (within minutes)
696- **API Versions**:
697  - V4 endpoints use `CG-API-KEY` header (most tools)
698  - V2 endpoints use `coinglassSecret` header (some legacy tools)
699  - Both work with the same COINGLASS_API_KEY environment variable
700- **Rate Limits**: Professional plan allows 6000 requests/minute
701- **Historical Data Limits**:
702  - Liquidation orders: Past 7 days, max 200 records
703  - Whale transfers: Past 6 months, minimum $10M
704  - Hyperliquid alerts: ~200 most recent large positions
705  - Other endpoints: Typically months to years of history
706 
707## Data Quality Notes
708 
709- **Hyperliquid**: Data is exchange-specific, doesn't include other DEXs
710- **Whale Transfers**: Covers Bitcoin, Ethereum, Tron, Ripple, Dogecoin, Litecoin, Polygon, Algorand, Bitcoin Cash, Solana
711- **ETF Data**: US ETFs updated after market close (4 PM ET), Hong Kong ETFs updated after Hong Kong market close
712- **Liquidation Orders**: Limited to 200 most recent, use heatmap for broader view
713- **CVD**: Cumulative metric - resets are not automatic, track changes not absolute values
714 
715## Version History
716 
717- **v3.0.0** (2025-03): Added 36 new tools
718  - Advanced liquidations (5 tools)
719  - Hyperliquid whale tracking (5 tools)
720  - Volume & flow analysis (5 tools)
721  - Whale transfers (1 tool)
722  - Bitcoin ETF (6 tools)
723  - Other ETFs (8 tools)
724  - Advanced L/S ratios (6 tools)
725- **v2.2.0** (2024): V4 API migration with futures market data
726- **v1.0.0** (2024): Initial release with basic derivatives data
727