coingecko

name: coingecko version: 2.1.0 description: | Crypto spot prices, OHLC charts, market discovery, and global stats.

Use when looking up coin prices, market caps, trending coins, sector rankings, or comparing tokens (e.g. BTC price, ETH chart, top gainers). delivery: script metadata: starchild: emoji: 🦎 skillKey: coingecko requires: env: - COINGECKO_API_KEY user-invocable: false disable-model-invocation: false

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: coin_price, coin_ohlc, coin_chart, cg_trending, cg_top_gainers_losers, cg_new_coins, cg_global, cg_global_defi, cg_categories, cg_derivatives, cg_coins_markets, cg_coin_data, cg_coin_tickers, cg_search, cg_token_price, cg_coin_by_contract.

CoinGecko Skill

Function Reference (signatures)

All public functions are in exports.py. coin_id is the CoinGecko id (e.g. bitcoin, ethereum) — use cg_search(query) first if unsure. vs_currency defaults to usd.

Prices & Charts

Discovery

Market Data

Categories / Derivatives / NFTs

Exchanges

Contracts / Tokens (by platform)

🚫 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

Also FORBIDDEN:

• ❌ web_search / web_fetch — 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

DO NOT return any numeric market data (prices, OHLC values, percentages) without calling a tool first.

⚡ Question → Tool Map (match first keyword, call immediately)

Derivatives: fields & full-market OI

cg_derivatives() returns {"tickers": [...], "count": N, "filter": "unexpired"}. Each ticker:

Full-market open interest (use this when CoinGlass coins-markets is unavailable on the platform plan):

from collections import defaultdict
t = cg_derivatives()["tickers"]
perp = [x for x in t if x["contract_type"] == "perpetual" and x.get("open_interest")]
by_coin = defaultdict(float)
for x in perp:
    by_coin[x["index_id"]] += x["open_interest"]
total = sum(by_coin.values())          # ~$217B as of 2026-09

Caveats:

• Current snapshot only, no history. For OI history use the coinglass skill (per-coin history, summed).
• Exchange-reported and includes small exchanges, so it runs well above CoinGlass (~$217B vs ~$117B on the same day). Always cite "CoinGecko" as the source, and never plot it on the same chart as CoinGlass or other third-party figures.
• Funding differs by exchange and margin type (USDT vs USDC vs coin-margined); if you report one per-coin number, use an OI-weighted average and say so.

🌳 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').