Orders Reference

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:

Field	Description	Type / Values	Notes	Example
id	Lirium's unique Identification for the order.	string		3dfb5...
operation	Order operation.	string_enum	see order operations	buy
reference_id	Banking Partner's unique Identification for the order. Optional.	string	Up to 64 characters long. Case sensitive	ref123-ABC
state	Current state of the order.	string_enum	see order sates	completed
created_at	Creation timestamp.	timestamp		2021-03-03T02:39:03.830641+00:00
last_updated_at	Timestamp of the last time the data on the order was changed.	timestamp		2021-03-03T02:39:04.417710+00:00
submitted_at	Confirmation timestamp.	timestamp	Empty when state is pending, pending_receive or aborted	2021-03-03T02:39:04.254244+00:00
customer_id		string		d3488a...
asset	dictionary containing the asset affected by this order
asset.type	Type of the asset	string	see asset types	currency
asset.id	Id of the asset	string	Varies depending on the type	BTC

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:

Field	Description	Type / Values	Notes	Example
operation	Whether the amount in this object adds or subtracts balance	string_enum	debit|credit	credit
amount	Affected balance amount. unsigned	string_decimal		0.00110507
balance	Resulting balance after the order was confirmed.	string_decimal	Empty when state is pending, pending_receive or aborted	0.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

Field	Description	Type	Notes
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.
requires_confirmation_code	Indicates whether if a code supplied by the user is required in Confirm Order	bool	see Security Code

---

Buy / Sell

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

Field	Description	Type	Notes	Example
settlement	dictionary containing currency and amount charged by Lirium to the Banking Partner in connection to this Order	money dictionary
settlement.currency		string		EUR
settlement.amount		string_decimal	unsigned	45
settlement.operation	whether the amount in this object adds or subtracts balance	string_enum	debit|credit	debit
reference	Dictionary containing the reference amount in USD	money dictionary
reference.currency		string	always USD	USD
reference.amount		string_decimal	unsigned	54.32
fees	Fees collected on this order.	array	see buy and sell fee
customer	Dictionary containing the final amount paid or received by the customer	money dictionary
customer.currency		string		BRL
customer.amount		string_decimal	unsigned	305.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

Field	Description	Type	Notes	Example
type	Fee type	string_enum	see fee type and value	percentage
value	Value corresponding to the type	string_decimal		1.5
mode	Fee mode	string	The only mode currently supported is collect. It means the fee is paid by the customer, being collected from the settlement account.	collect
base_amount	Amount used to calculate the fee	string	see fee base_amount and base_operation	45
base_operation	Operation on base_amount	string_enum	add | deduct	deduct
amount	The amount to be collected as fee			44.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

Field	Description	Type	Example
currency	Currency of the counterpart of the swap	string	USDC
amount	Amount of the counterpart of the swap	string_decimal	100.00131
exchange.swap_order_id	Indicates the id of the counterpart order (credit if this is debit, debit if this is credit)	string	ca45aa...

---

Send

Field	Description	Type	Notes	Example
fees	Amount of fees charged	string_decimal		0.00000193
network	Indicates the network to send	string_enum	bitcoin | ethereum | polygon | offchain	bitcoin
destination	Dictionary containing destination data
destination.type	Destination type	string_enum	crypto_currency_address |lirium_customer	crypto_ currency_ address
destination.value	Blockchain address or Lirium customer id	string	Varies depending on the type	2MspxDtN...
destination.amount	Amount to send	string		0.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:

  Field	Description	Type	Example
  transaction_id	The transaction id on the blockchain	string	0x123abc...

• 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:

  Field	Description	Type	Example
  customer_id	The customer id of the receiver	string	8281c...
  order_id	The order id of the receiver	string	0d490...

---

Receive

Field	Description	Type	Notes	Example
fees	charged fees in case they exist	string		0
network	Indicates the network where it was received	string_enum	bitcoin | ethereum | polygon | offchain	ethereum
origin	dictionary containing origin data
origin.type	the origin type	string_enum	blockchain_transaction | lirium_transfer	blockchain_ transaction
origin.value	the originating blockchain transaction id or Lirium customer id	string	Varies depending on the type	0xabc123...
origin.amount	the amount received	string		12.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

    Field	Description	Type	Example
    transaction_id	The transaction id on the blockchain	string	0xabc123...

• 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:

    Field	Description	Type	Example
    customer_id	The customer id of the receiver	string	7141b...
    order_id	The order id of the receiver	string	c88e5...

---

Receive NFT

Field	Description	Type	Notes
network	Indicates the network to where it was received	string_enum	polygon
origin	dictionary containing origin data
origin.type	the origin type	string_enum	blockchain_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

    Field	Description	Type	Example
    transaction_id	The transaction id on the blockchain	string	0x123abc...

---

Subscribe Investment

Field	Description	Type	Notes	Example
investment	Dictionary containing investment data
investment.id	Id of the investment token	string	It is one of the partner's available_investments	aEthUSDC
investment.amount	Amount of investment tokens received	string_decimal		1923.87862
investment.operation	Whether the amount in this object adds or subtracts balance	string_enum	Subscriptions are always credit	credit
investment.order_id	Id of the order that reflects the investment token balance operation	string		ac242...
rate	Indicates amount of asset per investment token	string_decimal		1.03956

---

Redeem Investment

Field	Description	Type	Notes	Example
investment	Dictionary containing investment data
investment.id	Id of the investment token	string	One of the investment assets previously subscribed	aEthUSDC
investment.amount	Amount of investment tokens redeemed	string_decimal		814.761562
investment.operation	Whether the amount in this object adds or subtracts balance	string_enum	Redemptions are always debit	debit
investment.order_id	Id of the order that reflects the investment token balance operation	string		b5ece...
rate	Indicates amount of asset per investment token	string_decimal		1.04325
invested_amount	Amount of asset previously invested to obtain the amount of investment tokens redeemed	string_decimal		846.993529
gross_amount	Gross amount of asset obtained by redeeming the investment tokens. Before applying fees.	string_decimal	investment.amount * rate	850
earnings	Difference between amount of asset obtained vs invested	string_decimal	gross_amount - invested_amount	3.006471
fees	Fees collected on this order.	array	see investment redemption fee

Investment Redemption Fee

The fees array contains objects with the following fields

Field	Description	Type	Notes	Example
source	Source of the fee	string_enum	lirium_commission | partner_commission	lirium_ commission
type	Fee type	string_enum	see fee type and value	percentage
value	Value corresponding to the type	string_decimal		5
mode	Fee mode	string	The 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 fees	collect
base_amount	Amount used to calculate the fee	string	see fee base_amount	3.006471
base_operation	Operation on base_amount	string_enum	The fee operation will always be deduct	deduct
amount	The amount to be collected as fee			0.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.