# @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.