1---
2name: coingecko
3version: 2.0.3
4description: CoinGecko crypto price data, charts, market discovery, and global stats
5delivery: script
6metadata:
7  starchild:
8    emoji: 🦎
9    skillKey: coingecko
10    requires:
11      env:
12      - COINGECKO_API_KEY
13user-invocable: false
14disable-model-invocation: false
15---
16 
17## Script Usage
18 
19Script-mode skill — read this file, then invoke from a `bash` block:
20 
21```bash
22python3 - <<'EOF'
23import sys, json
24sys.path.insert(0, "/data/workspace/skills/coingecko")
25from exports import coin_price, cg_trending, cg_global
26 
27print(coin_price(coin_ids="bitcoin,ethereum"))
28print(cg_trending())
29EOF
30```
31 
32Read `exports.py` for the full list of available functions. Common ones:
33`coin_price`, `coin_ohlc`, `coin_chart`, `cg_trending`,
34`cg_top_gainers_losers`, `cg_new_coins`, `cg_global`, `cg_global_defi`,
35`cg_categories`, `cg_derivatives`, `cg_coins_markets`, `cg_coin_data`,
36`cg_coin_tickers`, `cg_search`, `cg_token_price`, `cg_coin_by_contract`.
37 
38 
39# CoinGecko Skill
40 
41 
42## Function Reference (signatures)
43 
44All public functions are in `exports.py`. `coin_id` is the CoinGecko id
45(e.g. `bitcoin`, `ethereum`) — use `cg_search(query)` first if unsure.
46`vs_currency` defaults to `usd`.
47 
48### Prices & Charts
49| Function | Description |
50|---|---|
51| `coin_price(coin_ids, timestamps=None, vs_currency='usd')` | Current or historical price. `coin_ids` = comma-string like `"bitcoin,ethereum"`. `timestamps` = list of unix ts for historical (default: now). |
52| `coin_ohlc(coin_id, days=30, vs_currency='usd')` | OHLC bars for last N days. Returns list of `[ts, o, h, l, c]`. Granularity auto-selected: 1d=30min, 7-30d=4h, 30d+=4h. |
53| `coin_chart(coin_id, days=30, vs_currency='usd')` | Price + market_cap + total_volume timeseries. Returns `{prices, market_caps, total_volumes}` (each list of `[ts, val]`). |
54 
55### Discovery
56| Function | Description |
57|---|---|
58| `cg_trending()` | Trending coins, NFTs, categories (last 24h). |
59| `cg_top_gainers_losers(vs_currency='usd', duration='24h')` | Top gainers/losers. `duration` = `1h`/`24h`/`7d`/`14d`/`30d`/`60d`/`1y`. |
60| `cg_new_coins()` | Recently listed coins. |
61| `cg_search(query)` | Search coins/exchanges/categories by name. |
62 
63### Market Data
64| Function | Description |
65|---|---|
66| `cg_global()` | Global crypto market: total market_cap, volume, dominance. |
67| `cg_global_defi()` | Global DeFi: TVL, dominance, top protocols. |
68| `cg_coins_markets(vs_currency='usd', order='market_cap_desc', per_page=100, page=1, sparkline=False, price_change_percentage='24h', category=None, ids=None)` | Top coins with full market data. |
69| `cg_coin_data(coin_id, localization=False, tickers=False, market_data=True, community_data=False, developer_data=False, sparkline=False)` | Detailed data for one coin. |
70| `cg_coin_tickers(coin_id, exchange_ids=None, include_exchange_logo=False, page=1, order='volume_desc', depth=False)` | Where a coin trades + volumes. |
71| `cg_coins_list(include_platform=False)` | All coin ids/symbols (for resolving). |
72 
73### Categories / Derivatives / NFTs
74| Function | Description |
75|---|---|
76| `cg_categories(order='market_cap_desc')` | Top categories with market_cap and volume. |
77| `cg_categories_list()` | Just category ids/names. |
78| `cg_derivatives(include_tickers='unexpired')` | Derivatives tickers across exchanges. |
79| `cg_derivatives_exchanges(order='open_interest_btc_desc', per_page=50)` | Derivatives exchange rankings. |
80| `cg_nfts_list(order='market_cap_usd_desc', per_page=100, page=1)` | Top NFT collections. |
81| `cg_nft(nft_id)` | NFT collection detail. |
82| `cg_nft_by_contract(asset_platform, contract_address)` | NFT by contract address. |
83 
84### Exchanges
85| Function | Description |
86|---|---|
87| `cg_exchanges(per_page=100, page=1)` | Exchange rankings. |
88| `cg_exchange(exchange_id)` | One exchange's detail. |
89| `cg_exchange_tickers(exchange_id, ...)` | Tickers on an exchange. |
90| `cg_exchange_volume_chart(exchange_id, days=30)` | Exchange volume history. |
91 
92### Contracts / Tokens (by platform)
93| Function | Description |
94|---|---|
95| `cg_token_price(platform, contract_addresses, vs_currencies='usd', include_market_cap=False, include_24hr_vol=False, include_24hr_change=False, include_last_updated_at=False)` | Price by contract address on a platform. |
96| `cg_coin_by_contract(platform, contract_address)` | Coin metadata by contract. |
97| `cg_asset_platforms(filter=None)` | Supported chains. |
98| `cg_vs_currencies()` | Supported quote currencies. |
99| `cg_exchange_rates()` | BTC-denominated rates for fiat/major coins. |
100 
101## 🚫 CRITICAL: STOP — READ THIS BEFORE CALLING ANY TOOL
102 
103**The #1 error is calling Coinglass tools instead of CoinGecko tools.** They have similar names but are COMPLETELY DIFFERENT systems.
104 
105### WRONG → RIGHT Tool Substitution Table
106 
107| ❌ NEVER call this | ✅ Call this instead | How to tell them apart |
108|---|---|---|
109| `cg_coins_market_data` | **`cg_coins_markets`** | market_data=Coinglass derivatives. markets=CoinGecko spot. |
110| `cg_ohlc_history` | **`coin_ohlc`** | ohlc_history=Coinglass futures candles. coin_ohlc=CoinGecko spot candles. |
111| `cg_pair_market_data` | **`cg_coin_tickers`** | pair_market_data=Coinglass futures pair. coin_tickers=CoinGecko spot pairs. |
112| `cg_supported_exchanges` | **`cg_exchanges`** | supported_exchanges=Coinglass futures. exchanges=CoinGecko spot. |
113| `cg_taker_exchanges` | **`cg_exchange`** | taker=Coinglass volume. exchange=CoinGecko exchange info. |
114| `cg_aggregated_taker_volume` | **`cg_coin_tickers`** | taker_volume=Coinglass. coin_tickers=CoinGecko volume across exchanges. |
115| `defillama_chains` | **`cg_global_defi`** | For DeFi stats from CoinGecko, use cg_global_defi(). |
116 
117### Also FORBIDDEN:
118- ❌ `web_search` / `web_fetch` — ALL data is available via native CoinGecko tools above. NEVER use web_search for crypto market data.
119- ❌ `bash` for data processing — CoinGecko tools return clean data. No bash needed.
120- ❌ **NEVER answer with training data** — all prices, rankings, OHLC are stale. CALL THE TOOL.
121 
122## ⚠️ MANDATORY TOOL CALLS — You MUST call a tool before answering these
123 
124| Request type | You MUST call | Why |
125|---|---|---|
126| K线 / OHLC / candlestick / open high low close | `coin_ohlc(coin_id, days)` | Price data is real-time; training data is stale |
127| 走势图 / price chart / 价格趋势 | `coin_chart(coin_id, days)` | Same reason |
128| 当前价格 / price right now | `coin_price(coin_ids)` | Training data has no live prices |
129 
130**DO NOT return any numeric market data (prices, OHLC values, percentages) without calling a tool first.**
131 
132## ⚡ Question → Tool Map (match first keyword, call immediately)
133 
134| Question keyword | Tool to call | Example |
135|---|---|---|
136| 价格 / price / 多少钱 (single coin) | `coin_price(coin_id)` | `coin_price(coin_ids="bitcoin")` |
137| K线 / OHLC / candlestick / 蜡烛图 | `coin_ohlc(coin_id, days)` | `coin_ohlc(coin_id="ethereum", days=7)` |
138| 走势 / trend / price chart / 价格历史 | `coin_chart(coin_id, days)` | `coin_chart(coin_id="solana", days=30)` |
139| 热门 / trending / 趋势币 | `cg_trending()` | `cg_trending()` |
140| 涨幅最大 / 跌幅最大 / gainers / losers | `cg_top_gainers_losers()` | `cg_top_gainers_losers()` |
141| 新币 / 新上线 / new coins / recently added | `cg_new_coins()` | `cg_new_coins()` |
142| 总市值 / BTC市占率 / global / 晨报 / 市场概况 | `cg_global()` | `cg_global()` |
143| DeFi总市值 / DeFi TVL / DeFi dominance | `cg_global_defi()` | `cg_global_defi()` |
144| 板块 / sector / category / L1 / L2 / Meme / AI coins | `cg_categories()` | `cg_categories()` |
145| 板块内个币 / Meme前10 / AI币排名 / DeFi币排名 | `cg_coins_markets(category=X)` | `cg_coins_markets(category="meme-token", per_page=10)` |
146| 市值排名 / top 10 / ranking / 前10币 | `cg_coins_markets(per_page=N)` | `cg_coins_markets(per_page=10)` |
147| ATH / 历史最高 / 社区 / dev / 研究 / fundamentals | `cg_coin_data(coin_id)` | `cg_coin_data(coin_id="solana", community_data=True)` |
148| 对比两个币 / compare / XX vs YY | `cg_coin_data()` × 2 | call once per coin |
149| NFT排名 / NFT市场 / floor price / top NFTs | `cg_nfts_list()` | `cg_nfts_list()` |
150| 某个NFT (BAYC/Punks/Azuki) | `cg_nft(nft_id)` | `cg_nft(nft_id="bored-ape-yacht-club")` |
151| 交易所详情 / Binance详情 / exchange data | `cg_exchange(exchange_id)` | `cg_exchange(exchange_id="binance")` |
152| 交易所列表 / exchange ranking | `cg_exchanges()` | `cg_exchanges()` |
153| 交易对 / trading pairs / 流动性分布 | `cg_coin_tickers(coin_id)` | `cg_coin_tickers(coin_id="bitcoin")` |
154| 交易所交易量趋势 / volume chart | `cg_exchange_volume_chart(exchange_id)` | `cg_exchange_volume_chart(exchange_id="binance", days=30)` |
155| 合约地址价格 / token price on-chain | `cg_token_price(platform, contract)` | `cg_token_price(platform="ethereum", contract_addresses="0xa0b...")` |
156| 搜索币 / 找币 / coin lookup / search | `cg_search(query)` | `cg_search(query="pepe")` |
157| 永续合约交易所 / derivatives exchange / OI排名 | `cg_derivatives_exchanges()` | `cg_derivatives_exchanges()` |
158| 合约ticker / perpetual / funding / basis | `cg_derivatives()` | `cg_derivatives()` |
159| 交易所对比 + 永续交易所 | `cg_exchanges()` + `cg_derivatives_exchanges()` | both calls |
160 
161## 🌳 Decision Tree
162 
163```
164How many coins?
165├─ ONE coin
166│   ├─ Just price? → coin_price()
167│   ├─ ATH/community/dev/deep? → cg_coin_data()
168│   ├─ OHLC candles? → coin_ohlc()
169│   ├─ Price trend? → coin_chart()
170│   └─ Unknown ID? → cg_search() first
171├─ MULTIPLE coins / ranking
172│   ├─ Sector aggregate (板块总市值)? → cg_categories()
173│   ├─ Sector individual (Meme前10)? → cg_coins_markets(category=X)
174│   └─ General ranking? → cg_coins_markets(per_page=N)
175├─ NFTs → cg_nfts_list() or cg_nft(nft_id)
176├─ Exchange → cg_exchange(id) or cg_exchanges()
177├─ Global → cg_global() or cg_global_defi()
178└─ Token by contract → cg_token_price()
179```
180 
181## Common Category IDs
182 
183`meme-token`, `artificial-intelligence`, `layer-1`, `layer-2`, `decentralized-finance-defi`, `gaming`, `real-world-assets-rwa`
184 
185## Output Formatting
186 
187- Prices: always use `$` sign → `$66,697`
188- Percentages: always use `%` → `+4.2%`
189- NFT floor in ETH: show USD too → `5.17 ETH ($10,534)`
190 
191## Important Notes
192 
193- CoinGecko uses slug IDs: "bitcoin", "ethereum", "solana". Symbols (BTC, ETH, SOL) auto-resolve.
194- If unsure about a coin ID → `cg_search(query="coin name")` first.
195- Most questions need only 1-2 tool calls. Do NOT chain 3+ calls.
196 
197## Common Issues
198 
199### coin_price failed with invalid ID
200**Solution:** Use `cg_search(query="coin name")` to find the correct CoinGecko ID first, or use the symbol directly (e.g., 'COMP').
201 
202---
203