suaveplan/packages/money/finance/currency-provider-cryptocompare/README.md

@suaveplan/currency-provider-cryptocompare - Universal CryptoCompare crypto-rates provider for @suaveplan/currency. Sibling provider package on the slim @suaveplan/currency-providers core (httpRequest, defineCurrencyProvider, CurrencyProviderError, NoKeyConfig). Optional API key — free tier works keyless; key boosts the rate limit and is sent via authorization: Apikey <key> header.

Universal CryptoCompare crypto-rates provider for @suaveplan/currency. Sibling provider package on top of the slim @suaveplan/currency-providers core (httpRequest, CurrencyProviderError, NoKeyConfig). Optional API key — CryptoCompare's free tier works fully keyless; supplying a key boosts the upstream rate limit and is sent on every request via the authorization: Apikey <key> header.

Documentation tree

• cryptocompare — CryptoCompareProvider implements the CurrencyProvider contract from @suaveplan/currency on top of CryptoCompare's…
  • cryptocompare — CryptoCompareProvider implements the CurrencyProvider contract from @suaveplan/currency on top of CryptoCompare's…

Install

bun add @suaveplan/currency-provider-cryptocompare \
       @suaveplan/currency \
       @suaveplan/currency-providers

Quick start

import { CurrencyConverter } from "@suaveplan/currency";
import { CryptoCompareProvider } from "@suaveplan/currency-provider-cryptocompare";

const provider = new CryptoCompareProvider({
    apiKey: process.env.CRYPTOCOMPARE_API_KEY, // optional
});

const converter = new CurrencyConverter({
    provider,
    staleDurationMs: 60_000,
});

const conversion = await converter.convert(amount, "BTC");

Or register through the slim-core registry:

import { CurrencyProviderRegistry } from "@suaveplan/currency-providers";
import { CryptoCompareProvider } from "@suaveplan/currency-provider-cryptocompare";

const registry = new CurrencyProviderRegistry();
registry.register(new CryptoCompareProvider());
const provider = registry.get("cryptocompare");

Modules

• cryptocompare/cryptocompare — CryptoCompareProvider class, CryptoCompareConfig interface, error mapping for HTTP_ERROR / PARSE_ERROR / UPSTREAM_ERROR / UNKNOWN_CURRENCY.

Errors

Every failure path raises CurrencyProviderError from the slim core:

Code	Raised when
CURRENCY_PROVIDER.HTTP_ERROR	Non-2xx HTTP response (shared httpRequest)
CURRENCY_PROVIDER.PARSE_ERROR	Body not valid JSON, or payload not a JSON object
CURRENCY_PROVIDER.UPSTREAM_ERROR	Payload carries Response: "Error"
CURRENCY_PROVIDER.UNKNOWN_CURRENCY	No requested symbol produced a finite positive quote

Dispatch on error.code, not the message string. The instance also carries providerName: "cryptocompare", optional status (for HTTP_ERROR), and optional upstreamMessage (for UPSTREAM_ERROR).