CoinMarketCap crypto-rates sibling provider for @suaveplan/currency. One of the nine @suaveplan/currency-provider-<name> sibling packages spun out of the 2026-05-17 slim refactor of @suaveplan/currency-providers. Consumes the slim core's CurrencyProviderError registry, ApiKeyConfig type, and shared httpRequest() HTTP helper; talks to pro-api.coinmarketcap.com via the X-CMC_PRO_API_KEY header.

Documentation tree

coinmarketcap — CoinMarketCapProvider is the @suaveplan/currency-providers sibling that fetches cryptocurrency spot prices from the…
- coinmarketcap — CoinMarketCapProvider is the @suaveplan/currency-providers sibling that fetches cryptocurrency spot prices from the…

Install

bun add @suaveplan/currency-provider-coinmarketcap @suaveplan/currency-providers @suaveplan/currency

Quick start

import { CurrencyConverter } from "@suaveplan/currency";
import { CurrencyProviderRegistry } from "@suaveplan/currency-providers";
import { CoinMarketCapProvider } from "@suaveplan/currency-provider-coinmarketcap";

const registry = new CurrencyProviderRegistry();
registry.register(
    new CoinMarketCapProvider({ apiKey: process.env.CMC_API_KEY ?? "" })
);

const converter = new CurrencyConverter({
    provider: registry.get("coinmarketcap"),
});

const rate = await converter.getRate("BTC", "USD");

Direct instantiation works equally well:

import { CurrencyConverter } from "@suaveplan/currency";
import { CoinMarketCapProvider } from "@suaveplan/currency-provider-coinmarketcap";

const converter = new CurrencyConverter({
    provider: new CoinMarketCapProvider({ apiKey: process.env.CMC_API_KEY ?? "" }),
});

Features

Implements CurrencyProvider (name = "coinmarketcap", supportsCrypto = true, supportsFiat = false)
ApiKeyConfig constructor — apiKey required, baseUrl optional (defaults to https://pro-api.coinmarketcap.com/v1), injectable FetchLike from @suaveplan/types
Authenticated via the upstream X-CMC_PRO_API_KEY header; Accept set to application/json on every request
Default target list covers the top 10 crypto by market cap (BTC,ETH,SOL,USDT,USDC,BNB,XRP,ADA,DOGE,DOT); override via options.targets
Default base is USD; any fiat conversion currency works via options.base
Prices are inverted (1 / price) into the converter's expected 1 fiat = X crypto form
Typed errors via CurrencyProviderError — MISSING_CONFIG (empty apiKey), HTTP_ERROR (non-2xx), PARSE_ERROR (invalid JSON / missing data), UPSTREAM_ERROR (status.error_code populated), UNKNOWN_CURRENCY (no symbol resolved). Every error carries providerName: "coinmarketcap"
HTTP plumbing (abort-signal composition, timeout, non-2xx mapping) delegated to the slim core's httpRequest() — uniform with every other sibling provider
Universal (sideEffects: false); 100/100/100/100 istanbul coverage; 2 subpath exports

Modules

src/coinmarketcap/coinmarketcap.md — CoinMarketCapProvider

Status

0.1.0 (pre-graduation). Sibling provider landed alongside the 2026-05-17 slim refactor of @suaveplan/currency-providers. See the design proposal for the change record.