The official TypeScript/JavaScript SDK for the CoinMarketCap Pro API.
npm install @coinmarketcap/sdk
# or
yarn add @coinmarketcap/sdk
# or
pnpm add @coinmarketcap/sdkimport { CoinMarketCap } from "@coinmarketcap/sdk";
const cmc = new CoinMarketCap({ apiKey: process.env.CMC_PRO_API_KEY! });
// Use the namespace API — discover endpoints by category with autocomplete
const { data, error } = await cmc.api.cryptocurrency.quotesLatest({
query: { id: "1,1027" }, // 1 = BTC, 1027 = ETH
});
if (data) {
console.log(data);
}All endpoints are grouped by category on cmc.api:
import { CoinMarketCap } from "@coinmarketcap/sdk";
const cmc = new CoinMarketCap({ apiKey: "your-key" });
await cmc.api.cryptocurrency.quotesLatest({ query: { id: "1" } });
await cmc.api.cryptocurrency.listingsLatest({ query: { limit: 10 } });
await cmc.api.globalMetrics.quotesLatest({});
await cmc.api.exchange.info({ query: { id: "270" } });You can also import individual functions and pass the client explicitly:
import {
CoinMarketCap,
getV1CryptocurrencyQuotesLatest,
} from "@coinmarketcap/sdk";
const cmc = new CoinMarketCap({ apiKey: "your-key" });
const { data } = await getV1CryptocurrencyQuotesLatest({
client: cmc.client,
query: { id: "1", convert: "USD" },
});For simple scripts, init() configures the global client so bare functions work without passing client:
import { init, getV1CryptocurrencyQuotesLatest } from "@coinmarketcap/sdk";
const cmc = init({ apiKey: "your-key" });
// Namespace works on the returned instance
await cmc.api.cryptocurrency.quotesLatest({ query: { id: "1" } });
// Bare functions also work (use the global client)
await getV1CryptocurrencyQuotesLatest({ query: { id: "1" } });const cmc = new CoinMarketCap({
// Required for 'pro' mode
apiKey: "your-api-key",
// Optional
environment: "pro", // 'pro' (default) or 'public'
baseUrl: undefined, // Override base URL entirely
timeout: 30000, // Request timeout in ms (default: 30s)
maxRetries: 2, // Auto-retry count (default: 2)
fetch: customFetch, // Custom fetch implementation
});Use the public API without an API key for publicly available endpoints:
import { CoinMarketCap } from "@coinmarketcap/sdk";
const cmc = new CoinMarketCap({ environment: "public" });
await cmc.api.cryptocurrency.listingsLatest({ query: { limit: 10 } });The SDK provides typed error classes for common HTTP failures:
import {
CoinMarketCap,
CMCError,
RateLimitError,
AuthenticationError,
} from "@coinmarketcap/sdk";
const cmc = new CoinMarketCap({ apiKey: "your-key" });
const { data, error } = await cmc.api.cryptocurrency.quotesLatest({
query: { id: "1" },
});
if (error) {
if (error instanceof RateLimitError) {
console.log("Rate limited, retry after:", error.headers.get("Retry-After"));
} else if (error instanceof AuthenticationError) {
console.log("Invalid API key");
} else if (error instanceof CMCError) {
console.log(`API error ${error.status}:`, error.message);
}
}| Status Code | Error Class |
|---|---|
| 400 | BadRequestError |
| 401 | AuthenticationError |
| 403 | ForbiddenError |
| 404 | NotFoundError |
| 429 | RateLimitError |
| 5xx | InternalServerError |
| Network | APIConnectionError |
| Timeout | APITimeoutError |
Alternatively, you can throw errors instead of returning them:
import { CoinMarketCap, RateLimitError } from "@coinmarketcap/sdk";
const cmc = new CoinMarketCap({ apiKey: "your-key" });
try {
const { data } = await cmc.api.cryptocurrency.quotesLatest({
query: { id: "1" },
throwOnError: true,
});
console.log(data);
} catch (err) {
if (err instanceof RateLimitError) {
// handle rate limit
}
}Requests that fail with retryable status codes are automatically retried with exponential backoff:
- Retryable: 408, 409, 429, 500, 502, 503, 504, network errors, and timeouts
- Default: 2 retries with 500ms initial delay, up to 8s max
- 429 responses: Respects the
Retry-Afterheader, capped at the max delay (8s) so a large value can't stall the call - Body-safe: Request bodies are replayed correctly on each retry (POST endpoints included)
Disable retries:
const cmc = new CoinMarketCap({
apiKey: "your-key",
maxRetries: 0,
});Requests time out after 30 seconds by default:
const cmc = new CoinMarketCap({
apiKey: "your-key",
timeout: 10_000, // 10 seconds
});A timeout raises APITimeoutError.
Pass an AbortSignal to cancel an in-flight request. Caller cancellation is
honoured immediately and is never retried:
const controller = new AbortController();
const promise = cmc.api.cryptocurrency.quotesLatest({
query: { symbol: "BTC" },
signal: controller.signal,
});
controller.abort(); // rejects with an AbortErrorAll endpoints are available via cmc.api.<category>.<method>(). See api.md for the full reference.
Categories include:
cmc.api.cryptocurrency— Quotes, listings, market pairs, OHLCV, categoriescmc.api.exchange— Exchange info, listings, market pairscmc.api.globalMetrics— Global stats, fear & greed indexcmc.api.content— News, postscmc.api.community— Trending tokens, topicscmc.api.token— DEX token data, pools, tradescmc.api.derivatives— Derivatives market datacmc.api.cmcIndex— CMC 20/100 index
You can also import bare functions directly:
import {
getV1CryptocurrencyListingsLatest,
getV1CryptocurrencyInfo,
getV1CryptocurrencyMap,
// ... 100+ more endpoints
} from "@coinmarketcap/sdk";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 TypeScript (@coinmarketcap/sdk) and Python (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.
- Node.js >= 18
- TypeScript >= 5.0 (for TypeScript users)
MIT