CoinGecko API

Overview

Query cryptocurrency market data using the CoinGecko API V3. This skill covers:

• Price lookups by coin ID, symbol, or contract address
• Market data with rankings, volume, and price changes
• Historical price charts and OHLC data
• Search and trending coins
• Global market statistics

Scope: Covers the Demo (free), Analyst, Lite, and Pro tiers. For on-chain DEX data (GeckoTerminal endpoints), consult the fallback documentation.

Prerequisites

API Key Detection

Before making any API call, determine the available API key:

if [ -n "$COINGECKO_PRO_API_KEY" ]; then
  CG_BASE="https://pro-api.coingecko.com/api/v3"
  CG_AUTH=(-H "x-cg-pro-api-key: $COINGECKO_PRO_API_KEY")
elif [ -n "$COINGECKO_API_KEY" ]; then
  CG_BASE="https://api.coingecko.com/api/v3"
  CG_AUTH=(-H "x-cg-demo-api-key: $COINGECKO_API_KEY")
else
  CG_BASE="https://api.coingecko.com/api/v3"
  CG_AUTH=()
  echo "Warning: No CoinGecko API key found. Using keyless access (stricter rate limits)."
  echo "For higher limits, set COINGECKO_API_KEY or COINGECKO_PRO_API_KEY."
fi

API Tiers

Tier	Base URL	Auth Header	Rate Limit
Demo	https://api.coingecko.com/api/v3	x-cg-demo-api-key	~30 calls/min, ~10k/month
Analyst / Lite / Pro	https://pro-api.coingecko.com/api/v3	x-cg-pro-api-key	Plan-dependent

Authentication via HTTP header (recommended). Query parameters (x_cg_demo_api_key / x_cg_pro_api_key) also work.

Coin ID Resolution

CoinGecko uses string IDs (e.g., bitcoin, ethereum, uniswap) rather than symbols. Before querying, resolve the correct coin ID.

Resolution Strategy

1. Common coins — Use well-known IDs directly: bitcoin, ethereum, solana, cardano, chainlink, uniswap, aave, maker. Note that some IDs diverge from the coin name: binancecoin (BNB), avalanche-2 (AVAX), polygon-ecosystem-token (POL) — see the table below.
2. Symbol lookup — Use /simple/price with the symbols parameter for quick lookups: symbols=btc,eth. Symbols are not unique — multiple coins can share the same symbol. By default, only the top-market-cap coin per symbol is returned; pass include_tokens=all to get all matches.
3. Ambiguous symbols — If a symbol maps to multiple coins (e.g., "UNI" could be Uniswap or Universe), use /search?query=<name> to disambiguate. Always verify the result matches the user's intent.
4. Contract address — Use /simple/token_price/{platform_id} when a contract address is provided.
5. Unknown coins — Use /search?query=<term> to find the correct ID before querying.

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

Platform Resolution

Do not default to Ethereum. Always infer the platform from the user's prompt before making contract-based API calls.

Inference Rules

1. Explicit platform mention — If the user mentions a chain name (e.g., "on Polygon", "Arbitrum token", "Base chain"), map it to the corresponding platform ID (see ./references/PLATFORMS.md).
2. Platform-specific tokens — Some tokens exist primarily on specific platforms:
   • SOL, BONK, JUP → Solana (solana)
   • POL → Polygon (polygon-pos)
   • ARB → Arbitrum One (arbitrum-one)
   • OP → Optimism (optimistic-ethereum)
3. Address format hints — Base58 addresses (no 0x prefix) may be Solana or Tron — ask the user to clarify. 0x-prefixed addresses are EVM but exist on multiple chains.
4. Testnet keywords — Words like "testnet", "Sepolia", "Goerli", "devnet" indicate testnets. CoinGecko does not index testnet tokens — inform the user immediately.
5. Ambiguous cases — If the platform cannot be inferred, ask the user before proceeding. Do not assume Ethereum.

Unsupported Platforms

If the user references a chain not indexed by CoinGecko, respond with:

The chain "[chain name]" is not supported by the CoinGecko API.

For the current list of supported platforms, query:
https://api.coingecko.com/api/v3/asset_platforms

For a curated list of common platforms, see ./references/PLATFORMS.md. For the full live index, query the endpoint above.

Core Workflows

Quick Price Check

Fetch current price for one or more coins:

curl -s "$CG_BASE/simple/price?ids=bitcoin,ethereum&vs_currencies=usd&include_24hr_change=true&include_market_cap=true" "${CG_AUTH[@]}"

For symbol-based lookups:

curl -s "$CG_BASE/simple/price?symbols=btc,eth&vs_currencies=usd" "${CG_AUTH[@]}"

Token Price by Contract Address

Fetch price using a contract address on a specific chain:

curl -s "$CG_BASE/simple/token_price/ethereum?contract_addresses=0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48&vs_currencies=usd&include_market_cap=true" "${CG_AUTH[@]}"

Common platform IDs: ethereum, polygon-pos, arbitrum-one, optimistic-ethereum, base, avalanche, binance-smart-chain. For the full list, see ./references/PLATFORMS.md.

Token Logo

The /coins/{id} response includes logo URLs in the image object:

Field	Typical Size
image.thumb	25x25 px
image.small	50x50 px
image.large	200x200 px

Fetch via /coins/{id} or /coins/{platform}/contract/{address} — the image field is present in both responses.

