Coinmarketcap

CoinMarketCap Skill

Reference files:

• references/endpoints.md — full catalog by category with credit formulas
• references/credits.md — budget rules, cost estimation, plan tiers
• references/patterns.md — batching, caching, CMC vs alternatives
• references/examples/*.py — working Python scripts

🚨 Rule #1: credits, not requests

CoinMarketCap meters by credits, not by request count. The formula is:

credits_per_call = max(1, ceil(data_points_returned / 100))

Where data_points ≈ rows × columns × (1 + extra_convert_currencies).

Cheap calls (1 credit):

• Up to 100 cryptos on quotes/latest
• Up to 200 cryptos on listings/latest
• Any single-token lookup (map, info, pools)
• global-metrics, key/info, fiat/map

Expensive calls:

• listings/latest?limit=5000 = 25 credits (verified)
• ohlcv/historical with many points × many cryptos = points / 100
• market-pairs/latest with 500+ pairs
• Adding convert=USD,EUR,GBP → +1 credit per extra currency

Always check status.credit_count in response and log it.

🚨 Rule #2: budget thresholds (applied per call)

For batch jobs (N calls): threshold applied to total. 100 × 2 credits = 200 → announce. 100 × 5 = 500 → stop.

Check budget via GET /v1/key/info (free, 0 credits) before big sessions.

🚨 Rule #3: use CMC IDs, not symbols

Symbols collide (BTC might point to any of several tokens), can change, and break over time. CMC IDs are stable numeric identifiers.

Always:

1. Resolve symbols/names once via /v1/cryptocurrency/map
2. Cache the ID → (symbol, name) mapping on your side
3. Use IDs for all subsequent /quotes/*, /ohlcv/*, /info calls

Example:

BTC → 1
ETH → 1027
SOL → 5426

🚨 Rule #4: batch aggressively

Single call endpoints accept many IDs:

• /v2/cryptocurrency/quotes/latest?id=1,1027,5426,... — up to 100 IDs, still 1 credit
• /v1/cryptocurrency/listings/latest?limit=200 — 1 credit for top 200
• /v2/cryptocurrency/info?id=1,2,3,...,100 — 1 credit for 100 tokens' metadata

Never loop for sym in symbols: quote(sym). One call with all IDs saves N-1 credits and N-1 round trips.

Authentication

export CMC_API_KEY="..."
curl -H "X-CMC_PRO_API_KEY: $CMC_API_KEY" \
  "https://pro-api.coinmarketcap.com/v1/cryptocurrency/quotes/latest?symbol=BTC"

Base URL:

• Production: https://pro-api.coinmarketcap.com
• Sandbox (testing): https://sandbox-api.coinmarketcap.com

Step-by-step workflow

1. Classify the task

• "What's the price of X?" → /v2/cryptocurrency/quotes/latest with id=<CMC_ID>
• "Top N by market cap" → /v1/cryptocurrency/listings/latest?limit=N
• "Historical price chart" → /v3/cryptocurrency/quotes/historical or /v2/cryptocurrency/ohlcv/historical
• "What's trending right now" → /v1/cryptocurrency/trending/latest
• "Global market stats" → /v1/global-metrics/quotes/latest
• "Fear & Greed" → /v3/fear-and-greed/latest
• "Exchange volume" → /v1/exchange/listings/latest or /v1/exchange/quotes/latest
• "DEX token details" → /v1/dex/token (needs network_slug + contract_address)

2. Resolve any symbols to CMC IDs first (if you don't have them cached)

curl "$BASE/v1/cryptocurrency/map?symbol=BTC,ETH,SOL" -H "X-CMC_PRO_API_KEY: $KEY"

3. Estimate credits — see references/credits.md. Apply thresholds.

4. Execute — batch as much as the endpoint allows.

5. Log status.credit_count from response. If the user has ongoing budget concerns, run /v1/key/info periodically.

6. Present results — format USD with commas, timestamps to local, mcap in B/T (billions/trillions).

Common recipes

Price for 50 tokens right now

ids = ",".join([str(cmc_id) for cmc_id in coins])  # up to 100
r = httpx.get(f"{BASE}/v2/cryptocurrency/quotes/latest?id={ids}",
              headers={"X-CMC_PRO_API_KEY": KEY})
# 1 credit, one round trip

Daily OHLCV for BTC, last 90 days

r = httpx.get(f"{BASE}/v2/cryptocurrency/ohlcv/historical",
              params={"id": 1, "count": 90, "interval": "daily"},
              headers={"X-CMC_PRO_API_KEY": KEY})
# 1 credit (90 points < 100)

Top 200 coins by mcap

r = httpx.get(f"{BASE}/v1/cryptocurrency/listings/latest?limit=200",
              headers={"X-CMC_PRO_API_KEY": KEY})
# 1 credit

Fear & Greed today + 30 days back

r = httpx.get(f"{BASE}/v3/fear-and-greed/historical?count=30",
              headers={"X-CMC_PRO_API_KEY": KEY})

Live budget check

curl -H "X-CMC_PRO_API_KEY: $KEY" "$BASE/v1/key/info"
# 0 credits; returns plan, usage, remaining

See references/examples/ for complete runnable scripts.

Error handling

CoinMarketCap vs alternatives

Use CMC for authoritative/historical/ranked data, DexScreener or chain-specific APIs for real-time DEX/token granularity.

Reference files

• references/endpoints.md — catalog + credit formulas, tier requirements
• references/credits.md — budget rules, plan comparison, cost estimation heuristics
• references/patterns.md — batching, caching, when to use CMC
• references/examples/fetch_prices_batch.py — bulk quote fetch with ID resolution
• references/examples/historical_ohlcv.py — daily candles for analysis
• references/examples/global_dashboard.py — global metrics + F&G + trending in one shot

Related skills

• dexscreener-skill — free/no-auth DEX pair data
• dune-skill — historical SQL with deeper granularity than CMC OHLCV
• solana-rpc-skill — on-chain Solana specifics
• nansen-skill — smart-money + wallet profiling (orthogonal to CMC)