The Order resource represents an operation that affects a customer's cryptocurrency balance at Lirium.

The Order resource represents an operation that affects a customer's cryptocurrency balance at Lirium.

📘

Placing an Order requires two steps

Step 1 - Initiation

The Banking Partner (BP) submits their intention for placing an order on behalf of one of their customers.
Based on the details provided by BP, Lirium calculates and returns relevant information for the requested order, such as a guaranteed price for any cryptocurrency buy/sell operation or the mining fees that apply when sending crypto to the blockchain.
The response also includes a flag indicating whether or not a security code that has been sent by Lirium to the customer's email address is required for confirmation in the next step.

Step 2 - Confirmation

BP processes the information returned by Lirium and performs their own calculations in order to show the customer the final conditions for the requested order, such as adding their own fees and (when applicable) converting the resulting total amount from settlement currency to local currency at their own exchange rate to show the exact amount that BP will debit from their customer's account.
Provided that the customer reviewed and accepted those conditions, BP asks Customer to enter the security code (when required) and confirms the open order with Lirium by calling the Confirm Order endpoint.

🚧

Security Code

When the order requires a security code for confirmation, the code will be sent directly by Lirium to the customer's email address on file and should be collected from Customer by Banking Partners before attempting to confirm the transaction.

Please make sure that customer's email address on file is always kept up-to-date by using the Update Customer endpoint.

Order operations

Orders may be of one of the following operations:

  • buy: Used when placing an order for a Customer to buy cryptocurrencies and keep them in their Lirium custodial account.
  • sell: Used when placing an order for a Customer to sell cryptocurrencies that she holds at their Lirium custodial account.
  • swap: These orders are a direct way to go from one currency to another in one operation instead of having to manually sell one and buy the other with two orders.
  • reversal: These orders revert an exchange buy or sell operation
  • send: Used when placing an order for a Customer to send cryptocurrencies that she holds at their Lirium custodial account to the blockchain or to other Lirium customer as an offchain transfer.
  • receive: These orders are automatically generated by Lirium when a Customer receives cryptocurrencies from the blockchain into one of their cryptocurrencies receiving addresses or from other Lirium customer as an offchain transfer.
  • receive_nft: These orders are automatically generated by Lirium when a Customer receives NFTs from the blockchain into one of their cryptocurrencies receiving addresses.
  • subscribe_investment: Used when placing an order for a Customer to subscribe an investment with their cryptocurrencies held at Lirium.
  • redeem_investment: Used when placing an order for a Customer to redeem an investment and keep the resulting cryptocurrency in their Lirium custodial account.

Order states

An order, regardless of its type, may be in one of these states

  • pending: The order has been successfully initiated and is still waiting to be confirmed.
  • pending_receive: The order has been detected but is not yet confirmed.
    • Applies to receive and receive_nft operations.
  • processing: The order has been confirmed and is being processed.
  • completed: The order has been successfully processed and completed.
  • aborted: The order was cancelled before confirmation.
  • cancelled: The order was cancelled after confirmation.

🚧

Aborted orders

Orders with state aborted are orders which were initiated but not confirmed before it's expiration time. Thus, they did not affect any account balance.

These orders are considered discarded or failed attempts to create orders, and for this reason are not returned in the customer's orders collection.


Order fields

Common

Any order, independent from its operation, includes the following fields:

FieldDescriptionType / ValuesNotesExample
idLirium's unique Identification for the order.string3dfb5...
operationOrder operation.string_enumsee order operationsbuy
reference_idBanking Partner's unique Identification for the order.
Optional.
stringUp to 64 characters long.
Case sensitive
ref123-ABC
stateCurrent state of the order.string_enumsee order satescompleted
created_atCreation timestamp.timestamp2021-03-03T02:39:03.830641+00:00
last_updated_atTimestamp of the last time the data on the order was changed.timestamp2021-03-03T02:39:04.417710+00:00
submitted_atConfirmation timestamp.timestampEmpty when state is pending, pending_receive or aborted2021-03-03T02:39:04.254244+00:00
customer_idstringd3488a...
assetdictionary containing the asset affected by this order
asset.typeType of the assetstringsee asset typescurrency
asset.idId of the assetstringVaries depending on the typeBTC

Asset Types

The asset type can be one of the following:

  • currency: The asset is a currency from the customer's wallet.

    • The id field value is the currency. It is one of the partner's available_assets
  • investment: The asset is an investment token from the customer's wallet.

    • The id field value is the investment asset. It is one of the partner's available_investments
  • nft: The asset is a currency from the customer's wallet.

    • The id field value is id of the affected customer's NFT.

The currency and investment types include the following additional fields in the asset node:

FieldDescriptionType / ValuesNotesExample
operationWhether the amount in this object adds or subtracts balancestring_enumdebit|creditcredit
amountAffected balance amount. unsignedstring_decimal0.00110507
balanceResulting balance after the order was confirmed.string_decimalEmpty when state is pending, pending_receive or aborted0.00110507

Additionally, each operation on an order will add an object in a node named exactly like the operation type with exclusive information pertaining to it, referred in this doc as {operation}.

