Execute portfolio buy order

POST

investments

portfolio

orders

curl --request POST \
  --url https://{host}/investments/portfolio/orders \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-user-id: <x-user-id>' \
  --data '
{
  "portfolioId": "64f0c51e7fb3fc001234abcd",
  "orderAmount": 100,
  "allocationMethod": "holdings",
  "executeEtfOrdersInRealtime": false
}
'

{
  "id": "64f5b3137fb3fc001234abce",
  "category": "AssetTransaction",
  "status": "Pending",
  "portfolioTransactionCategory": "buy",
  "owner": "64f0c51e7fb3fc001234abcd",
  "portfolio": "64f0c51e7fb3fc001234abcd",
  "consideration": {
    "currency": "EUR",
    "amount": 10000
  },
  "executionWindow": {
    "stocks": {
      "executionType": "MARKET_HOURS",
      "start": "2024-07-12T09:30:00.000Z",
      "end": "2024-07-12T16:00:00.000Z"
    },
    "etfs": {
      "executionType": "MARKET_HOURS",
      "start": "2024-07-12T13:00:00.000Z",
      "end": "2024-07-12T18:00:00.000Z"
    }
  },
  "orders": [
    {
      "id": "64f5b3137fb3fc001234abcf",
      "isin": "US0378331005",
      "side": "Buy",
      "status": "Pending",
      "quantity": 0.5,
      "consideration": {
        "currency": "EUR",
        "amount": 5000
      }
    }
  ],
  "fees": {
    "realtimeExecution": {
      "currency": "EUR",
      "amount": 0
    }
  }
}

{
  "status": 400,
  "error": {
    "message": "Target allocation is not set up for this portfolio",
    "description": "Operation failed"
  },
  "responseId": "3f0fd3bf-a2ff-4c0e-9b1d-5d7055dbf6cd"
}

{
  "status": 401,
  "error": {
    "message": "User not found"
  },
  "responseId": "145f2b0d-1d5b-4e91-8d0d-7af0ae9ad13a"
}

{
  "status": 403,
  "error": {
    "message": "Portfolio does not belong to user"
  },
  "responseId": "5e467f79-c62c-4d83-9810-7a0f8529fd76"
}

{
  "status": 404,
  "error": {
    "message": "Portfolio not found"
  },
  "responseId": "65c0b1f6-2a48-4c4f-a5aa-9b9c8c6f9b58"
}

Authorizations

Authorization

string

header

required

Auth0-issued access token that includes the scopes listed for the endpoint.

Headers

x-user-id

string

required

User identifier for the M2M client to specify which user's data to access.

Pattern: ^[a-f0-9]{24}$

Body

application/json

portfolioId

string

required

Portfolio identifier (MongoDB ObjectId)

Pattern: ^[a-f0-9]{24}$

orderAmount

number<double>

required

Amount to invest in whole currency units (e.g., 100.0 for 100 EUR)

Required range: x >= 0.01

allocationMethod

enum<string>

required

Method for distributing the investment across assets

Available options:

targetAllocation,

holdings

executeEtfOrdersInRealtime

boolean

required

Whether to execute ETF orders in real-time. Only users enabled for real-time execution can set this to true.

Response

Portfolio buy order executed successfully

Asset transaction enriched with display-ready fields.

string

required

category

enum<string>

required

Available options:

AssetTransaction

status

string

required

Current transaction status (Pending, PendingGift, Settled, etc.).

orders

object[]

required

Show child attributes

portfolioTransactionCategory

enum<string>

Available options:

update,

buy,

sell

owner

string

User identifier owning the transaction.

portfolio

string

Portfolio identifier associated with the transaction.

consideration

object

Show child attributes

executionWindow

object | null

Execution windows separated by asset category (matches domain ExecutionWindowsType)

Show child attributes

fees

object | null

Wealthyhood fees on orders and settled transactions (commission, FX, and real-time execution when applicable).

Show child attributes

partnerFees

object | null

Present for partner users when countervalue fees apply.

Show child attributes

Cancel portfolio transactionCancel a pending portfolio asset transaction and all its associated orders

curl --request POST \
  --url https://{host}/investments/portfolio/orders \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-user-id: <x-user-id>' \
  --data '
{
  "portfolioId": "64f0c51e7fb3fc001234abcd",
  "orderAmount": 100,
  "allocationMethod": "holdings",
  "executeEtfOrdersInRealtime": false
}
'

{
  "id": "64f5b3137fb3fc001234abce",
  "category": "AssetTransaction",
  "status": "Pending",
  "portfolioTransactionCategory": "buy",
  "owner": "64f0c51e7fb3fc001234abcd",
  "portfolio": "64f0c51e7fb3fc001234abcd",
  "consideration": {
    "currency": "EUR",
    "amount": 10000
  },
  "executionWindow": {
    "stocks": {
      "executionType": "MARKET_HOURS",
      "start": "2024-07-12T09:30:00.000Z",
      "end": "2024-07-12T16:00:00.000Z"
    },
    "etfs": {
      "executionType": "MARKET_HOURS",
      "start": "2024-07-12T13:00:00.000Z",
      "end": "2024-07-12T18:00:00.000Z"
    }
  },
  "orders": [
    {
      "id": "64f5b3137fb3fc001234abcf",
      "isin": "US0378331005",
      "side": "Buy",
      "status": "Pending",
      "quantity": 0.5,
      "consideration": {
        "currency": "EUR",
        "amount": 5000
      }
    }
  ],
  "fees": {
    "realtimeExecution": {
      "currency": "EUR",
      "amount": 0
    }
  }
}

{
  "status": 400,
  "error": {
    "message": "Target allocation is not set up for this portfolio",
    "description": "Operation failed"
  },
  "responseId": "3f0fd3bf-a2ff-4c0e-9b1d-5d7055dbf6cd"
}

{
  "status": 401,
  "error": {
    "message": "User not found"
  },
  "responseId": "145f2b0d-1d5b-4e91-8d0d-7af0ae9ad13a"
}

{
  "status": 403,
  "error": {
    "message": "Portfolio does not belong to user"
  },
  "responseId": "5e467f79-c62c-4d83-9810-7a0f8529fd76"
}

{
  "status": 404,
  "error": {
    "message": "Portfolio not found"
  },
  "responseId": "65c0b1f6-2a48-4c4f-a5aa-9b9c8c6f9b58"
}

API documentation

Authentication

Automations

Universe Configuration

Users

Cash

Savings Vault

Bank Accounts

Account Closures

Deposits

Wallets

Withdrawals

Portfolios

Insights

Daily Summaries

Investment Products

Investment Orders

Savings Orders

Savings Details

Automations

Learn

Notification Settings

Transactions

Test

Authorizations

Headers

Body

Response