88 lines
4.0 KiB
Markdown
88 lines
4.0 KiB
Markdown
# @suaveplan/currency-provider-kraken - Universal Kraken public-ticker rate provider for @suaveplan/currency. Wraps Kraken's free no-API-key /0/public/Ticker endpoint into a CurrencyProvider with the slim core's shared httpRequest helper, typed CurrencyProviderError (HTTP_ERROR / PARSE_ERROR / UPSTREAM_ERROR / UNKNOWN_CURRENCY), and the 12-symbol BTC/ETH/SOL/USDT/DOT/ADA/LINK/AVAX/ATOM/LTC/DOGE/XRP coverage matched against Kraken's non-standard pair names.
|
|
|
|
Universal Kraken public-ticker rate provider for `@suaveplan/currency`.
|
|
Wraps Kraken's free, no-API-key `/0/public/Ticker` endpoint into a
|
|
`CurrencyProvider` so a `CurrencyConverter` can price the major crypto
|
|
pairs against USD without callers ever seeing Kraken's non-standard pair
|
|
names (`XXBTZUSD`, `XETHZUSD`, `XDGUSD`, …).
|
|
|
|
Concrete sibling of the slim `@suaveplan/currency-providers` core — uses
|
|
the shared `httpRequest()` helper, raises the shared `CurrencyProviderError`
|
|
codes (`HTTP_ERROR`, `PARSE_ERROR`, `UPSTREAM_ERROR`, `UNKNOWN_CURRENCY`),
|
|
and accepts the shared `NoKeyConfig` (optional `baseUrl`, optional injectable
|
|
`FetchLike`) plus an optional `extraSymbols` map for caller-supplied
|
|
extensions.
|
|
|
|
<!-- begin:auto-docs -->
|
|
## Documentation tree
|
|
|
|
- [provider](./src/provider/provider.md) — `KrakenProvider` is the universal `CurrencyProvider` implementation for Kraken's free `/0/public/Ticker` endpoint.…
|
|
- [provider](./src/provider/provider.md) — `KrakenProvider` is the universal `CurrencyProvider` implementation for Kraken's free `/0/public/Ticker` endpoint.…
|
|
- [symbols](./src/symbols/symbols.md) — The Kraken public ticker addresses pairs by non-standard names — `XXBTZUSD` for BTC/USD, `XETHZUSD` for ETH/USD, `XDGUS…
|
|
- [symbols](./src/symbols/symbols.md) — The Kraken public ticker addresses pairs by non-standard names — `XXBTZUSD` for BTC/USD, `XETHZUSD` for ETH/USD, `XDGUS…
|
|
<!-- end:auto-docs -->
|
|
|
|
## Install
|
|
|
|
```bash
|
|
bun add @suaveplan/currency-provider-kraken @suaveplan/currency @suaveplan/currency-providers
|
|
```
|
|
|
|
## Quick start
|
|
|
|
```ts
|
|
import { CurrencyConverter } from "@suaveplan/currency";
|
|
import { KrakenProvider } from "@suaveplan/currency-provider-kraken";
|
|
|
|
const provider = new KrakenProvider();
|
|
const converter = new CurrencyConverter({ provider });
|
|
|
|
const btcPerUsd = await converter.getRate("USD", "BTC"); // e.g. 0.0000149
|
|
const ethPerUsd = await converter.getRate("USD", "ETH"); // e.g. 0.0002857
|
|
```
|
|
|
|
Or register through the slim core's registry:
|
|
|
|
```ts
|
|
import { CurrencyProviderRegistry } from "@suaveplan/currency-providers";
|
|
import { KrakenProvider } from "@suaveplan/currency-provider-kraken";
|
|
|
|
const registry = new CurrencyProviderRegistry();
|
|
registry.register(new KrakenProvider());
|
|
|
|
const provider = registry.get("kraken");
|
|
```
|
|
|
|
## Features
|
|
|
|
- No API key — Kraken's public endpoint is free (per-IP rate-limited)
|
|
- 12 high-volume symbols out of the box: BTC, ETH, SOL, USDT, DOT, ADA,
|
|
LINK, AVAX, ATOM, LTC, DOGE, XRP
|
|
- Optional `extraSymbols` for newly-listed pairs without forking
|
|
- Reciprocal-of-USD rate model — `rates[X] = 1 / lastTradeClosedPriceUsd`
|
|
- Single-round-trip batch fetch (Kraken supports a comma-separated `pair=`
|
|
query)
|
|
- Uses the slim core's `httpRequest()` so HTTP errors, timeouts, and caller
|
|
`AbortSignal` propagation are uniform across providers
|
|
- Maps wire-level failure modes to typed `CurrencyProviderError`:
|
|
`HTTP_ERROR`, `UPSTREAM_ERROR`, `PARSE_ERROR`, `UNKNOWN_CURRENCY`
|
|
- Universal — no `node:`/`bun:`/DOM imports; runs unchanged under
|
|
Node ≥ 18, Bun, modern browsers (subject to Kraken's CORS policy), Web
|
|
Workers
|
|
|
|
## Modules
|
|
|
|
- [`src/provider/provider.md`](./src/provider/provider.md) —
|
|
`KrakenProvider` class, `KrakenProviderConfig`, `DEFAULT_KRAKEN_BASE_URL`
|
|
- [`src/symbols/symbols.md`](./src/symbols/symbols.md) —
|
|
`KRAKEN_SYMBOL_MAP`, `KRAKEN_PAIR_TO_SYMBOL`, `mergeSymbolMap`
|
|
|
|
## Status
|
|
|
|
`0.1.0` (pre-graduation). native sibling of the slim
|
|
`@suaveplan/currency-providers` core landed by
|
|
the design document. See
|
|
the design proposal for
|
|
the migration parity table and source mapping.
|
|
|