Initial Commit

packages/money/finance/currency-provider-binance/README.md

@@ -0,0 +1,84 @@
+# @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.
+