Quick Start

This page gets one small application model running end-to-end: an Orbit Treasury that tracks USDC, USD, and SOL.

Install the gem

gem "amounts"

bundle install

For Rails integration later:

require "amount/active_record"

Register the types you care about

require "amount"

Amount.register :USDC,
  decimals: 6,
  display_symbol: "$",
  display_position: :prefix,
  ui_decimals: 2

Amount.register :USD,
  decimals: 2,
  display_symbol: "$",
  display_position: :prefix,
  ui_decimals: 2

Amount.register :SOL,
  decimals: 9,
  display_symbol: "SOL",
  display_position: :suffix,
  ui_decimals: 4

Amount.register_default_rate :USD, :USDC, "1"

Amount.register_default_rate :USDC, :USD, "1"

That does four things:

1. Defines the storage precision for each type
2. Defines how each type should display by default
3. Generates convenience constructors like Amount.usdc(...)
4. Registers directional conversion rules for cross-type arithmetic

Construct values

treasury_buffer = Amount.usdc("150000.00")
invoice = Amount.new("2500.00", :USD)
gas_budget = Amount.sol("18.75")

Construction defaults are intentional:

• Integer means atomic units
• String means UI value
• Float, BigDecimal, and Rational mean UI value
• from: overrides inference explicitly

Do math safely

(treasury_buffer - invoice).ui
# => "$147500.00"

treasury_buffer > invoice
# => true

That works because the right-hand side can be converted from USD into USDC using the registered directional rate.

Without a rate:

Amount.usdc("10") + Amount.sol("1")
# => raises Amount::TypeMismatch

Serialize and parse

For client-facing compact input:

Amount.parse("USDC|1.50")
Amount.parse("v1:USDC|1.50")

For structured persistence or wire payloads:

payload = Amount.usdc("1.50").to_h
# => { v: 1, atomic: "1500000", symbol: "USDC" }

Amount.load(payload)

Lock the registry at boot

If your application configures the registry in an initializer, lock it once setup is complete:

Amount.registry.lock!

That prevents accidental runtime mutation such as late registration or clearing the shared registry.

Next steps

• Read Atomic vs UI to understand the storage model
• Read Rates and Conversion before relying on cross-type math
• Read Rails Overview if you want has_amount and t.amount