Skip to main content
Execute buy orders to add asset positions to your customers’ portfolios.

​
Getting Started

This guide walks you through creating buy orders using the Rime API. You’ll make your first successful API call to place a buy order and understand how to help your customers subscribe to assets.

​
Prerequisites

Before creating buy orders, ensure you have:
  1. Authentication token - Follow our authentication guide to get your access token
  2. Customer account - The account_id for the account that the order is placed for
  3. Asset information - The isin for the asset the order should be placed for

​
Order Structure

Buy orders are structured with the following key attributes: Required parameters:
  • Order side (side) - Set to BUY for purchase orders
  • Market type (market) - PRIMARY for new issuances, SECONDARY for existing shares
  • Amount of units (amount_of_units) - Number of share units to purchase
  • Currency (currency) - Currency for the transaction (only EUR is currently supported)
  • Settlement type (settlement_type) - bearer or claimable
  • Share class (isin) - The ISIN code of the asset to invest in
  • Account ID (account_id) - Your customer’s account
Optional parameters:
  • Custom offering ID (custom_offering_id) - If you have a custom fee arrangement for this asset with us, provide the ID here if you want make an order for it under these special conditions.
  • Payment Method Details (sender_payment_method_details) - If you want to use a different payment method than the primary one, provide the details here. If not provided, primary payment method of the account will be used.
  • Wallet Address (recipient_wallet_address) - If you want to use a different wallet than the primary one, provide the address here. The wallet must be registered under the account and whitelisted. If not provided, primary wallet of the account will be used.

​
Step-by-Step Implementation

​
Step 1: Create a buy order

Place a buy order for your customer to purchase fund shares: 
curl -X POST "https://sandbox.api.rime.finance/v1/orders" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "side": "BUY",
    "market": "PRIMARY",
    "amount_of_units": 100000,
    "currency": "EUR",
    "settlement_type": "bearer",
    "isin": "${ISIN}",
    "account_id": "${ACCOUNT_ID}"
  }'

​
Step 2: Handle the response

A successful buy order creation returns a 201 Created status with the order details:
201
{
  "side": "BUY",
  "market": "PRIMARY",
  "amount_of_units": 100000,
  "value": 100000,
  "currency": "EUR",
  "isin": "NL1111111111",
  "settlement_transaction_hash": null,
  "payment_transaction_reference": null,
  "custom_offering_id": null
}

Order Processing

Buy orders start with “PLACED” status and progress through processing stages. Monitor order status to track completion.

​
Troubleshooting

Cause: Invalid isin or investable share class doesn’t existSolution: Verify the isin is correct and the fund is available for subscription
{
  "detail": "Share class not found"
}
Cause: Customer account doesn’t have sufficient funds for the purchaseSolution: Ensure your customer has adequate account balance or reduce the order value
{
  "detail": "Insufficient account balance for order value"
}
Cause: Missing required fields or invalid data typesSolution: Check all required parameters are provided with correct data types
{
  "detail": [
    {
      "loc": ["body", "value"],
      "msg": "ensure this value is greater than 0",
      "type": "value_error.number.not_gt"
    }
  ]
}

​
Next Steps

After creating buy orders for your customers:
  1. Get portfolio information - View the updated portfolio with new holdings
  2. Sell shares - Help customers liquidate positions when needed
  3. Retrieve fund information - Research additional investment options
⌘I