@bsv/amountinator

Satoshi/BSV/USD and multi-fiat currency conversion with exchange rate caching and wallet settings integration — convert between crypto (SATS, BSV) and 15+ fiat currencies with auto-refresh.

Install

npm install @bsv/amountinator

Quick start

import { CurrencyConverter } from '@bsv/amountinator'

const converter = new CurrencyConverter()  // 5-min auto-refresh
await converter.initialize()

// Auto-detect input currency, convert to user's preference
const formatted = await converter.convertAmount('5000')
console.log(formatted.formattedAmount) // e.g. "5,000 satoshis"
console.log(formatted.hoverText)       // present for very small displayed values

// Cleanup (stop auto-refresh)
converter.dispose()

What it provides

• CurrencyConverter — Main class for conversions with auto-refresh
• Multi-currency support — 15+ fiat currencies (USD, GBP, EUR, JPY, CNY, INR, etc.)
• Crypto conversion — SATS ↔ BSV ↔ Fiat via USD
• Exchange rate caching — Configurable auto-refresh interval (default: 5 min)
• Auto-detection — Parse "100" (SATS), "0.1" (BSV), or "10 USD" from user input
• Settings integration — Read/write preferred currency to wallet settings
• Formatted output — Display string with symbol, decimals, and hover text
• Satoshi rounding — convertToSatoshis() rounds up to ensure sufficient payment

Common patterns

Initialize with auto-refresh

const converter = new CurrencyConverter()  // 5-min interval
await converter.initialize()

Convert with auto-detection

const formatted = await converter.convertAmount('5000')  // "5000" or "0.1" or "10 USD"
console.log(formatted.formattedAmount) // formatted for display
console.log(formatted.hoverText)       // optional full value for tiny amounts

Convert between specific currencies

const usdAmount = converter.convertCurrency(0.1, 'BSV', 'USD')  // 6.2 (if rate = 62)

Get preferred currency symbol

const symbol = converter.getCurrencySymbol()  // "
quot; if USD, "€" if EUR

Convert user currency to satoshis

const sats = await converter.convertToSatoshis(10)  // If preferred = 'USD', USD→SATS
console.log(sats)  // e.g. 1610000 (rounded up)

Static converter (no auto-refresh)

const staticConverter = new CurrencyConverter(0)  // refreshInterval = 0
await staticConverter.initialize()
const amount = await staticConverter.convertAmount('100')
// Rates will not auto-update

Key concepts

• Exchange Rates — Two-tier: USD/BSV (external service), then USD↔fiat (15+ currencies)
• Preferred Currency — User's chosen display currency; persisted in wallet settings
• Auto-Refresh — Rates updated on interval; caches within window to avoid redundant fetches
• Currency Detection — convertAmount() auto-detects if input is SATS, BSV, or fiat (via suffix)
• Wallet Settings Integration — Reads/writes preferred currency from wallet manager
• Fiat Conversion — Single path: SATS ↔ USD ↔ Fiat (via usdPerBsv and fiatPerUsd)
• Rounding — convertToSatoshis() rounds up (Math.ceil) for payment safety

When to use this

• Displaying satoshi amounts to users in their preferred currency
• Parsing user input for payment amounts with auto-detection
• Multi-currency applications with live exchange rates
• Formatting amounts for UI display with hover details
• Converting between SATS, BSV, and fiat in wallets or faucets

When NOT to use this

• For mathematical operations on amounts — use conversions separately
• If you only use satoshis internally — skip conversion entirely
• For financial calculations requiring precision — use BigDecimal library
• For static amounts without live rates — skip auto-refresh

Spec conformance

• Currency codes — ISO 4217 (e.g., USD, GBP, EUR)
• Satoshi/BSV units — 1 BSV = 100,000,000 SATS
• Fiat conversion — Generic multi-currency (no BRC reference)

Common pitfalls

• Rates not available — convertCurrency() throws if usdPerBsv <= 0; call initialize() first
• Preferred currency not set — If settings fetch fails, defaults to 'SATS'
• Auto-refresh timer not stopped — Always call dispose() before component unmount
• String parsing ambiguity — "100.5" is parsed as BSV, "100" as SATS (heuristic: decimal = BSV)
• Rounding behavior — convertToSatoshis() always rounds UP; use convertCurrency() for exact values

Related packages

• @bsv/simple — Wallet with payment operations
• @bsv/fund-wallet — Faucet that may display amounts
• @bsv/sdk — Transaction building with satoshis

Reference

• API reference (TypeDoc)
• Source on GitHub
• npm