92 lines
3.6 KiB
Markdown
92 lines
3.6 KiB
Markdown
# @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.
|
|
|