Create a new order for a customer. The order type is determined by the operation field.

Order Types

• buy / sell: Exchange fiat for crypto or vice versa. See Buy and Sell amounts for details on specifying amounts. For bank withdrawals, see Sell with Fiat Instructions.
• swap: Exchange one cryptocurrency for another.
• send: Send cryptocurrency to a blockchain address, another Lirium customer, or an Address Book entry. See Send amounts for details.
• subscribe_investment: Subscribe to an investment product.
• redeem_investment: Redeem an investment.

For complete order field documentation, see the Orders Reference.

📘

Operation Nodes

All "operation nodes" ("buy": {},"sell": {}, "swap": {}, "send":{}, "subscribe_investment":{}, "redeem_investment":{}) are mutually exclusive.

See the request examples for clarification

📘

Reference ID

The Reference ID is intended for your internal use. You can set an ID generated in your systems and we will store and return it as part of the order's data.

If a Reference ID is specified when creating an order, it will be used as an idempotency key. The value for this id could be used only once. Attempts to submit already used Reference ID will return an error.

It can be left empty on order initiation and assigned later on order confirmation.
However, when submitted on order initiation, it must not be sent on order confirmation.

⚠️

Buy / Sell Settlement currency

The parameter is optional if you have only one settlement currency configured.

If you have multiple settlement currencies, then the settlement currency parameter must be specified in all buy and sell orders.

Error Responses

Error responses include error_code, error_msg, and a request_id field for tracking. Some errors may include additional context fields depending on the error type.

Examples of invalid_parameters conditions surfaced by error_msg:

• Only one operation node is allowed — more than one of buy/sell/swap/send/subscribe_investment/redeem_investment was supplied.
• The operation node name must match the operation value (<operation>) — the operation value does not match the node key in the body.
• Node '<operation>' is required. — the node matching operation is missing (e.g. operation: swap without a swap block).
• asset.amount or settlement.amount is required / asset.amount or destination.amount is required — neither an asset amount nor a settlement/destination amount was provided.
• Either asset.amount or settlement.amount can be sent, but not both / Either asset.amount or destination.amount can be sent, but not both — both amounts were provided; only one is allowed.
• {'<node>': {'commission': {'type': ['Must be one of: percentage, fixed.']}}} — invalid commission type for buy/sell. For redeem_investment, the allowed values are earnings_percentage, percentage, fixed.
• {'<operation>': {'<field>': ['This field is required but was not found in the request.']}} — the referenced nested field is required for the operation (for example, send.destination.value or redeem_investment.investment).

⚠️

Redeem Investment

The parameter asset.amount is used to specify how much asset.currency should the customer receive in their account after all fees are applied. The calculation of how many investment shares/tokens should be redeemed are calculated.

If the customer wants to redeem all the investment, then the parameter redeem_investment.investment.full_amount should be set to true and asset.amount must not be specified.

The parameter redeem_investment.commission is used to tell Lirium to collect the Partner's commission fee. This is a feature that requires enabling prior to usage.

📘

Commission and fees in responses

For buy, sell, swap, and send orders, the commission node is accepted on the request but is not echoed back in the response — the commission is already reflected in the settlement or asset amounts.

For redeem_investment, commissions surface in the response as entries inside the redeem_investment.fees[] array. Each entry includes source (lirium_commission or partner_commission), type, value, mode, base_amount, base_operation, and amount. When no commission applies, the fees array is omitted from the response.