When a customer wants to buy a specific cryptocurrency (eg, "BTC") they may express their intention in two different ways:

  1. By specifying the amount of desired cryptocurrency they wants to buy
  2. By specifying the amount of fiat currency they wants to spend

The combination of asset amount and settlement amount allows to support both use cases for your customers.

  • If your customer is trying to buy a specific amount of such cryptocurrency, then the asset amount value should specify how much of that cryptocurrency your customer is willing to buy, while the settlement amount value should not be sent as seen in the following example.
{
    "reference_id": "Abc123ed-F456Gh",
    "operation": "buy",
    "asset": {
        "currency": "BTC",
        "amount": "1"
    }
}
  • On the other hand, if your customer wants to spend a specific amount of fiat currency that they hold with your bank and receive the resulting amount of the specified cryptocurrency, then the settlement amount param should specify how much in settlement currency (as configured for your account at Lirium) your customer wants to spend, while not sending the asset amount, again as seen in the examples.
{
    "reference_id": "Abc123ed-F456Gh",
    "operation": "buy",
    "asset": {
        "currency": "BTC"
    },
    "buy": {
        "settlement": {
            "currency": "USD"
            "amount": "10000"
        }
    }
}

Please note that the asset currency value always identifies the asset that your customer is trying to buy (eg. BTC)

🚧

Local Currency vs Settlement Currency

The settlement amount value always expresses an amount in the settlement currency that was setup for your bank and Lirium to settle funds (typically USD, EUR or GBP).

In the case where your customers hold with your Bank accounts a currency that is different from your settlement currency with Lirium (for example, you are a local bank in Australia and your customers hold AUD with you, while you settle with Lirium in USD) and you still want to support the use case for your customers to specify an amount of local currency they want to spend in buying cryptocurrency, you first need to convert the desired amount of AUD to USD at your own fx rate and then use the resulting USD amount as settlement amount for the transaction.