skills/docs/money/finance/currency-provider-coingecko/README.md

@suaveplan/currency-provider-coingecko - Universal CoinGecko sibling for @suaveplan/currency-providers. Exposes CoinGeckoProvider (free public tier + optional Pro-tier x-cg-pro-api-key) and the getCoinGeckoId symbol lookup; routes every request through the shared httpRequest helper and raises typed CurrencyProviderError on HTTP_ERROR / PARSE_ERROR / UPSTREAM_ERROR / UNKNOWN_CURRENCY.

Universal CoinGecko sibling for @suaveplan/currency-providers. Implements the CurrencyProvider contract from @suaveplan/currency against the public /simple/price endpoint, with optional Pro-tier apiKey support attached as x-cg-pro-api-key on every outbound request. Both free and Pro tiers share the same URL shape, so upgrading is a single-field config change.

Documentation tree

• coin-ids — Owns the curated mapping from uppercase ticker symbol (BTC, ETH, …) to the opaque CoinGecko coin id (bitcoin, `et…
  • coin-ids — Owns the curated mapping from uppercase ticker symbol (BTC, ETH, …) to the opaque CoinGecko coin id (bitcoin, `et…
• coingecko — CoinGecko sibling for @suaveplan/currency-providers. Implements the CurrencyProvider contract from `@suaveplan/curr…
  • coingecko — CoinGecko sibling for @suaveplan/currency-providers. Implements the CurrencyProvider contract from `@suaveplan/curr…

Install

bun add @suaveplan/currency-provider-coingecko

Quick start

import { CurrencyConverter } from "@suaveplan/currency";
import { CurrencyProviderRegistry } from "@suaveplan/currency-providers";
import { CoinGeckoProvider } from "@suaveplan/currency-provider-coingecko";

// Free public tier — no API key required.
const free = new CoinGeckoProvider();

// Pro tier — pass apiKey; the same provider attaches x-cg-pro-api-key.
const pro = new CoinGeckoProvider({
 apiKey: process.env.COINGECKO_PRO_KEY,
 baseUrl: "https://pro-api.coingecko.com/api/v3",
});

const registry = new CurrencyProviderRegistry();
registry.register(pro);

const converter = new CurrencyConverter({
 provider: registry.get("coingecko"),
 staleDurationMs: 60_000,
});

const rates = await registry
 .get("coingecko")
 .fetchRates({ base: "USD", targets: ["BTC", "ETH"] });

Features

• CoinGeckoProvider implements CurrencyProvider — drops directly into any @suaveplan/currency converter or CurrencyProviderRegistry.
• Truly optional apiKey — free tier requires no config; Pro tier attaches x-cg-pro-api-key automatically.
• 16 curated cryptocurrencies (BTC, ETH, SOL, USDT, USDC, BNB, XRP, ADA, DOGE, DOT, AVAX, MATIC, LINK, UNI, ATOM, LTC).
• Routes every request through the shared httpRequest() helper from @suaveplan/currency-providers for abort-signal composition, per-call timeouts, and typed HTTP failures.
• Proactive UNKNOWN_CURRENCY gate — unknown options.targets reject before the HTTP call is issued.
• Typed CurrencyProviderError on every failure path: HTTP_ERROR, PARSE_ERROR, UPSTREAM_ERROR, UNKNOWN_CURRENCY.
• Universal — zero browser / Node-only APIs. Works in Node 18+, Bun, modern browsers, and Web Workers.

Modules

• src/coingecko/coingecko.md — CoinGeckoProvider class + CoinGeckoConfig type.
• src/coin-ids/coin-ids.md — COIN_IDS curated map + getCoinGeckoId(symbol) lookup.