Investments

Investments allow your customers to earn yield on their cryptocurrency holdings through established DeFi protocols. Customers can subscribe (deposit) their crypto assets into investment products and redeem (withdraw) them along with any accrued earnings.

Overview

The investment lifecycle consists of three main phases:

Subscribe: Customer Crypto (USDC) → Lirium → DeFi Protocol → Investment Token (aEthUSDC)
Redeem:    Investment Token (aEthUSDC) → DeFi Protocol → Lirium → Customer Crypto (USDC)

Prerequisites

Before integrating investments, ensure:

1. Your partner account has the investments product enabled. Check Partner Details to verify.
2. Your customers are fully onboarded and verified. See KYC Flows.
3. Customers have sufficient balance in the required quote_asset currency to subscribe.

Available Investment Assets

The investments available to your partner account are listed in the available_investments field of the Partner Details response.

Each investment asset includes the following information:

📘

Quote Asset

The quote_asset is the cryptocurrency that the customer must hold to subscribe to the investment, and the cryptocurrency they receive back when redeeming. For example, to subscribe to aEthUSDC, the customer needs USDC in their balance.

Investment Providers

Providers are the DeFi protocols that power the investment products. Use Get Investment Providers to retrieve the list.

Investment Rates

Use Get Investment Rates to query the current rates and yields for all investment assets. This endpoint does not require authentication.

Each rate entry provides:

📘

Rate, APY, and APR

The rate indicates how much quote_asset each investment token is currently worth. This value increases over time as yield accrues. The apy reflects compounded returns while apr reflects simple interest. These values are variable and change based on market conditions.

How It Works

Subscribing to an Investment

Subscribing converts a customer's cryptocurrency into yield-bearing investment tokens through a two-step order process.

Flow:

1. Initiate a subscribe_investment order specifying the investment asset and the amount of quote_asset to invest
2. Confirm the order (with security code if required)
3. The customer's quote_asset balance is debited
4. Investment tokens are credited to the customer's investment balance
5. The investment starts earning yield immediately

POST /customers/{customer_id}/orders

{
  "operation": "subscribe_investment",
  "asset": {
    "currency": "USDC",
    "amount": "2000"
  },
  "subscribe_investment": {
    "investment": {
      "id": "aEthUSDC"
    }
  }
}

{
  "id": "3dfb5a...",
  "operation": "subscribe_investment",
  "state": "pending",
  "created_at": "2024-02-01T10:00:00+00:00",
  "customer_id": "d3488a...",
  "asset": {
    "type": "currency",
    "id": "USDC",
    "operation": "debit",
    "amount": "2000"
  },
  "subscribe_investment": {
    "requires_confirmation_code": true,
    "expires_at": "2024-02-01T10:05:00+00:00",
    "investment": {
      "id": "aEthUSDC"
    },
    "rate": "1.03956"
  }
}

After confirming the order, the response transitions to completed state and includes the resulting investment token balance:

{
  "id": "3dfb5a...",
  "operation": "subscribe_investment",
  "state": "completed",
  "created_at": "2024-02-01T10:00:00+00:00",
  "submitted_at": "2024-02-01T10:01:30+00:00",
  "customer_id": "d3488a...",
  "asset": {
    "type": "currency",
    "id": "USDC",
    "operation": "debit",
    "amount": "2000",
    "balance": "500"
  },
  "subscribe_investment": {
    "requires_confirmation_code": true,
    "expires_at": "2024-02-01T10:05:00+00:00",
    "investment": {
      "id": "aEthUSDC",
      "amount": "1923.87862",
      "operation": "credit",
      "order_id": "ac242..."
    },
    "rate": "1.03956"
  }
}

📘

Investment Token Amount

The amount of investment tokens received is calculated as: asset.amount / rate. In this example: 2000 / 1.03956 = 1923.87862 aEthUSDC tokens.

Redeeming an Investment

Redeeming converts investment tokens back into the quote_asset cryptocurrency plus any accrued earnings.

There are two ways to redeem:

• Partial redemption: Specify the asset.amount to indicate how much quote_asset the customer should receive after all fees are applied
• Full redemption: Set redeem_investment.investment.full_amount to true to redeem the entire investment position

POST /customers/{customer_id}/orders

{
  "operation": "redeem_investment",
  "asset": {
    "currency": "USDC",
    "amount": "850"
  },
  "redeem_investment": {
    "investment": {
      "id": "aEthUSDC"
    }
  }
}

{
  "operation": "redeem_investment",
  "asset": {
    "currency": "USDC"
  },
  "redeem_investment": {
    "investment": {
      "id": "aEthUSDC",
      "full_amount": true
    }
  }
}

⚠️

Redeem Investment Amount

When specifying asset.amount for a partial redemption, this is the net amount of quote_asset the customer will receive after all fees are applied. Lirium calculates how many investment tokens need to be redeemed to achieve this net amount.

When using full_amount: true, do not specify asset.amount.

