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.
  • send: Used when placing an order for a Customer to send cryptocurrencies that she holds at their Lirium custodial account to the blockchain.
  • receive: These orders are automatically generated by Lirium when a Customer receives cryptocurrencies from the blockchain into one of their cryptocurrencies receiving addresses.
  • reversal: These orders revert an exchange operation (buy or sell).
  • 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.

Order states

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

  • pending: Order has been successfully Initiated and is still waiting to be confirmed.
  • processing: Order has been confirmed and is being processed.
  • completed: Order has been successfully processed and completed.
  • aborted: Order was cancelled before confirmation.
  • cancelled: Order was cancelled after confirmation.

🚧

Aborted orders

Orders with state aborted are orders that were initiated but not confirmed before its expiration time. Thus, they did not affect any account.

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 object fields

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

FieldDescriptionType / ValuesNotes
idLirium's unique Identification for the order.string
operationOrder operation.string enumbuy/sell/send/receive
reference_idBanking Partner's unique Identification for the order.
Optional.
stringUp to 64 characters long.
Case sensitive
stateCurrent state of the order.string enumpending/processing/completed/aborted/cancelled
created_atCreation timestamp.timestamp
last_updated_atTimestamp of the last time the data on the order was changed.timestamp
submitted_atConfirmation timestamp.timestampEmpty when state is pending or aborted
customer_idstring
asset.currencyAffected balance currencystringBTC/ETH/etc
asset.amountAffected balance amount. unsignedstring*eg. 0.00230000
asset.operationWhether the amount in this object adds or subtracts balancestring enumdebit/credit

Additionally, each operation on an order will add a dictionary in a json node named exactly like the operation type with exclusive information pertaining to it.

See the following sections for examples, but some of the fields in the operation node include

FieldDescriptionTypeNotesApplies to
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.buy / sell / send
settlementdictionary containing currency and amount charged by Lirium to the Banking Partner in connection to this Ordermoney dictionarybuy / sell
settlement.currencystringeg, USDbuy / sell
settlement.amountunsignedstringeg, 8520.00buy / sell
settlement.operationwhether the amount in this object adds or subtracts balancestring enumdebit/creditbuy / sell
requires_confirmation_codeif you need to send a code supplied by the user to confirm the orderboolbuy / sell / send
feescharged fees in case they existstringsend / receive
networkIndicates the network to sendstringbitcoin / ethereum / polygonsend
destinationdictionary containing destination datasend
destination.typethe destination typestringeg, crypto_currency_addresssend
destination.valuethe address itselfstringsend
destination.amountthe amount to sendstringsend
origindictionary containing origin datareceive
origin.typethe origin typestringeg, crypto_transactionreceive
origin.valuethe originating addressstringreceive
origin.amountthe amount receivedstringreceive
customer.currencycurrency for the amount accepted by the customerstringeg. ARS
customer.amountAmount accepted by the customerstring
exchange.swap_order_idIn a swap order, points to the id of the counterpart order (credit if this is debit, debit if this is credit)
buy.fees and sell.feesBuy/Sell specific fees, particularly when Lirium Fee Collection is enabled for your account.array

The fees array in buy and sell orders contains objects with the following fields

FieldDescriptionTypeNotes
typeFee typestringThe only type currently supported is "percentage".
valueValue corresponding to the typestringA value of 1 for type "percentage" would mean 1% fee
modeFee collection modestringThe only mode currently supported is "collect". It means the fee is paid by the customer, being collected from the settlement account.
base_amountAmount used to calculate the feestring
base_operationOperation on base_amountstringCan be "add" or "deduct"
amountFee amount

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. ARS), this value must 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.