paulrberg/coingecko-cli

CoinGecko CLI

Overview

Query cryptocurrency market data using the official CoinGecko CLI (cg). The CLI wraps the CoinGecko V3 API with structured JSON output, a dry-run mode, and a self-describing command catalog — designed to be driven by agents.

Key capabilities:

• Current prices by coin ID or symbol (cg price)
• Top coins by market cap with filters and CSV export (cg markets)
• Coin search with fuzzy matching (cg search)
• Trending coins, NFTs, and categories (cg trending)
• Historical price snapshots, time series, and OHLC (cg history)
• Top gainers/losers over configurable durations (cg top-gainers-losers, paid)

Out of scope — cg does not support contract-address price lookups, global market stats (total market cap, BTC/ETH dominance), NFT detail endpoints, GeckoTerminal on-chain DEX queries, or token logo metadata. Fall back to WebFetch against docs.coingecko.com/llms.txt for those.

Prerequisites

Verify the CLI is installed:

command -v cg || { echo "cg not on PATH; install via: brew install coingecko/coingecko-cli/cg"; exit 1; }

Check authentication and tier without running interactive setup:

cg status -o json

The CLI reads CG_API_KEY and CG_API_TIER (demo or paid) from the environment. If cg status shows no key, ask the user before invoking cg auth — that command is interactive and writes config to disk.

Tier Matrix

| Tier | Rate Limit | Monthly Cap | History | Paid-Only Commands | | ----------- | ---------------- | ----------- | ------- | -------------------- | | Demo (free) | ~30 req/min | ~10,000 | 1 year | — | | Analyst | ~500 req/min | ~500,000 | Deeper | top-gainers-losers | | Lite / Pro | 500–1000 req/min | 1M–3M | Deeper | top-gainers-losers |

Detect feature gating up front by reading the paid_only field in cg commands -o json.

Output Conventions

• Always pass -o json for any output that needs to be parsed by the agent. The default table format is for humans.
• Use --dry-run to preview the underlying API request as JSON without executing it. Useful when validating an unfamiliar flag combination before spending a quota.
• Use --export <file.csv> only when the user explicitly asks for CSV (cg markets, cg history, cg top-gainers-losers support this).

Coin ID Resolution

CoinGecko identifies coins by string ID (e.g. bitcoin, ethereum), not symbol. Many IDs diverge from the coin's common name.

Resolution order:

1. Known coin — use the table below.
2. Symbol — cg price --symbols btc,eth ... works but symbols are non-unique. Only the top-market-cap coin per symbol is returned.
3. Unknown / ambiguous — cg search <term> -o json to resolve the ID first, then re-issue the real query.

Common Coin IDs

| Coin | ID | Symbol | | ----------- | ------------------------- | ------ | | Bitcoin | bitcoin | BTC | | Ethereum | ethereum | ETH | | Solana | solana | SOL | | BNB | binancecoin | BNB | | XRP | ripple | XRP | | Cardano | cardano | ADA | | Dogecoin | dogecoin | DOGE | | Chainlink | chainlink | LINK | | Avalanche | avalanche-2 | AVAX | | Polygon | polygon-ecosystem-token | POL | | Uniswap | uniswap | UNI | | Aave | aave | AAVE | | Maker | maker | MKR | | USDC | usd-coin | USDC | | USDT | tether | USDT | | DAI | dai | DAI | | Wrapped BTC | wrapped-bitcoin | WBTC |

Core Commands

Price

cg price --ids bitcoin,ethereum --vs usd -o json
cg price --symbols btc,eth --vs eur -o json

Returns { "<id>": { "<currency>": <price>, "<currency>_24h_change": <pct> } }.

Markets

# Top 50 by market cap in USD
cg markets --total 50 --vs usd -o json

# Layer-1 category, sorted by volume, exported to CSV
cg markets --category layer-1 --order volume_desc --export l1.csv

--order enum: market_cap_desc (default), market_cap_asc, volume_desc, volume_asc, id_asc, id_desc. Category IDs come from cg commands -o json or /coins/categories/list.

Search

cg search ethereum --limit 5 -o json

Returns an array of { id, name, symbol, market_cap_rank }. Use this first whenever the user gives only a name or symbol.

Trending

cg trending -o json

Returns trending coins, nfts, and categories from the last 24h. --show-max coins,nfts,categories increases the per-section limit (paid only).

History

cg history <coin> has three mutually exclusive query modes:

# Snapshot on a single date
cg history bitcoin --date 2024-01-01 -o json

# Last N days, auto-granularity
cg history ethereum --days 30 -o json

# Explicit date range; --to covers the full day up to 23:59:59 UTC
cg history solana --from 2024-01-01 --to 2024-03-01 -o json

Modifiers:

• --ohlc — switch from price series to candlesticks. In --days mode, only 1, 7, 14, 30, 90, 180, 365, max are accepted.
• --interval daily|hourly — override auto-granularity for --days or --from/--to. Large ranges auto-batch into multiple API requests.
• --vs <currency> — quote currency (default usd).
• --export <file.csv> — write to CSV.

Returned JSON in price mode: { "prices": [[ts_ms, price], ...], "market_caps": [...], "total_volumes": [...] }. In OHLC mode the response is a bare array of [ts_ms, open, high, low, close] tuples.

Top Gainers / Losers (paid)

cg top-gainers-losers --duration 24h --top-coins 1000 -o json
cg top-gainers-losers --losers --duration 7d --price-change-percentage 1h,7d,30d -o json

--duration enum: 1h, 24h, 7d, 14d, 30d, 60d, 1y. --top-coins enum: 300, 500, 1000, all. Returns 401 on demo tier — check paid_only via cg commands before calling.

Output Formatting

Default to a Markdown table when presenting results to the user. Honour explicit format requests (JSON, CSV, plain text).

Number formatting:

• Prices > $1 → 2 decimals ($67,187.34)
• Prices $0.01 – $1 → 4 decimals ($0.4523)
• Prices < $0.01 → 6+ decimals ($0.000001234)
• Market caps → abbreviated ($1.32T, $415.2B, $8.5M)
• Percentages → signed, 2 decimals (+3.64%, -1.23%)

Self-Discovery

When the inline examples don't cover what's needed, query the CLI's own machine-readable catalog:

cg commands -o json

Each entry includes name, description, examples, flags (with type, default, enum), output_formats, api_endpoint, oas_operation_id, requires_auth, and paid_only. Use it to detect tier gating before issuing a command, or to find the exact enum values for a flag.

For one-off flag lookups:

cg <subcommand> --help

Rate Limits & Errors

• HTTP 429 — back off briefly and retry; batch coin IDs into single calls (--ids a,b,c) wherever the command allows.
• Missing / invalid key — cg status -o json surfaces it. Prompt the user; do not run cg auth non-interactively.
• Paid-only command on demo tier — detect via the paid_only field in cg commands -o json before invoking. The CLI will otherwise return an API error.

Additional Resources

• CLI repo: https://github.com/coingecko/coingecko-cli
• AI agent guide: https://docs.coingecko.com/docs/ai-agent-hub/cli
• AI-friendly API docs: https://docs.coingecko.com/llms.txt — fetch via WebFetch for endpoints cg does not expose (contract-address prices, NFT details, GeckoTerminal on-chain DEX data).