Confirmation related

All the orders that can be created with Create Order have the following fields inside the {operation} node

FieldDescriptionTypeNotes
expires_attimestamp at which the order expires if still in pending state.timestampIf the order is not confirmed before this time will be automatically aborted.
requires_confirmation_codeIndicates whether if a code supplied by the user is required in Confirm Orderboolsee Security Code

Buy / Sell

The following fields will be inside the {operation} node buy or sell

FieldDescriptionTypeNotesExample
settlementdictionary containing currency and amount charged by Lirium to the Banking Partner in connection to this Ordermoney dictionary
settlement.currencystringEUR
settlement.amountstring_decimalunsigned45
settlement.operationwhether the amount in this object adds or subtracts balancestring_enumdebit|creditdebit
referenceDictionary containing the reference amount in USDmoney dictionary
reference.currencystringalways USDUSD
reference.amountstring_decimalunsigned54.32
feesFees collected on this order.arraysee buy and sell fee
customerDictionary containing the final amount paid or received by the customermoney dictionary
customer.currencystringBRL
customer.amountstring_decimalunsigned305.1

⚠️

Reference money field

This field applies only when the Partner's settlement currency differs from USD and this feature is enabled

📘

Customer money field

When confirming a buy or sell order, the partner must provide the final currency and amount paid or received by the customer.

This field is for tracking purposes, since the partner is acting as a payment processor, Lirium should know the final amounts.

Example:

The partner settlement is in USD and a for buy order the amount to pay quoted by Lirium is USD 10, but the customer pays with a MXN account held with the partner.
The partner does the conversion and collects MXN 170.43 from the customer account as a payment.
In this case the customer currency and amount to be send in the confirmation is MXN 170.43

Buy / Sell Fee

The fee is a commission charged by the Partner, but collected by Lirium. These commissions will be paid later into the Partner's settlement balance.

⚠️

Partner commissions

The collection of the Partner's commission fees on buy and sell orders feature that requires enabling prior to usage.

The fees array contains objects with the following fields

FieldDescriptionTypeNotesExample
typeFee typestring_enumsee fee type and valuepercentage
valueValue corresponding to the typestring_decimal1.5
modeFee modestringThe only mode currently supported is collect. It means the fee is paid by the customer, being collected from the settlement account.collect
base_amountAmount used to calculate the feestringsee fee base_amount and base_operation45
base_operationOperation on base_amountstring_enumadd | deductdeduct
amountThe amount to be collected as fee44.34

Fee type and value

The fee type may be one of the following:

  • fixed: The value indicates the amount of the fee to be collected. No additional calculations needed
  • percentage: The value indicates a percentage to be calculated on the settlement amount. Eg. A value of 1 would mean 1% fee

📘

The settlement amount aways includes the fee

If the order created has a settlement of USD 100 and the fee is:

  • fixed 5: USD 5 will be collected as fee and USD 95 will be used on the buy or sell operation.
  • percentage 1: USD 0.99 will be collected as fee and USD 99.01 will be used on the buy or sell operation
    • Note that the fee is USD 0.99 because that is the 1% of USD 99.01 and by adding them we get the final amount of USD 100 .

Fee base_amount and base_operation

The base_amount and base_operation can vary depending on how the order was initiated.

For example, if the order was initiated indicating a fiat amount (ie. USD), this value will always be equal to the final settlement.amount value, then depending on the operation:

  • Buy: base_operation = deduct. The fee value is deducted from the requested fiat amount, and then the amount of crypto the customer buys is calculated.

  • Sell: base_operation = add. The fee value is added to the amount that is used to calculate how much crypto the customer must sell to get the requested fiat amount after fees.

On the other hand, if the order was initiated indicating a crypto amount, we first calculate how much fiat that amounts to, this will be the base_amount and then, depending on the operation:

  • Buy: base_operation = add. The fee value is added to the fiat amount that the customer must pay to get the requested crypto amount.

  • Sell: base_operation = deduct. The fee value is deducted from the fiat amount that the customer gets by selling the requested crypto amount.


Swap

FieldDescriptionTypeExample
currencyCurrency of the counterpart of the swapstringUSDC
amountAmount of the counterpart of the swapstring_decimal100.00131
exchange.swap_order_idIndicates the id of the counterpart order
(credit if this is debit, debit if this is credit)
stringca45aa...

Send

FieldDescriptionTypeNotesExample
feesAmount of fees chargedstring_decimal0.00000193
networkIndicates the network to sendstring_enumbitcoin | ethereum | polygon | offchainbitcoin
destinationDictionary containing destination data
destination.typeDestination typestring_enumcrypto_currency_address |lirium_customer| mastercard_aliascrypto_ currency_ address
destination.valueBlockchain address or Lirium customer idstringVaries depending on the type2MspxDtN...
destination.amountAmount to sendstring0.0001

Destination type and value

