skills/plugins/library-navigator/skills/sp-currency-provider-binance/SKILL.md

name, description

name	description
sp-currency-provider-binance	Binance public-ticker crypto-rates provider implementing the CurrencyProvider contract for @suaveplan/currency.

Binance Currency Provider for Suaveplan

Binance public-ticker crypto-rates provider that implements the CurrencyProvider contract from @suaveplan/currency on top of the slim @suaveplan/currency-providers core. Fetches from Binance's free, key-less /api/v3/ticker/price endpoint and returns inverted spot mid-prices (1 / price) ready for CurrencyConverter.

Architecture

Component	Responsibility
BinanceProvider	Main class implementing CurrencyProvider; fetches ticker data, decodes rates, and returns RateFetchResult
BINANCE_PROVIDER_NAME	Stable identifier constant ("binance") used as registry key and provider.name
BINANCE_DEFAULT_BASE_URL	Default REST base URL ("https://api.binance.com/api/v3") overridable via constructor
ensureTickerArray	Validates the upstream JSON payload is an array of { symbol: string; price: string } rows; throws UPSTREAM_ERROR on mismatch
decodeRates	Parses ticker rows, filters by base suffix (endsWith), inverts prices (1 / price), and silently skips zero/negative/non-finite prices
filterTargets	When options.targets is provided, restricts the rate map to requested currencies and throws UNKNOWN_CURRENCY for any missing target

File Structure

money/finance/currency-provider-binance/
  src/binance/binance.ts   # BinanceProvider class, constants, and internal helpers
  src/binance/index.ts     # Barrel re-exporting the binance module
  src/index.ts             # Root barrel re-exporting from binance/

Sibling packages:

• @suaveplan/currency — universal currency conversion engine (CurrencyConverter, RateCache, CurrencyProvider interface)
• @suaveplan/currency-providers — slim core providing CurrencyProviderRegistry, httpRequest, CurrencyProviderError, and shared config types (NoKeyConfig, ApiKeyConfig)
• @suaveplan/currency-provider-ecb — fiat provider sibling using the European Central Bank daily rates
• @suaveplan/currency-provider-coingecko — crypto provider sibling using CoinGecko's API

Patterns

Quick Start

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

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

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

Registry Registration

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

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

const result = await registry
    .get(BINANCE_PROVIDER_NAME)
    .fetchRates({ base: "USDT", targets: ["BTC", "ETH", "SOL"] });

Injectable Fetch for Testing or Proxies

import type { FetchLike } from "@suaveplan/types";

const proxiedFetch: FetchLike = async (url, init) => {
    return await fetch(`https://proxy.example.com/${String(url)}`, init);
};

const binance = new BinanceProvider({
    fetch: proxiedFetch,
    baseUrl: "https://api.binance.com/api/v3",
    timeoutMs: 8_000,
});

Custom Base Suffix

const provider = new BinanceProvider();

// Fetch EUR-quoted pairs instead of the default USDT
const result = await provider.fetchRates({ base: "EUR" });
// result.rates.BTC === 1 / 62000 (from BTC/EUR ticker)

Constraints

• supportsCrypto === true, supportsFiat === false — this provider only covers crypto assets listed on Binance spot markets
• No API key required; the provider uses Binance's public /api/v3/ticker/price endpoint
• Rates are stored as 1 / price so the result answers "1 unit of base = N units of asset"
• Zero, negative, and non-finite ticker prices are silently skipped (not surfaced as errors) to handle delisted-but-published symbols
• When options.targets is provided, any target absent from the upstream listing raises UNKNOWN_CURRENCY instead of being omitted
• Symbols whose entire name equals the base suffix (e.g. USDTUSDT) are defensively skipped to avoid empty-string rate keys
• Transport errors (non-2xx) are raised as CurrencyProviderError with code HTTP_ERROR by the shared httpRequest helper

Checklist

1. Import from @suaveplan/currency-provider-binance for the root barrel, or @suaveplan/currency-provider-binance/binance/binance for the subpath export
2. Pass an injectable FetchLike in the constructor when testing or proxying
3. Use targets to restrict the returned rate map and surface missing pairs as typed errors
4. Remember prices are inverted (1 / price) — expect small numbers for expensive assets
5. Verify provider.supportsFiat is false before using this provider for fiat conversions