---
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

```bash
# 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

```bash
# 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

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

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

### Historical data

```bash
# 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

```bash
# 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](https://www.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

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

## Additional Resources

- CLI repo: [coingecko/coingecko-cli](https://github.com/coingecko/coingecko-cli)
- API docs: https://docs.coingecko.com/reference/introduction