coinmarketcap-sdk

The official Python SDK for the CoinMarketCap Pro API.

Installation

pip install coinmarketcap-sdk
# or
uv add coinmarketcap-sdk
# or
poetry add coinmarketcap-sdk

Note: The PyPI package is coinmarketcap-sdk, but you import it as coinmarketcap:

from coinmarketcap import CoinMarketCap

Quick Start

import os
from coinmarketcap import CoinMarketCap

cmc = CoinMarketCap(api_key=os.environ["CMC_PRO_API_KEY"])

# Use the namespace API — discover endpoints by category with autocomplete
quotes = cmc.cryptocurrency.quotes_latest(id="1,1027")  # 1 = BTC, 1027 = ETH
print(quotes)

Usage

Namespace API (Recommended)

All endpoints are grouped by category on the client instance:

from coinmarketcap import CoinMarketCap

cmc = CoinMarketCap(api_key="your-key")

cmc.cryptocurrency.quotes_latest(id="1")
cmc.cryptocurrency.listings_latest(limit=10)
cmc.global_metrics.quotes_latest()
cmc.exchange.info(id="270")

Async variants are available with the async_ prefix:

quotes = await cmc.cryptocurrency.async_quotes_latest(id="1,1027")

POST Endpoints (Request Models)

POST endpoints require typed request body models:

from coinmarketcap import CoinMarketCap
from coinmarketcap.models import DqueryBatchPriceRequestDTO

cmc = CoinMarketCap(api_key="your-key")

body = DqueryBatchPriceRequestDTO.from_dict({
    "tokens": [{"platform": "ethereum", "address": "0x..."}],
})
prices = cmc.token.batch_get_token_price(body=body)

All 400+ request/response models are available via coinmarketcap.models.

Configuration Options

cmc = CoinMarketCap(
    # Required for 'pro' mode
    api_key="your-api-key",

    # Optional
    environment="pro",      # 'pro' (default) or 'public'
    base_url=None,          # Override base URL entirely
    timeout=30.0,           # Request timeout in seconds (default: 30s)
    max_retries=2,          # Auto-retry count (default: 2)
)

Public (Keyless) Mode

Use the public API without an API key for publicly available endpoints:

from coinmarketcap import CoinMarketCap

cmc = CoinMarketCap(environment="public")

cmc.cryptocurrency.listings_latest(limit=10)

Error Handling

The SDK raises typed exception classes for common HTTP failures:

from coinmarketcap import CoinMarketCap, CMCError, RateLimitError, AuthenticationError

cmc = CoinMarketCap(api_key="your-key")

try:
    quotes = cmc.cryptocurrency.quotes_latest(id="1")
except RateLimitError as e:
    # e.headers carries response headers, e.g. Retry-After
    print("Rate limited, retry after:", e.headers.get("Retry-After"))
except AuthenticationError as e:
    print("Invalid API key:", e)
except CMCError as e:
    # HTTP-level failures: e.status_code, e.body, e.headers
    print(f"API error {e.status_code}:", e)

CMCError (and its subclasses) expose status_code, body, and headers. Transport-level failures raise APIConnectionError / APITimeoutError after retries are exhausted; the original httpx exception is available on .cause. APITimeoutError is a subclass of APIConnectionError, so catching the latter also catches timeouts.

Error Types

Automatic Retries

Requests that fail with retryable status codes are automatically retried with exponential backoff:

• Retryable statuses: 408, 409, 429, 500, 502, 503, 504
• Retryable network errors: connect/read/write/pool timeouts, connection errors, remote protocol errors, and proxy errors
• Default: 2 retries with 500ms initial delay and exponential backoff, up to 8s max
• 429 responses: Respects the Retry-After header when present

Both sync and async calls share the same retry behavior.

Disable retries:

cmc = CoinMarketCap(api_key="your-key", max_retries=0)

Timeout

Requests time out after 30 seconds by default:

cmc = CoinMarketCap(api_key="your-key", timeout=10.0)  # 10 seconds

Available Endpoints

All endpoints are available via cmc.<category>.<method>(). Categories include:

• cmc.cryptocurrency — Quotes, listings, market pairs, OHLCV, categories
• cmc.exchange — Exchange info, listings, market pairs
• cmc.global_metrics — Global stats, fear & greed index
• cmc.content — News, posts
• cmc.community — Trending tokens, topics
• cmc.token — DEX token data, pools, trades
• cmc.derivatives — Derivatives market data
• cmc.cmc_index — CMC 20/100 index

Requirements

• Python >= 3.10

License

MIT