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/coingecko")
from exports import coin_price, cg_trending, cg_global
print(coin_price(coin_ids="bitcoin,ethereum"))
print(cg_trending())
EOF
Read exports.py for the full list of available functions. Common ones: coinprice, coinohlc, coinchart, cgtrending, cgtopgainerslosers, cgnewcoins, cgglobal, cgglobaldefi, cgcategories, cgderivatives, cgcoinsmarkets, cgcoindata, cgcointickers, cgsearch, cgtokenprice, cgcoinbycontract.
CoinGecko Skill
Function Reference (signatures)
All public functions are in exports.py. coinid is the CoinGecko id (e.g. bitcoin, ethereum) — use cgsearch(query) first if unsure. vs_currency defaults to usd.
Prices & Charts
| Function |
Description |
coinprice(coinids, 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). |
coinohlc(coinid, 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. |
coinchart(coinid, days=30, vs_currency='usd') |
Price + marketcap + totalvolume timeseries. Returns {prices, marketcaps, totalvolumes} (each list of [ts, val]). |
Discovery
| Function |
Description |
cg_trending() |
Trending coins, NFTs, categories (last 24h). |
cgtopgainerslosers(vscurrency='usd', duration='24h') |
Top gainers/losers. duration = 1h/24h/7d/14d/30d/60d/1y. |
cgnewcoins() |
Recently listed coins. |
cg_search(query) |
Search coins/exchanges/categories by name. |
Market Data
| Function |
Description |
cg_global() |
Global crypto market: total market_cap, volume, dominance. |
cgglobaldefi() |
Global DeFi: TVL, dominance, top protocols. |
cgcoinsmarkets(vscurrency='usd', order='marketcapdesc', perpage=100, page=1, sparkline=False, pricechangepercentage='24h', category=None, ids=None) |
Top coins with full market data. |
cgcoindata(coinid, localization=False, tickers=False, marketdata=True, communitydata=False, developerdata=False, sparkline=False) |
Detailed data for one coin. |
cgcointickers(coinid, exchangeids=None, includeexchangelogo=False, page=1, order='volume_desc', depth=False) |
Where a coin trades + volumes. |
cgcoinslist(include_platform=False) |
All coin ids/symbols (for resolving). |
Categories / Derivatives / NFTs
| Function |
Description |
cgcategories(order='marketcap_desc') |
Top categories with market_cap and volume. |
cgcategorieslist() |
Just category ids/names. |
cgderivatives(includetickers='unexpired') |
Derivatives tickers across exchanges. |
cgderivativesexchanges(order='openinterestbtcdesc', perpage=50) |
Derivatives exchange rankings. |
cgnftslist(order='marketcapusddesc', perpage=100, page=1) |
Top NFT collections. |
cgnft(nftid) |
NFT collection detail. |
cgnftbycontract(assetplatform, contract_address) |
NFT by contract address. |
Exchanges
| Function |
Description |
cgexchanges(perpage=100, page=1) |
Exchange rankings. |
cgexchange(exchangeid) |
One exchange's detail. |
cgexchangetickers(exchange_id, ...) |
Tickers on an exchange. |
cgexchangevolumechart(exchangeid, days=30) |
Exchange volume history. |
Contracts / Tokens (by platform)
| Function |
Description |
cgtokenprice(platform, contractaddresses, vscurrencies='usd', includemarketcap=False, include24hrvol=False, include24hrchange=False, includelastupdated_at=False) |
Price by contract address on a platform. |
cgcoinbycontract(platform, contractaddress) |
Coin metadata by contract. |
cgassetplatforms(filter=None) |
Supported chains. |
cgvscurrencies() |
Supported quote currencies. |
cgexchangerates() |
BTC-denominated rates for fiat/major coins. |
🚫 CRITICAL: STOP — READ THIS BEFORE CALLING ANY TOOL
The #1 error is calling Coinglass tools instead of CoinGecko tools. They have similar names but are COMPLETELY DIFFERENT systems.
WRONG → RIGHT Tool Substitution Table
| ❌ NEVER call this |
✅ Call this instead |
How to tell them apart |
cgcoinsmarket_data |
cgcoinsmarkets |
market_data=Coinglass derivatives. markets=CoinGecko spot. |
cgohlchistory |
coin_ohlc |
ohlchistory=Coinglass futures candles. coinohlc=CoinGecko spot candles. |
cgpairmarket_data |
cgcointickers |
pairmarketdata=Coinglass futures pair. coin_tickers=CoinGecko spot pairs. |
cgsupportedexchanges |
cg_exchanges |
supported_exchanges=Coinglass futures. exchanges=CoinGecko spot. |
cgtakerexchanges |
cg_exchange |
taker=Coinglass volume. exchange=CoinGecko exchange info. |
cgaggregatedtaker_volume |
cgcointickers |
takervolume=Coinglass. cointickers=CoinGecko volume across exchanges. |
defillama_chains |
cgglobaldefi |
For DeFi stats from CoinGecko, use cgglobaldefi(). |
Also FORBIDDEN:
- ❌
websearch / webfetch — ALL data is available via native CoinGecko tools above. NEVER use web_search for crypto market data.
- ❌
bash for data processing — CoinGecko tools return clean data. No bash needed.
- ❌ NEVER answer with training data — all prices, rankings, OHLC are stale. CALL THE TOOL.
⚠️ MANDATORY TOOL CALLS — You MUST call a tool before answering these
| Request type |
You MUST call |
Why |
| K线 / OHLC / candlestick / open high low close |
coinohlc(coinid, days) |
Price data is real-time; training data is stale |
| 走势图 / price chart / 价格趋势 |
coinchart(coinid, days) |
Same reason |
| 当前价格 / price right now |
coinprice(coinids) |
Training data has no live prices |
DO NOT return any numeric market data (prices, OHLC values, percentages) without calling a tool first.
⚡ Question → Tool Map (match first keyword, call immediately)
| Question keyword |
Tool to call |
Example |
| 价格 / price / 多少钱 (single coin) |
coinprice(coinid) |
coinprice(coinids="bitcoin") |
| K线 / OHLC / candlestick / 蜡烛图 |
coinohlc(coinid, days) |
coinohlc(coinid="ethereum", days=7) |
| 走势 / trend / price chart / 价格历史 |
coinchart(coinid, days) |
coinchart(coinid="solana", days=30) |
| 热门 / trending / 趋势币 |
cg_trending() |
cg_trending() |
| 涨幅最大 / 跌幅最大 / gainers / losers |
cgtopgainers_losers() |
cgtopgainers_losers() |
| 新币 / 新上线 / new coins / recently added |
cgnewcoins() |
cgnewcoins() |
| 总市值 / BTC市占率 / global / 晨报 / 市场概况 |
cg_global() |
cg_global() |
| DeFi总市值 / DeFi TVL / DeFi dominance |
cgglobaldefi() |
cgglobaldefi() |
| 板块 / sector / category / L1 / L2 / Meme / AI coins |
cg_categories() |
cg_categories() |
| 板块内个币 / Meme前10 / AI币排名 / DeFi币排名 |
cgcoinsmarkets(category=X) |
cgcoinsmarkets(category="meme-token", per_page=10) |
| 市值排名 / top 10 / ranking / 前10币 |
cgcoinsmarkets(per_page=N) |
cgcoinsmarkets(per_page=10) |
| ATH / 历史最高 / 社区 / dev / 研究 / fundamentals |
cgcoindata(coin_id) |
cgcoindata(coinid="solana", communitydata=True) |
| 对比两个币 / compare / XX vs YY |
cgcoindata() × 2 |
call once per coin |
| NFT排名 / NFT市场 / floor price / top NFTs |
cgnftslist() |
cgnftslist() |
| 某个NFT (BAYC/Punks/Azuki) |
cgnft(nftid) |
cgnft(nftid="bored-ape-yacht-club") |
| 交易所详情 / Binance详情 / exchange data |
cgexchange(exchangeid) |
cgexchange(exchangeid="binance") |
| 交易所列表 / exchange ranking |
cg_exchanges() |
cg_exchanges() |
| 交易对 / trading pairs / 流动性分布 |
cgcointickers(coin_id) |
cgcointickers(coin_id="bitcoin") |
| 交易所交易量趋势 / volume chart |
cgexchangevolumechart(exchangeid) |
cgexchangevolumechart(exchangeid="binance", days=30) |
| 合约地址价格 / token price on-chain |
cgtokenprice(platform, contract) |
cgtokenprice(platform="ethereum", contract_addresses="0xa0b...") |
| 搜索币 / 找币 / coin lookup / search |
cg_search(query) |
cg_search(query="pepe") |
| 永续合约交易所 / derivatives exchange / OI排名 |
cgderivativesexchanges() |
cgderivativesexchanges() |
| 合约ticker / perpetual / funding / basis |
cg_derivatives() |
cg_derivatives() |
| 交易所对比 + 永续交易所 |
cgexchanges() + cgderivatives_exchanges() |
both calls |
🌳 Decision Tree
How many coins?
├─ ONE coin
│ ├─ Just price? → coin_price()
│ ├─ ATH/community/dev/deep? → cg_coin_data()
│ ├─ OHLC candles? → coin_ohlc()
│ ├─ Price trend? → coin_chart()
│ └─ Unknown ID? → cg_search() first
├─ MULTIPLE coins / ranking
│ ├─ Sector aggregate (板块总市值)? → cg_categories()
│ ├─ Sector individual (Meme前10)? → cg_coins_markets(category=X)
│ └─ General ranking? → cg_coins_markets(per_page=N)
├─ NFTs → cg_nfts_list() or cg_nft(nft_id)
├─ Exchange → cg_exchange(id) or cg_exchanges()
├─ Global → cg_global() or cg_global_defi()
└─ Token by contract → cg_token_price()
Common Category IDs
meme-token, artificial-intelligence, layer-1, layer-2, decentralized-finance-defi, gaming, real-world-assets-rwa
Output Formatting
- Prices: always use
$ sign → $66,697
- Percentages: always use
% → +4.2%
- NFT floor in ETH: show USD too →
5.17 ETH ($10,534)
Important Notes
- CoinGecko uses slug IDs: "bitcoin", "ethereum", "solana". Symbols (BTC, ETH, SOL) auto-resolve.
- If unsure about a coin ID →
cg_search(query="coin name") first.
- Most questions need only 1-2 tool calls. Do NOT chain 3+ calls.
Common Issues
coin_price failed with invalid ID
Solution: Use cg_search(query="coin name") to find the correct CoinGecko ID first, or use the symbol directly (e.g., 'COMP').
