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
abortedare orders that were initiated but not confirmed before itsexpirationtime. 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:
| Field | Description | Type / Values | Notes |
|---|---|---|---|
| id | Lirium's unique Identification for the order. | string | |
| operation | Order operation. | string enum | buy/sell/send/receive |
| reference_id | Banking Partner's unique Identification for the order. Optional. | string | Up to 64 characters long. Case sensitive |
| state | Current state of the order. | string enum | pending/processing/completed/aborted/cancelled |
| created_at | Creation timestamp. | timestamp | |
| last_updated_at | Timestamp of the last time the data on the order was changed. | timestamp | |
| submitted_at | Confirmation timestamp. | timestamp | Empty when state is pending or aborted |
| customer_id | string | ||
| asset.currency | Affected balance currency | string | BTC/ETH/etc |
| asset.amount | Affected balance amount. unsigned | string | *eg. 0.00230000 |
| asset.operation | Whether the amount in this object adds or subtracts balance | string enum | debit/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
| Field | Description | Type | Notes | Applies to |
|---|---|---|---|---|
| expires_at | timestamp at which the order expires if still in pending state. | timestamp | If the order is not confirmed before this time will be automatically aborted. | buy / sell / send |
| settlement | dictionary containing currency and amount charged by Lirium to the Banking Partner in connection to this Order | money dictionary | buy / sell | |
| settlement.currency | string | eg, USD | buy / sell | |
| settlement.amount | unsigned | string | eg, 8520.00 | buy / sell |
| settlement.operation | whether the amount in this object adds or subtracts balance | string enum | debit/credit | buy / sell |
| requires_confirmation_code | if you need to send a code supplied by the user to confirm the order | bool | buy / sell / send | |
| fees | charged fees in case they exist | string | send / receive | |
| network | Indicates the network to send | string | bitcoin / ethereum / polygon | send |
| destination | dictionary containing destination data | send | ||
| destination.type | the destination type | string | eg, crypto_currency_address | send |
| destination.value | the address itself | string | send | |
| destination.amount | the amount to send | string | send | |
| origin | dictionary containing origin data | receive | ||
| origin.type | the origin type | string | eg, crypto_transaction | receive |
| origin.value | the originating address | string | receive | |
| origin.amount | the amount received | string | receive | |
| customer.currency | currency for the amount accepted by the customer | string | eg. ARS | |
| customer.amount | Amount accepted by the customer | string | ||
| exchange.swap_order_id | In 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.fees | Buy/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
| Field | Description | Type | Notes |
|---|---|---|---|
| type | Fee type | string | The only type currently supported is "percentage". |
| value | Value corresponding to the type | string | A value of 1 for type "percentage" would mean 1% fee |
| mode | Fee collection mode | string | The only mode currently supported is "collect". It means the fee is paid by the customer, being collected from the settlement account. |
| base_amount | Amount used to calculate the fee | string | |
| base_operation | Operation on base_amount | string | Can be "add" or "deduct" |
| amount | Fee 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.