A lightweight and reliable library for representing and working with monetary values in .NET, based on ISO 4217 currency definitions.

✨ Features

• Strongly-typed monetary values
• Full support for ISO 4217 currencies
• Safe arithmetic operations (prevents mixing currencies)
• Built-in rounding (major and minor units)
• Value-type (struct) for performance and immutability
• Designed for financial and business applications

🚀 Quick Start

Install NuGet package

dotnet add package NMoney

Write code

usingNMoney;usingIso4217List=NMoney.Iso4217.CurrencySet;varprice=Iso4217List.USD.Money(10m);varquantity=3;vartotal=price*quantity;Console.WriteLine(total);// 30 USD

💰 Core Concepts

Money

Money is a value type that represents a monetary amount.

It consists of:

• A decimal amount
• A currency (ICurrency)

Key behaviors

• Immutable
• Supports arithmetic operations
• Throws an exception when mixing different currencies

Currency

ICurrency represents a currency and provides:

• Name (e.g. "US Dollar")
• ISO 4217 code (e.g. "USD")
• Number of decimal places for minor units (e.g. 2 for cents)
• Currency symbol (e.g. "$")

Currency Sets

CurrencySet represents a collection of currencies used for:

• list of currencies used in the application
• serialization and deserialization

usingNMoney;usingIso4217List=NMoney.Iso4217.CurrencySet;ICurrencySetactualSet=newCurrencySet([Iso4217List.CNY,Iso4217List.RUB,Iso4217List.INR,newCurrency("BTC",0.01m,"₿")]);Console.WriteLine(actualSet.TryParse("CNY"));// Yuan Renminbi

🌍 ISO 4217

Currency definitions are based on the official ISO 4217 standard.

Updates are sourced from:

• https://www.iso.org/iso-4217-currency-codes.html
• https://www.six-group.com/dam/download/financial-information/data-center/iso-currrency/lists/list-one.xml

The XML list is used to generate currency definitions in C#.

Iso4217.CurrencySet provides:

• All active ISO 4217 currencies
• Obsolete currencies (where applicable)

usingNMoney;varallIso4217Set=NMoney.Iso4217.CurrencySet.Instance;Console.WriteLine(allIso4217Set.TryParse("AUD"));//Australian Dollar

🔢 Operations

Arithmetic

varusd=NMoney.Iso4217.CurrencySet.USD;varusd10=usd.Money(10m);varusd15=usd.Money(15m);varsum=usd10+usd15;// 25 USDvardiff=usd15-usd10;// 5 USDvarscaled=usd10*2;// 20 USDvardivided=usd15/3;// 5 USD

Currency safety

varusd=NMoney.Iso4217.CurrencySet.USD.Money(10m);vareur=NMoney.Iso4217.CurrencySet.EUR.Money(10m);varinvalid=usd+eur;// throws InvalidOperationException

Comparison

varusd=NMoney.Iso4217.CurrencySet.USD;varusd10=usd.Money(10m);varusd15=usd.Money(15m);usd10==usd15;// falseusd10<usd15;// trueusd10==CurrencySet.EUR.Money(10m);// falseusd10>CurrencySet.EUR.Money(10m);// throws InvalidOperationException

Aggregation

varusd=NMoney.Iso4217.CurrencySet.USD;vartotal=Money.Zero;total+=usd.Money(10m);total+=usd.Money(15m);// total = 25 USD

Money.Zero represents a neutral monetary value used as a starting point for aggregations.

When combined with another Money value, it adopts that value’s currency.

Rounding

varvalue=NMoney.Iso4217.CurrencySet.USD.Money(20.953m);value.CeilingMajorUnit();// 21 USDvalue.FloorMajorUnit();// 20 USDvalue.CeilingMinorUnit();// 20.96 USDvalue.FloorMinorUnit();// 20.95 USD

🧩 Design Principles

• Correctness over convenience — prevents invalid monetary operations
• Explicit currency handling — no implicit conversions
• Precision — uses decimal for financial accuracy
• Immutability — safe for concurrent and functional scenarios

📦 Serialization

• BSON support: see NMoney.Bson