# @suaveplan/currency-provider-coinmarketcap - CoinMarketCap crypto-rates provider for @suaveplan/currency — sibling of @suaveplan/currency-providers. Authenticates via X-CMC_PRO_API_KEY header against the /cryptocurrency/quotes/latest endpoint. Universal (no node:/bun:/DOM imports).

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.

<!-- begin:auto-docs -->
## Documentation tree

- [coinmarketcap](./src/coinmarketcap/coinmarketcap.md) — `CoinMarketCapProvider` is the `@suaveplan/currency-providers` sibling that fetches cryptocurrency spot prices from the…
  - [coinmarketcap](./src/coinmarketcap/coinmarketcap.md) — `CoinMarketCapProvider` is the `@suaveplan/currency-providers` sibling that fetches cryptocurrency spot prices from the…
<!-- end:auto-docs -->

## Install

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

## Quick start

```ts
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:

```ts
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`](./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.