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. See Buy and Sell amounts for selling or swapping a whole balance.
• 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.

Recipes

Runnable end-to-end examples of each operation:

• Buy Crypto (buy)
• Send Crypto (send)
• Subscribe to an Investment (subscribe_investment)
• Redeem an Investment (redeem_investment)

📘

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.

Creating an order at a quoted price

Send the id of a quote from Create Quote as quote_id, and the order is created at the price that quote holds instead of at the market price.

{
    "reference_id": "Abc123ed-F456Gh",
    "quote_id": "cb2af049b9cf4642947436df461486c2",
    "operation": "buy",
    "asset": {
        "currency": "BTC",
        "amount": "0.97087378"
    }
}

• Accepted on buy, sell and send.
• A swap carrying a quote_id is refused with Quote cannot be provided for this operation — a swap cannot be quoted.
• It cannot be combined with asset.full_amount.
• An expired quote no longer holds its price. Quote again rather than reusing the quote_id.

Selling a whole balance

Set asset.full_amount to true to operate the customer's entire available balance of asset.currency, without having to read the balance first and without leaving dust behind:

{
    "reference_id": "Abc123ed-F456Gh",
    "operation": "sell",
    "asset": {
        "currency": "BTC",
        "full_amount": true
    },
    "sell": {
        "settlement": {
            "currency": "USD"
        }
    }
}

{
    "reference_id": "Abc123ed-F456Gh",
    "operation": "swap",
    "asset": {
        "currency": "BTC",
        "full_amount": true
    },
    "swap": {
        "currency": "USDC"
    }
}

Rules:

• Available on sell and swap. It is refused with invalid_parameters on every other operation, buy included.
• When it is true, no amount is sent anywhere in the request — not asset.amount, not settlement.amount, not swap.amount, not delegation.amount. The balance is the amount.
• It cannot be combined with a quote_id. The amount is only resolved when the order is created, so there is nothing to quote beforehand.
• It cannot be combined with redeem_investment inside the operation node. To redeem a whole investment, use redeem_investment.investment.full_amount instead (see the callout below).
• "full_amount": false behaves exactly like omitting it: an amount is still required.

📘

Confirming the amount

The balance is resolved when the order is created, so the resulting asset.amount comes back on the order response. Show that amount to the customer before confirming the order.

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.full_amount is not supported for this operation — asset.full_amount was sent on an operation other than buy, sell or swap.
• Full amount not supported for this operation — asset.full_amount was sent on buy.
• Amounts cannot be set with full amount — an amount was sent alongside asset.full_amount (for example settlement.amount or delegation.amount).
• Quote cannot be provided with full amount — a quote_id was sent alongside asset.full_amount.
• Investment asset cannot be set with full amount — a redeem_investment node was sent alongside asset.full_amount.
• 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 / Either asset.amount or payment.destination.amount can be sent, but not both — both amounts were provided; only one is allowed. The message names the node the second amount was read from.
• {'<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).
• payment.destination is required — a sell carried a payment node with no destination.
• payment is not supported for this operation — a buy carried a payment node. Only sell takes one.
• Quote cannot be provided for this operation — a quote_id was sent on a swap.

⚠️

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.

⚠️

Quoted swaps are now refused

A swap sent with a quote_id is refused with invalid_parameters and Quote cannot be provided for this operation. It was previously ignored, and the order executed at the market rate instead of at the quoted one. See Create Quote for the operations that can be quoted.

📘

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.