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 ascoinmarketcap: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
| Status Code | Error Class |
|---|---|
| 400 | BadRequestError |
| 401 | AuthenticationError |
| 402 | PaymentRequiredError |
| 403 | ForbiddenError |
| 404 | NotFoundError |
| 429 | RateLimitError |
| 5xx | InternalServerError |
| Network | APIConnectionError |
| Timeout | APITimeoutError |
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-Afterheader 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, categoriescmc.exchange— Exchange info, listings, market pairscmc.global_metrics— Global stats, fear & greed indexcmc.content— News, postscmc.community— Trending tokens, topicscmc.token— DEX token data, pools, tradescmc.derivatives— Derivatives market datacmc.cmc_index— CMC 20/100 index
Versioning
The SDK follows Semantic Versioning. A major version removes or renames methods, or changes return types or response fields in a way that can break existing code. A minor version adds endpoints or fields. A patch version fixes bugs.
The Python (coinmarketcap-sdk) and TypeScript (@coinmarketcap/sdk) SDKs are released
together with the same version number. The SDK version is separate from the API's
endpoint versions (/v1, /v2, /v3). Each CHANGELOG entry names the
OpenAPI spec the release was built from and lists its breaking changes.
Requirements
- Python >= 3.10
License
MIT
Metadata
Release files for coinmarketcap-sdk 5.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| coinmarketcap_sdk-5.0.0.tar.gz | 333.8 kB | Without provenance | Details for coinmarketcap_sdk-5.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| coinmarketcap_sdk-5.0.0-py3-none-any.whl | Python 3 | none | any | Details for coinmarketcap_sdk-5.0.0-py3-none-any.whl |
Total release size: 1.3 MB
Release files / coinmarketcap_sdk-5.0.0.tar.gz
| Download URL | coinmarketcap_sdk-5.0.0.tar.gz |
|---|---|
| Size | 333.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
34896a0329536b27ac9f1ce5b33e8d21dc070273e4c8d8cedcb5960f79682b66
|
|
BLAKE2b-256 checksum How to use checksums |
3198830ca6e9192086d3ad1fc9c9d73b2c10da82139cb16e45f65411159a8841
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.6
|
Release files / coinmarketcap_sdk-5.0.0-py3-none-any.whl
| Download URL | coinmarketcap_sdk-5.0.0-py3-none-any.whl |
|---|---|
| Size | 930.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1eceeefb457c508603d4c133cefa61f7fe95cce6d5670c868893ce09f943802a
|
|
BLAKE2b-256 checksum How to use checksums |
d4c90d4256eb4bb461b1b494c5e2ffdef68340194e4396ba6eb64ee3d420c3d4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.6
|
Security for coinmarketcap-sdk 5.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.