coingecko - SKILL.md Agent Skill

name: coingecko description: This skill should be used when the user asks to "check the price of ETH", "get market data for a token", "show me trending coins", "look up OHLC data", "find a coin ID by contract address", or mentions CoinGecko, token prices, market caps, or historical charts. compatibility: Requires the CoinGecko CLI (`cg`), installed via `brew install coingecko/coingecko-cli/cg` or `curl -sSfL https://raw.githubusercontent.com/coingecko/coingecko-cli/main/install.sh | sh`. Authenticate with `cg auth` or set CG_API_KEY environment variable. allowed-tools: Bash(cg:*) metadata: author: maxyz.xyz argument-hint: "[command] [flags]"

CoinGecko CLI

Query cryptocurrency market data — prices, charts, trending coins, historical data, and more — using the official CoinGecko CLI.

Always use -o json on every command. JSON output contains the full API response and is reliably parseable. The default table format drops fields.

Commands

Command	Description
`cg price`	Current price by coin IDs or ticker symbols
`cg markets`	Top coins ranked by market cap
`cg search`	Search coins by name or symbol
`cg trending`	Trending coins, NFTs, and categories (24h)
`cg history`	Historical price data (snapshot, range, OHLC)
`cg top-gainers-losers`	Top movers (paid plans only)
`cg watch`	Live WebSocket price streaming (paid only)

Run cg <command> --help for full flag details. Run cg commands for machine-readable JSON catalog.

Common Workflows

Price by coin ID or ticker

# By CoinGecko ID
cg price --ids bitcoin,ethereum -o json

# By ticker symbol (resolves to highest market cap match)
cg price --symbols btc,eth -o json

# Different currency
cg price --ids bitcoin --vs eur -o json

Market rankings

# Top 100 by market cap
cg markets --total 100 -o json

# Filter by category
cg markets --total 50 --category layer-2 -o json
cg markets --total 50 --category artificial-intelligence -o json

# Sort by volume
cg markets --total 100 --order volume_desc -o json

Search and discover

# Find a coin's CoinGecko ID
cg search solana -o json

# Trending coins, NFTs, and categories
cg trending -o json

Historical data

# Price on a specific date
cg history bitcoin --date 2024-01-15 -o json

# Past 30 days
cg history bitcoin --days 30 -o json

# Custom date range
cg history bitcoin --from 2024-01-01 --to 2024-06-30 -o json

# OHLC candle data
cg history bitcoin --days 7 --ohlc -o json

# Export to CSV
cg history bitcoin --days 30 --export btc_30d.csv

Debugging

# Dry-run — show API request without executing
cg price --ids bitcoin --dry-run

Gotchas

Coin IDs vs tickers: cg price accepts both (--ids bitcoin or --symbols btc). When using --symbols, the API returns the highest market-cap match
History date format: cg history accepts YYYY-MM-DD — the CLI converts to the API's DD-MM-YYYY format internally
Market chart granularity: --days 1 returns 5-minute intervals, 2-90 returns hourly, 90+ returns daily. Cannot be overridden on free plans
Category IDs: Find category IDs at coingecko.com/en/categories (copy from URL slug)
Rate limits: Demo key ~30-50 calls/min, no key ~10-30 calls/min. CLI handles retry with backoff on 429s

Install

npx skills add maxyz-xyz/skills --skill coingecko

Additional Resources

CLI repo: coingecko/coingecko-cli
API docs: https://docs.coingecko.com/reference/introduction