npmhttps://www.npmjs.com/package/@bsv/amountinatorv2.1.4API reference (TypeDoc) ↗

@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

bash

npm install @bsv/amountinator

Quick start

typescript

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

Runtime and package compatibility

The package root provides matching typed entry points for Node.js ESM and CommonJS consumers. The published tarball is checked with publint, strict @arethetypeswrong/core resolution, and clean installs that import and require both public exports. Node.js 22 or newer is supported.

Common patterns

Initialize with auto-refresh

typescript

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

Convert with auto-detection

typescript

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

typescript

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

Get preferred currency symbol

typescript

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

Convert user currency to satoshis

typescript

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

Static converter (no auto-refresh)

typescript

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

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

Reference

Loading…

Edit this page on GitHub

Quick start

typescript

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

typescript

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

typescript

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

typescript

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

typescript

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

typescript

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

typescript

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

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