Assets & Currency conversion

Learn how to work with multi-asset ledgers and currency conversions in Formance

The Formance ledger is a multi-asset ledger, meaning that multiple assets can be held within a single account balance natively. There are multiple ways to use the ledger in a multi-asset context — this page will cover the different strategies and best practices you can adopt for your transactions and accounts.

Overview

The key points that will guide your implementation are the type of funding and atomicity of the conversion, leading to the following typical scenarios:

	Single-stage	Multi-stages
Funded	Trade against fund account	Trade against fund + swap account
Non-funded	Trade against world	Trade against world + swap account

Funded vs non-funded

The first thing to consider is whether you want the conversion to be funded or not, which is in simpler terms, simply the difference between conversion and exchange.

Non-funded conversion

When you’re exchanging currency A for currency B, the latter needs to come from somewhere. If you’re trading against the @world account, you’re effectively introducing new units of B in an unbounded way into the ledger - which is what we refer to as a non-funded conversion. It is the simplest way to perform a conversion, albeit lacking more fine grained control over the amount of currency B you’re introducing into the ledger.

Funded exchange

The other way to perform a conversion is to trade against a funding account that you control, and you can ensure that the amount of currency B you’re trading is limited by the amount of currency B you previously introduced in the ledger in a separate process, which is what we refer to as a funded conversion.

An example case where a funded conversion is preferable could be a BTC buying platform. In this example, users acquire BTC from you and you will enable them to hold both BTC and USD in their accounts, letting them exchange their USD for BTC. In this case, the total amount of BTC held by your users should be limited by the amount of BTC you actually own in your reserves. By using a funded conversion and sourcing BTC granted to users from a previously provisioned account in the ledger, you can ensure that you are not accidentally creating BTC out of thin air.

Single-phase vs multi-stages

The other thing to consider is whether you want to perform the asset conversion in a single step, or in multiple stages. In the case of a single step conversion, you will be performing the conversion in a single atomic transaction posted to the ledger. This is the simplest way to perform a conversion, but it is not always possible and assumes that the desired asset is already available for exchange.

A typical good case for multi-stage conversion, is a conversion that involves the intervention of different parties or a delay in the conversion process. For example, if you enable your users to trade some USD for AAPL, and you are using a broker behind the scenes for the acquiring of AAPL. In this scenario, the best practice is to use a swap account as described below:

In this example:

1. The first step (in blue) represents the user placing some USD in the swap account.
2. The second step (in magenta) represents a step where the logic of acquiring the AAPL would be happening in your backend, with them eventually being sent to the swap account in exchange for its whole balance of USD.
3. Finally, the third step (in orange) is the user exchanging the AAPL acquired by the broker for AAPL in their account.

Each of these steps can be performed in a separate ledger transaction, as the swap account is being used as a temporary holding location for the exchange process.

Additional best practices

Exchange rate

For auditability purposes, it is recommended that you store the exchange rate used for the conversion in the transaction metadata. This will enable you to audit the conversion process and ensure that the conversion rate used is the one you intended to use.