Skip to content

amountinator.md

Latest commit

 

History

History
160 lines (119 loc) · 5.94 KB

amountinator.md

File metadata and controls

160 lines (119 loc) · 5.94 KB
Raw
id pkg-amountinator
title @bsv/amountinator
kind package
domain helpers
version 2.1.8
source_repo bsv-blockchain/ts-stack
last_updated 2026-08-26
last_verified 2026-08-26
review_cadence_days 30
npm https://www.npmjs.com/package/@bsv/amountinator
repo https://github.com/bsv-blockchain/ts-stack/tree/main/packages/helpers/amountinator
status stable
tags
helpers
amounts
satoshis

@bsv/amountinator

This source candidate declares SDK peer ^2.1.6 || ^3.0.0 || ^4.0.0. SDK3 remains a coordinated proposal; see the qualification and migration limits before adopting it.

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

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

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() // "$" 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

Reference