{
  "id": "7bc9e2...",
  "operation": "redeem_investment",
  "state": "completed",
  "created_at": "2024-06-15T14:00:00+00:00",
  "submitted_at": "2024-06-15T14:01:00+00:00",
  "customer_id": "d3488a...",
  "asset": {
    "type": "currency",
    "id": "USDC",
    "operation": "credit",
    "amount": "850",
    "balance": "1350"
  },
  "redeem_investment": {
    "requires_confirmation_code": true,
    "expires_at": "2024-06-15T14:05:00+00:00",
    "investment": {
      "id": "aEthUSDC",
      "amount": "814.761562",
      "operation": "debit",
      "order_id": "b5ece..."
    },
    "rate": "1.04325",
    "invested_amount": "846.993529",
    "gross_amount": "850",
    "earnings": "3.006471",
    "fees": [
      {
        "source": "lirium_commission",
        "type": "earnings_percentage",
        "value": "5",
        "mode": "collect",
        "base_amount": "3.006471",
        "base_operation": "deduct",
        "amount": "0.15032355"
      }
    ]
  }
}

Monitoring Customer Investments

Use Customer Investments to retrieve a customer's current investment positions with real-time valuation data.

GET /customers/{customer_id}/investments

The response includes each investment position with detailed performance metrics:

{
  "investments": [
    {
      "id": "aEthUSDC",
      "amount": "1109.117058",
      "valued_position": {
        "quote_asset": "USDC",
        "invested_amount": "1153.006471",
        "invested_price": "1.03956",
        "last_price": "1.04325",
        "valued_amount": "1157.100123",
        "pnl": "4.093652",
        "pnl_percentage": "0.35",
        "net": {
          "fee_amount": "0.204683",
          "valued_amount": "1156.895440",
          "pnl": "3.888969",
          "pnl_percentage": "0.34"
        }
      }
    }
  ]
}

Valuation Fields

📘

Partner Commission in Valuation

The Customer Investments endpoint accepts an optional fee_value query parameter. When provided, the net fields in the response will include the partner's commission in the fee calculations, giving a more accurate view of what the customer would receive upon redemption.

Fees

Lirium Commission

Lirium charges a fee on investment redemptions based on the earnings generated. The fee type is earnings_percentage, meaning the fee is calculated as a percentage of the earnings only.

Example: If the fee value is 5 (5%) and the customer earned 3.006471 USDC, the fee would be 0.15032355 USDC (5% of 3.006471).

If a redemption has no earnings (the rate has not changed since subscription), no fees are collected.

Partner Commission

Partners can optionally charge their own commission on redeem_investment orders. This is a feature that requires enabling prior to usage.

To collect a partner commission, include the commission field in the redemption request:

{
  "operation": "redeem_investment",
  "asset": {
    "currency": "USDC",
    "amount": "850"
  },
  "redeem_investment": {
    "investment": {
      "id": "aEthUSDC"
    },
    "commission": {
      "type": "earnings_percentage",
      "value": "2"
    }
  }
}

The supported commission types are:

Partner commissions are collected by Lirium and paid later into the partner's settlement balance.

Integration Guide

Step 1: Discover Available Investments

Query your partner's available investments and display them to customers with current rates.

# Get your available investments (from Partner Details)
GET /partner

# Get current rates and yields (no auth required)
GET /investments/rates

# Get provider information (no auth required)
GET /investments/providers

Step 2: Subscribe

When a customer wants to invest, create a subscribe_investment order:

1. Call Create Order with operation: "subscribe_investment"
2. Display the order details to the customer (rate, token amount, expiration)
3. Collect the security code if requires_confirmation_code is true
4. Call Confirm Order to execute the investment

Step 3: Monitor Positions

Periodically query Customer Investments to display the customer's current positions, earnings, and P&L.

Step 4: Redeem

When a customer wants to withdraw their investment:

1. Call Create Order with operation: "redeem_investment"
2. Display the order details including earnings breakdown and fees
3. Collect the security code if requires_confirmation_code is true
4. Call Confirm Order to execute the redemption

Step 5: Track via Webhooks

Use webhooks to receive real-time notifications about order status changes via the order-updated event.

Best Practices

1. Display rates clearly: Show customers the current APY/APR and explain that rates are variable and subject to change.

2. Show net values: Use the net fields from Customer Investments to display the actual value customers would receive after fees.

3. Validate amounts: Check subscription.min_amount and subscription.max_amount before initiating orders to avoid validation errors.

4. Handle expiration: Pending orders expire at expires_at. If a customer doesn't confirm in time, the order will be automatically aborted and a new one must be created.

5. Use webhooks: Subscribe to order-updated events rather than polling for order status changes.

6. Explain fees upfront: Clearly communicate Lirium's earnings_percentage fee structure so customers understand the net returns.

API Reference

• Get Investment Providers
• Get Investment Rates
• Customer Investments
• Create Order (for subscribe_investment and redeem_investment operations)
• Confirm Order
• Order Details