The destination type may be one of the following:

  • crypto_currency_address: The value indicates a blockchain address on the network

    • When the blockchain address belongs to a Lirium customer, the order will be processed offchain with no fees.
    • After the transaction has been broadcasted to the blockchain, a node named crypto_currency_transaction is added to the destination node with the following fields:
    FieldDescriptionTypeExample
    transaction_idThe transaction id on the blockchainstring0x123abc...
  • lirium_customer: The value indicates a Lirium customer id. Always processed offchain

    • A node named lirium_transfer is added to the destination node with the following fields:
    FieldDescriptionTypeExample
    customer_idThe customer id of the receiverstring8281c...
    order_idThe order id of the receiverstring0d490...

Receive

FieldDescriptionTypeNotesExample
feescharged fees in case they existstring0
networkIndicates the network where it was receivedstring_enumbitcoin | ethereum | polygon | offchainethereum
origindictionary containing origin data
origin.typethe origin typestring_enumblockchain_transaction | lirium_transferblockchain_ transaction
origin.valuethe originating blockchain transaction id or Lirium customer idstringVaries depending on the type0xabc123...
origin.amountthe amount receivedstring12.35615

Origin type and value

The origin type may be one of the following:

  • blockchain_transaction: The value indicates a blockchain transaction id on the network

    • A node named crypto_currency_transaction is added to the origin node with the following fields

      FieldDescriptionTypeExample
      transaction_idThe transaction id on the blockchainstring0xabc123...
  • lirium_transfer: The value indicates a Lirium send order id. Always processed offchain

    • A node named lirium_transfer is added to the destination node with the following fields:

      FieldDescriptionTypeExample
      customer_idThe customer id of the receiverstring7141b...
      order_idThe order id of the receiverstringc88e5...

Receive NFT

FieldDescriptionTypeNotes
networkIndicates the network to where it was receivedstring_enumpolygon
origindictionary containing origin data
origin.typethe origin typestring_enumblockchain_transaction

Origin type and value

The origin type may be one of the following:

  • blockchain_transaction: The value indicates a blockchain transaction id on the network

    • A node named blockchain_transaction is added to the origin node with the following fields

      FieldDescriptionTypeExample
      transaction_idThe transaction id on the blockchainstring0x123abc...

Subscribe Investment

FieldDescriptionTypeNotesExample
investmentDictionary containing investment data
investment.idId of the investment tokenstringIt is one of the partner's available_investmentsaEthUSDC
investment.amountAmount of investment tokens receivedstring_decimal1923.87862
investment.operationWhether the amount in this object adds or subtracts balancestring_enumSubscriptions are always creditcredit
investment.order_idId of the order that reflects the investment token balance operationstringac242...
rateIndicates amount of asset per investment tokenstring_decimal1.03956

Redeem Investment

FieldDescriptionTypeNotesExample
investmentDictionary containing investment data
investment.idId of the investment tokenstringOne of the investment assets previously subscribedaEthUSDC
investment.amountAmount of investment tokens redeemedstring_decimal814.761562
investment.operationWhether the amount in this object adds or subtracts balancestring_enumRedemptions are always debitdebit
investment.order_idId of the order that reflects the investment token balance operationstringb5ece...
rateIndicates amount of asset per investment tokenstring_decimal1.04325
invested_amountAmount of asset previously invested to obtain the amount of investment tokens redeemedstring_decimal846.993529
gross_amountGross amount of asset obtained by redeeming the investment tokens. Before applying fees.string_decimalinvestment.amount * rate850
earningsDifference between amount of asset obtained vs investedstring_decimalgross_amount - invested_amount3.006471
feesFees collected on this order.arraysee investment redemption fee

Investment Redemption Fee

The fees array contains objects with the following fields

FieldDescriptionTypeNotesExample
sourceSource of the feestring_enumlirium_commission | partner_commissionlirium_ commission
typeFee typestring_enumsee fee type and valuepercentage
valueValue corresponding to the typestring_decimal5
modeFee modestringThe only mode currently supported is collect. It means the fee is paid by the customer, being collected from the asset before crediting the final amount after feescollect
base_amountAmount used to calculate the feestringsee fee base_amount3.006471
base_operationOperation on base_amountstring_enumThe fee operation will always be deductdeduct
amountThe amount to be collected as fee0.15032355

Fee source

The fee souce may be one of the following:

  • lirium_commission: The fee is a commission charged by Lirium
  • partner_commission: The fee is a commission charged by the Partner, but collected by Lirium. These commissions will be paid later into the Partner's settlement balance.

⚠️

Partner commissions

The collection of the Partner's commission fees on redeem_investment orders are feature that requires enabling prior to usage.

Fee type and value

The fee type may be one of the following:

  • fixed: The value indicates the amount of the fee to be collected. No additional calculations needed
  • percentage: The value indicates a percentage to be calculated on the asset amount. Eg. A value of 1 would mean 1% fee
  • earnings_percentage: The value indicates a percentage to be calculated on the earnings amount. Eg. A value of 1 would mean 1% fee
    • It may occur that a redemption has no earnings (subscribed and redeemed with the same rate), in this case no fees will be collected.

Fee base_amount

The base_amount varies depending on the fee type:

  • earnings_percentage: This value will always be equal to redeem_investment.earnings
  • fixed | percentage: This value will always be equal to the asset.amount plus the fee amount.