Order execution flow

Overview

This guide explains how to submit buy or sell orders for assets in a user’s portfolio using the Investment Orders endpoint POST /investments/orders.

All order operations require M2M authentication with a bearer token and the x-user-id header to specify which user’s orders to manage.

Key differences between order types

Buy orders: Specify amount (monetary value to invest). You must verify the user has sufficient cash balance before submitting.
Sell orders: Specify quantity (asset units to sell). You must verify the user has sufficient holdings before submitting.

Prerequisites

Access to API endpoints
M2M bearer token with required scopes
x-user-id header (user identifier, MongoDB ObjectId format)

Buy order flow

Use this flow to purchase an asset for a user’s portfolio.

Verify available cash

Before submitting a buy order, retrieve the user’s cash balance to ensure sufficient funds are available.Call GET /cash to retrieve the available cash balance across all currencies.

const BASE = 'https://api.wealthyhood.com';

async function getCashBalance({ token, userId }) {
  const res = await fetch(`${BASE}/cash`, {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${token}`,
      'x-user-id': userId,
      'Accept': 'application/json'
    }
  });
  if (!res.ok) throw new Error(`Failed to get cash: ${res.status}`);
  return res.json();
}

curl -X GET 'https://api.wealthyhood.com/cash' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_M2M_TOKEN' \
  -H 'x-user-id: 64f0c51e7fb3fc001234abcd'

Compare the available cash balance in the target currency with the intended purchase amount before proceeding.

Get asset buy preview

Get a preview of the asset buy transaction to show execution options, fees breakdown, and estimated quantity.Call POST /investments/asset/preview with the asset ISIN, amount, and side set to “buy”.

const BASE = 'https://api.wealthyhood.com';

async function getAssetBuyPreview({ token, userId, isin, amount }) {
  const res = await fetch(`${BASE}/investments/asset/preview`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'x-user-id': userId,
      'Accept': 'application/json',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      isin,
      amount,
      side: 'buy'
    })
  });
  if (!res.ok) throw new Error(`Failed to get preview: ${res.status}`);
  return res.json();
}

curl -X POST 'https://api.wealthyhood.com/investments/asset/preview' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_M2M_TOKEN' \
  -H 'x-user-id: 64f0c51e7fb3fc001234abcd' \
  -d '{
    "isin": "US0378331005",
    "amount": 25.5,
    "side": "buy"
  }'

Display both express and smart execution options:

Express (real-time): Faster execution but may incur additional fees
Smart (market hours): Lower fees but executes during market hours

Show the fees breakdown (fees.express vs fees.smart) and execution windows to help users make informed decisions.

Submit the buy order

Call POST /investments/orders with optional query params:

paymentMethod: cash (default) or gift
executeEtfOrdersInRealtime: true only for users enabled for real-time ETF execution

const BASE = 'https://api.wealthyhood.com';

async function submitBuyOrder({ token, userId, isin, amount, paymentMethod = 'cash', executeEtfOrdersInRealtime }) {
  const url = new URL(`${BASE}/investments/orders`);
  if (paymentMethod) url.searchParams.set('paymentMethod', paymentMethod);
  if (typeof executeEtfOrdersInRealtime === 'boolean') {
    url.searchParams.set('executeEtfOrdersInRealtime', String(executeEtfOrdersInRealtime));
  }

  const res = await fetch(url.toString(), {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'x-user-id': userId,
      'Accept': 'application/json',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      side: 'buy',
      isin,
      amount
    })
  });
  if (!res.ok) throw new Error(`Order failed: ${res.status}`);
  return res.json();
}

curl -X POST 'https://api.wealthyhood.com/investments/orders?paymentMethod=cash' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_M2M_TOKEN' \
  -H 'x-user-id: 64f0c51e7fb3fc001234abcd' \
  -d '{
    "side": "buy",
    "isin": "US0378331005",
    "amount": 25.5
  }'

Use executeEtfOrdersInRealtime=true only for eligible users and only for ETFs.

Render the transaction in UI

The response is an AssetTransaction with display-ready fields such as displayAmount, displayQuantity, executionWindow, fees, and nested orders.

Show execution window: Use executionWindow.type (e.g., real-time or market-hours) and expectedExecutionDate when provided.
Show fees: Display fees.commission.amount, fees.fx.amount, etc., when present.
Show order summary: From orders[0], read isin, side, status, and displayQuantity.

Successful submission returns HTTP 200 with a populated transaction object.

Sell order flow

Use this flow to sell an asset from a user’s portfolio.

Verify portfolio holdings

Before submitting a sell order, retrieve the user’s portfolio holdings to ensure sufficient quantity of the asset is available.Call GET /portfolios/{id} to retrieve holdings with asset details and quantities.

const BASE = 'https://api.wealthyhood.com';

async function getPortfolioHoldings({ token, userId, portfolioId }) {
  const res = await fetch(`${BASE}/portfolios/${portfolioId}`, {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${token}`,
      'x-user-id': userId,
      'Accept': 'application/json'
    }
  });
  if (!res.ok) throw new Error(`Failed to get holdings: ${res.status}`);
  return res.json();
}

