80 lines
3.5 KiB
Markdown
80 lines
3.5 KiB
Markdown
# @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`](../currency-providers/README.md). 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.
|
|
|
|
<!-- begin:auto-docs -->
|
|
## Documentation tree
|
|
|
|
- [coin-ids](./src/coin-ids/coin-ids.md) — Owns the curated mapping from uppercase ticker symbol (`BTC`, `ETH`, …) to the opaque CoinGecko coin id (`bitcoin`, `et…
|
|
- [coin-ids](./src/coin-ids/coin-ids.md) — Owns the curated mapping from uppercase ticker symbol (`BTC`, `ETH`, …) to the opaque CoinGecko coin id (`bitcoin`, `et…
|
|
- [coingecko](./src/coingecko/coingecko.md) — CoinGecko sibling for `@suaveplan/currency-providers`. Implements the `CurrencyProvider` contract from `@suaveplan/curr…
|
|
- [coingecko](./src/coingecko/coingecko.md) — CoinGecko sibling for `@suaveplan/currency-providers`. Implements the `CurrencyProvider` contract from `@suaveplan/curr…
|
|
<!-- end:auto-docs -->
|
|
|
|
## Install
|
|
|
|
```bash
|
|
bun add @suaveplan/currency-provider-coingecko
|
|
```
|
|
|
|
## Quick start
|
|
|
|
```ts
|
|
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`](./src/coingecko/coingecko.md) —
|
|
`CoinGeckoProvider` class + `CoinGeckoConfig` type.
|
|
- [`src/coin-ids/coin-ids.md`](./src/coin-ids/coin-ids.md) — `COIN_IDS`
|
|
curated map + `getCoinGeckoId(symbol)` lookup.
|
|
|