Market Rankings

Fetch top coins by market cap with detailed data:

curl -s "$CG_BASE/coins/markets?vs_currency=usd&order=market_cap_desc&per_page=10&page=1&price_change_percentage=24h,7d" "${CG_AUTH[@]}"

Historical Price Data

Fetch price history for charts:

# Last 7 days (hourly granularity)
curl -s "$CG_BASE/coins/bitcoin/market_chart?vs_currency=usd&days=7" "${CG_AUTH[@]}"

# Last 365 days (daily granularity)
curl -s "$CG_BASE/coins/bitcoin/market_chart?vs_currency=usd&days=365" "${CG_AUTH[@]}"

Auto-granularity: 1 day → 5-min intervals, 2-90 days → hourly, >90 days → daily.

Response contains prices, market_caps, and total_volumes arrays of [timestamp_ms, value] pairs.

OHLC / Candlestick Data

Fetch OHLC data for charting:

curl -s "$CG_BASE/coins/bitcoin/ohlc?vs_currency=usd&days=7" "${CG_AUTH[@]}"

Returns [[timestamp, open, high, low, close], ...]. Valid days values: 1, 7, 14, 30, 90, 180, 365, max.

Global Market Stats

curl -s "$CG_BASE/global" "${CG_AUTH[@]}"

Returns total market cap, 24h volume, BTC/ETH dominance percentages, and active cryptocurrencies count.

Search for a Coin

curl -s "$CG_BASE/search?query=sablier" "${CG_AUTH[@]}"

Returns matching coins, exchanges, categories, and NFTs sorted by market cap.

Trending Coins

curl -s "$CG_BASE/search/trending" "${CG_AUTH[@]}"

Returns top trending coins based on CoinGecko search activity.

Output Formatting

Default behavior: Present results in a Markdown table:

| Coin | Price (USD) | 24h Change | Market Cap |
| ---- | ----------- | ---------- | ---------- |
| Bitcoin | $67,187.34 | +3.64% | $1.32T |
| Ethereum | $3,456.78 | +2.15% | $415.2B |

User preference: If the user requests a specific format (JSON, CSV, plain text), use that format instead.

Number Formatting

• Prices > $1: 2 decimal places (e.g., $67,187.34)
• Prices $0.01–$1: 4 decimal places (e.g., $0.4523)
• Prices < $0.01: 6+ decimal places (e.g., $0.000001234)
• Market caps: abbreviated (e.g., $1.32T, $415.2B, $8.5M)
• Percentages: 2 decimal places with sign (e.g., +3.64%, -1.23%)

Rate Limits

For Pro/Analyst/Lite plans, query the /key endpoint for live quotas (Pro base URL only — returns 401 on Demo):

curl -s "https://pro-api.coingecko.com/api/v3/key" -H "x-cg-pro-api-key: $COINGECKO_PRO_API_KEY"

Returns plan, rate_limit_request_per_minute, monthly_call_credit, and current_remaining_monthly_calls. Demo users should refer to the pricing page for current limits.

Approximate defaults (may vary):

Tier	Requests/Min	Monthly Cap
Demo (free)	~30	~10,000
Analyst	~500	~500,000
Lite	~500	~1,000,000
Pro	~1,000	~3,000,000

If rate limited (HTTP 429), wait briefly and retry. Batch multiple coin queries into single calls using comma-separated IDs where possible.

Error Handling

HTTP Code	Error Code	Cause	Action
401	10002	Invalid or missing API key	Verify the key value and base URL match the tier
401	10005	Endpoint not included in current plan	Use the tier-restricted fallback below
429	—	Rate limit exceeded	Wait and retry; reduce request frequency
200 {}	—	Unknown coin ID or contract address	/simple/* endpoints return empty {} instead of 404 for unrecognized IDs/addresses. Treat an empty response as "not found" and use /search to resolve the correct ID
404	—	Invalid endpoint path	Verify the endpoint URL is correct

Tier-Restricted Endpoints

Some endpoints return 401 (error code 10005) on the Pro base URL for lower-tier plans (e.g., Analyst) but work on the Demo base URL.

Known Analyst-tier restrictions (401/10005 on Pro base URL):

• /search/trending
• /global
• /global/decentralized_finance_defi

Fallback strategy: On a 401 with error code 10005, retry on the Demo base URL. If COINGECKO_API_KEY is available, use it for better rate limits; otherwise fall back to keyless:

if [ -n "$COINGECKO_API_KEY" ]; then
  curl -s "https://api.coingecko.com/api/v3/search/trending" \
    -H "x-cg-demo-api-key: $COINGECKO_API_KEY"
else
  curl -s "https://api.coingecko.com/api/v3/search/trending"
fi

Do not use this fallback for error code 10002 (invalid key) — that indicates a misconfigured API key, not a tier restriction.

Reference Files

• ./references/ENDPOINTS.md — Curated endpoint reference with parameters, response formats, and asset platform IDs
• ./references/PLATFORMS.md — Curated list of common asset platform IDs with chain mappings (query /asset_platforms for the full live index)

Fallback Documentation

For endpoints not covered by this skill (on-chain DEX data, NFT details, exchange-specific queries), fetch the AI-friendly documentation:

https://docs.coingecko.com/llms.txt

Use WebFetch to retrieve this documentation for extended API capabilities.