Coinmarketcap

CoinMarketCap Skill

Reference files:

• [references/endpoints.md](references/endpoints.md) — full catalog by category with credit formulas
• [references/credits.md](references/credits.md) — budget rules, cost estimation, plan tiers
• [references/patterns.md](references/patterns.md) — batching, caching, CMC vs alternatives
• [references/examples/*.py](references/examples/) — 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)

| Estimated credits | Action | |-------------------|--------| | 200 | STOP. Propose alternative (narrower limit, targeted id list, cached data, different endpoint). Execute only with approval. |

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=
• "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 networkslug + contractaddress)

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

| HTTP | CMC code | Meaning | Action | |------|----------|---------|--------| | 401 | 1001 | Invalid key | Check env var | | 401 | 1002 | Missing key header | Add X-CMC_PRO_API_KEY | | 403 | 1006 | Endpoint not in plan | Report to user; find alternative | | 429 | 1008 | Minute limit hit | Sleep 60s | | 429 | 1009 | Daily limit | Await daily reset or upgrade | | 429 | 1010 | Monthly limit | Await monthly reset or upgrade | | 429 | 1011 | IP rate limit | Lower concurrency | | 500 | — | Server error | Exponential backoff, then report |

CoinMarketCap vs alternatives

| Need | Best | |------|------| | Authoritative price + market cap rankings | CMC (what the industry references) | | Live DEX pair data on specific chain | DexScreener (free) or GeckoTerminal | | On-chain Solana-specific | Solscan, Helius | | Historical 5y+ OHLCV | CMC (Professional plan, all-time) | | Rich metadata (logos, descriptions, URLs) | CMC /v2/cryptocurrency/info | | Exchange volume over time | CMC /v1/exchange/quotes/historical | | Fear & Greed Index | CMC /v3/fear-and-greed/* (authoritative source) | | Broad trending + community pulse | CMC /community/trending/* + /content/* |

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

Reference files

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

Related skills

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Vo1ganin
• Source: Vo1ganin/crypto-claude-skills
• License: MIT

Install and usage instructions live in the source repository linked above.