@suaveplan/currency-provider-binance - Universal Binance public-ticker crypto-rates provider for @suaveplan/currency. Sibling provider package: implements the CurrencyProvider contract from @suaveplan/currency on top of the slim @suaveplan/currency-providers core (httpRequest, defineCurrencyProvider, CurrencyProviderError, NoKeyConfig). No API key required.

Binance public-ticker crypto-rates provider for @suaveplan/currency. Sibling package in the foundation-with-sibling-plugins shape: implements the CurrencyProvider contract on top of the slim @suaveplan/currency-providers core (httpRequest, CurrencyProviderError, NoKeyConfig). Universal — runs unchanged under Node 18+, Bun, modern browsers, and Web Workers. No API key required.

Documentation tree

binance — BinanceProvider is the Binance sibling implementation of the CurrencyProvider contract from @suaveplan/currency.…
- binance — BinanceProvider is the Binance sibling implementation of the CurrencyProvider contract from @suaveplan/currency.…

Install

bun add @suaveplan/currency-provider-binance @suaveplan/currency @suaveplan/currency-providers

Quick start

import { CurrencyConverter } from "@suaveplan/currency";
import { CurrencyProviderRegistry } from "@suaveplan/currency-providers";
import { BinanceProvider } from "@suaveplan/currency-provider-binance";

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

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

const rate = await converter.getRate("USDT", "BTC");

Direct instantiation without the registry works exactly the same:

const converter = new CurrencyConverter({
    provider: new BinanceProvider(),
});

Features

Public Binance spot ticker endpoint (/api/v3/ticker/price) — free, no API key, no signature, no OAuth
Default base USDT; any suffix-style base supported by Binance works (EUR, BTC, ETH, etc.) by passing base to fetchRates
Optional targets filter raises typed UNKNOWN_CURRENCY for any target absent from the upstream listing — surfaces missing pairs eagerly rather than silently dropping them
Sanitised pricing: zero, negative, and non-finite ticker prices are skipped (delisted-but-published symbols stay out of the cache)
Rate inversion: every rate stored as 1 / price so the cache answers "1 unit of base = N units of crypto"
Injectable FetchLike for tests, proxies, and edge-runtime adapters; optional timeoutMs flows through to the shared httpRequest helper
Typed errors via CurrencyProviderError carrying one of HTTP_ERROR, PARSE_ERROR, UPSTREAM_ERROR, UNKNOWN_CURRENCY — no plain Error ever escapes
Universal; explicit named barrel; one subpath export beyond the root; 100/100/100/100 istanbul coverage

Modules

src/binance/binance.md — BinanceProvider class, BINANCE_PROVIDER_NAME, BINANCE_DEFAULT_BASE_URL

Status

0.1.0 (pre-graduation). Follow-up to the 2026-05-17 slim refactor of @suaveplan/currency-providers — see the design proposal for the per-package change record and the design document for the cross-cutting sibling-shape architecture.

3.4 KiB Raw Blame History