Overview

You can use Ledgers to record user balances no matter what currency your users transact in.

Each ledger object can record transactions and balances in a single currency, which you can define upon creating the ledger. If your application uses multiple different currencies, you can use multiple ledgers to track user balances, one for each currency.

Using a predefined currency

When creating a ledger, you can specify the currency of the ledger using the currency field. This field can accept any ISO-4217 currency code.

For example, I can create a ledger tracking my user balances in dollars:

curl --request POST \
     --url https://app.moderntreasury.com/api/ledgers \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --data '
{
     "name": "User balances",
     "currency": "USD"
}
'

All ledger accounts and ledger transactions I create in this ledger will automatically be denominated in dollars.

When I create ledger transactions in this ledger, I need to specify the amount on ledger entries in the smallest unit of my currency. In the case of dollars, this smallest unit is cents. A ledger entry with an amount of 1000 would represent $10.00.

Using a custom currency

Many applications need to immutably record double-entry transactions in currencies not supported by ISO-4217, like cryptocurrencies. Ledgers can record transactions in any custom currency including user credits, rewards points, air miles, or cryptocurrencies.

To create a ledger with a custom currency, you can use a custom currency value and specify a currency_exponent when creating a ledger object.

For example, Ether (the cryptocurrency that powers the Ethereum network) has a smallest denomination of 1*10^-18 Ether. You can create a new ledger with a custom value for currency and a currency_exponent of 18.

curl --request POST \
     --url https://app.moderntreasury.com/api/ledgers \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --data '
{
     "name": "Ether balances",
     "currency": "ETH",
     "currency_exponent": 18
}
'

Any subsequent entries written to this ledger can now be denominated in Ether's smallest unit. A ledger entry with an amount of 3000000000000000000 would be recorded as 3 Ether.