85 lines
3.4 KiB
Markdown
85 lines
3.4 KiB
Markdown
# @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.
|
|
|
|
<!-- begin:auto-docs -->
|
|
## Documentation tree
|
|
|
|
- [binance](./src/binance/binance.md) — `BinanceProvider` is the Binance sibling implementation of the `CurrencyProvider` contract from `@suaveplan/currency`.…
|
|
- [binance](./src/binance/binance.md) — `BinanceProvider` is the Binance sibling implementation of the `CurrencyProvider` contract from `@suaveplan/currency`.…
|
|
<!-- end:auto-docs -->
|
|
|
|
## Install
|
|
|
|
```bash
|
|
bun add @suaveplan/currency-provider-binance @suaveplan/currency @suaveplan/currency-providers
|
|
```
|
|
|
|
## Quick start
|
|
|
|
```ts
|
|
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:
|
|
|
|
```ts
|
|
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`](./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.
|
|
|