# currencyx

`currencyx` contains OpenMeter's shared currency primitives. It keeps fiat
behavior compatible with GOBL/ISO currency definitions while allowing product
and ledger code to pass configured custom currencies through the same
`Currency` interface.

## Fiat Currency

Use `Code` directly for fiat currencies. Fiat precision comes from the GOBL
currency definition and fiat rounding remains half-away-from-zero.

```go
calculator, err := currencyx.Code("USD").Calculator()
if err != nil {
    return err
}

amount := calculator.RoundToPrecision(alpacadecimal.RequireFromString("1.235"))
// amount == 1.24
```

## Custom Currency

Use `NewCustomCurrency` when the currency is not a known fiat code. Custom
currencies carry explicit precision and default to bankers rounding
(half-even). Use `NewCustomCurrencyWithRounding` to opt into half-away-from-zero.

```go
credits, err := currencyx.NewCustomCurrency(currencyx.Code("CREDITS"), 6)
if err != nil {
    return err
}

calculator, err := currencyx.NewCalculator(credits)
if err != nil {
    return err
}

amount := calculator.RoundToPrecision(alpacadecimal.RequireFromString("1.2345678"))
// amount == 1.234568
```

## Allocation

Allocation helpers use the calculator's precision and distribute residual units
with a deterministic largest-remainder method. Provide a `CompareKey` function
when equal remainders need a stable domain-specific tie-breaker.