curl -X GET 'https://api.wealthyhood.com/portfolios/64f0c51e7fb3fc001234abcd' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_M2M_TOKEN' \
  -H 'x-user-id: 64f0c51e7fb3fc001234abcd'

Verify that the portfolio holdings contain sufficient quantity of the asset (by ISIN) before proceeding with the sell order.

The holdings response includes an array of holdings, each with:

asset.isin: ISIN of the asset
quantity: Available quantity to sell
asset.currentTicker.price: Current price per unit

Get asset sell preview

Get a preview of the asset sell transaction to show execution options, fees breakdown, and estimated proceeds.Call POST /investments/asset/preview with the asset ISIN, quantity, and side set to “sell”.

const BASE = 'https://api.wealthyhood.com';

async function getAssetSellPreview({ token, userId, isin, quantity }) {
  const res = await fetch(`${BASE}/investments/asset/preview`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'x-user-id': userId,
      'Accept': 'application/json',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      isin,
      quantity,
      side: 'sell'
    })
  });
  if (!res.ok) throw new Error(`Failed to get preview: ${res.status}`);
  return res.json();
}

curl -X POST 'https://api.wealthyhood.com/investments/asset/preview' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_M2M_TOKEN' \
  -H 'x-user-id: 64f0c51e7fb3fc001234abcd' \
  -d '{
    "isin": "IE00B4L5Y983",
    "quantity": 1.25,
    "side": "sell"
  }'

Display both express and smart execution options:

Express (real-time): Faster execution but may incur additional fees
Smart (market hours): Lower fees but executes during market hours

Show the estimated proceeds (orders.express and orders.smart with money field) and fees breakdown.

Aggregated sell orders for ETFs are rejected for real-time-enabled users. Check hasETFOrders in the preview response to determine if this applies.

Submit the sell order

Call POST /investments/orders with optional query params:

paymentMethod: cash (default) or gift
executeEtfOrdersInRealtime: true only for users enabled for real-time ETF execution

const BASE = 'https://api.wealthyhood.com';

async function submitSellOrder({ token, userId, isin, quantity, paymentMethod = 'cash', executeEtfOrdersInRealtime }) {
  const url = new URL(`${BASE}/investments/orders`);
  if (paymentMethod) url.searchParams.set('paymentMethod', paymentMethod);
  if (typeof executeEtfOrdersInRealtime === 'boolean') {
    url.searchParams.set('executeEtfOrdersInRealtime', String(executeEtfOrdersInRealtime));
  }

  const res = await fetch(url.toString(), {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'x-user-id': userId,
      'Accept': 'application/json',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      side: 'sell',
      isin,
      quantity
    })
  });
  if (!res.ok) throw new Error(`Order failed: ${res.status}`);
  return res.json();
}

curl -X POST 'https://api.wealthyhood.com/investments/orders?paymentMethod=cash' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_M2M_TOKEN' \
  -H 'x-user-id: 64f0c51e7fb3fc001234abcd' \
  -d '{
    "side": "sell",
    "isin": "IE00B4L5Y983",
    "quantity": 1.25
  }'

Aggregated sell orders for ETFs are rejected for real-time-enabled users. If the preview shows hasETFOrders: true and the user is real-time enabled, you should set executeEtfOrdersInRealtime=false or show an error message.

Render the transaction in UI

The response is an AssetTransaction with display-ready fields such as displayAmount, displayQuantity, executionWindow, fees, and nested orders.

Show execution window: Use executionWindow.type (e.g., real-time or market-hours) and expectedExecutionDate when provided.
Show fees: Display fees.commission.amount, fees.fx.amount, etc., when present.
Show order summary: From orders[0], read isin, side, status, and displayQuantity.

Successful submission returns HTTP 200 with a populated transaction object.

Error handling

400 Bad Request: Validation or business rule violation (e.g., invalid amount, missing required field, invalid ISIN).
401/403: Authentication/authorization failures.
404 Not Found: Portfolio or related resource not found.

Getting started

Screens

Flows

Sandbox Flows

Overview

Key differences between order types

Prerequisites

Buy order flow

Sell order flow

Error handling

See also

​Overview

​Key differences between order types

​Prerequisites

​Buy order flow

​Sell order flow

​Error handling

​See also

Overview

Key differences between order types

Prerequisites

Buy order flow

Sell order flow

Error handling

See also