> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wealthyhood.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Submit order

> Place a single buy or sell order for a portfolio and receive the resulting asset transaction.



## OpenAPI

````yaml POST /investments/orders
openapi: 3.0.3
info:
  title: Wealthyhood Investments API
  version: 1.0.0
  description: >
    Portfolio and asset investment preview, execution, and order management
    endpoints for Wealthyhood portfolios.


    All requests use machine-to-machine (M2M) authentication. Each request
    requires:

    - A bearer access token (M2M token with required scopes)

    - An `x-user-id` header to specify which user's data to access
servers:
  - url: https://{host}
    variables:
      host:
        default: api.wealthyhood.com
        description: Wealthyhood API host name.
security:
  - bearerAuth: []
tags:
  - name: Investments
    description: >-
      Preview and execute portfolio and asset investment operations, and manage
      orders.
paths:
  /investments/orders:
    post:
      tags:
        - Investments
      summary: Submit a single asset order
      description: >
        Submit a buy or sell order for a single asset. The route validates
        ownership of the portfolio,

        enforces minimum trade thresholds, and enriches the response with
        display fields such as execution

        windows, fees, and quantities before returning it to the caller.


        For **buy orders**, specify `amount` (the monetary value to invest).

        For **sell orders**, specify `quantity` (the number of asset units to
        sell).


        **Order type:** Use one of the `SubmitAssetOrderRequest` branches —
        market orders omit

        `orderType` or set it to `Market`; limit orders require `orderType:
        Limit`, `limitPrice`, and

        `timeInForce`. See the request schema `oneOf` for per-branch required
        fields and constraints.
      parameters:
        - $ref: '#/components/parameters/XUserId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubmitAssetOrderRequest'
            examples:
              buyFromCash:
                summary: Buy order funded from cash balance
                value:
                  side: buy
                  isin: US0378331005
                  amount: 25.5
              buyWithRealtimeExecution:
                summary: Buy order with real-time ETF execution enabled
                value:
                  side: buy
                  isin: IE00B4L5Y983
                  amount: 100
                  executeEtfOrdersInRealtime: true
              sellAll:
                summary: Sell order using quantity
                value:
                  side: sell
                  isin: IE00B4L5Y983
                  quantity: 1.25
              limitBuy:
                summary: Limit buy order
                value:
                  side: buy
                  isin: US0378331005
                  orderType: Limit
                  amount: 50
                  limitPrice: 150
                  timeInForce:
                    type: goodTillDate
                    expiresAt: '2026-07-28T12:00:00.000Z'
              limitSell:
                summary: Limit sell order
                value:
                  side: sell
                  isin: US0378331005
                  orderType: Limit
                  quantity: 2
                  limitPrice: 200
                  timeInForce:
                    type: goodTillDate
                    expiresAt: '2026-07-28T12:00:00.000Z'
      responses:
        '200':
          description: Order created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssetTransaction'
              examples:
                marketOrder:
                  summary: Market order response
                  value:
                    id: 64f5b3137fb3fc001234abce
                    category: AssetTransaction
                    status: Pending
                    orders:
                      - id: 64f5b3137fb3fc001234abcf
                        displayId: ORD-ABC12
                        isin: US0378331005
                        side: Buy
                        status: Pending
                        orderType: Market
                        quantity: 1.5
                        executionWindow:
                          executionType: REALTIME
                          start: '2024-07-12T09:30:00.000Z'
                          end: '2024-07-12T16:00:00.000Z'
                        consideration:
                          currency: EUR
                          amount: 25.5
                        displayDate: '2024-07-12T10:30:00Z'
                        isCancellable: true
                        createdAt: '2024-07-12T10:30:00Z'
                limitOrder:
                  summary: Limit order response
                  value:
                    id: 64f5b3137fb3fc001234abce
                    category: AssetTransaction
                    status: Pending
                    orders:
                      - id: 64f5b3137fb3fc001234abcf
                        displayId: ORD-ABC12
                        isin: US0378331005
                        side: Buy
                        status: Pending
                        orderType: Limit
                        limitPrice:
                          currency: USD
                          amount: 150
                        expiresAt: '2026-07-28T12:00:00.000Z'
                        consideration:
                          currency: EUR
                          amount: 50
                        isCancellable: true
                        displayDate: '2024-07-12T10:30:00Z'
                        createdAt: '2024-07-12T10:30:00Z'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
components:
  parameters:
    XUserId:
      name: x-user-id
      in: header
      required: true
      description: >-
        User identifier for the M2M client to specify which user's data to
        access.
      schema:
        type: string
        pattern: ^[a-f0-9]{24}$
  schemas:
    SubmitAssetOrderRequest:
      description: >
        Asset order request. Exactly one branch applies:


        - **Market buy** — `side: buy`, `amount` required; `orderType` omitted
        or `Market`;
          optional `executeEtfOrdersInRealtime`. `limitPrice` and `timeInForce` are not allowed.
        - **Market sell** — `side: sell`, `quantity` required; same market rules
        as buy.

        - **Limit buy** — `side: buy`, `orderType: Limit`, `amount`,
        `limitPrice`, and `timeInForce`
          required. `executeEtfOrdersInRealtime` is not allowed.
        - **Limit sell** — `side: sell`, `orderType: Limit`, `quantity`,
        `limitPrice`, and `timeInForce`
          required. `executeEtfOrdersInRealtime` is not allowed.
      oneOf:
        - $ref: '#/components/schemas/MarketBuyAssetOrderRequest'
        - $ref: '#/components/schemas/MarketSellAssetOrderRequest'
        - $ref: '#/components/schemas/LimitBuyAssetOrderRequest'
        - $ref: '#/components/schemas/LimitSellAssetOrderRequest'
    AssetTransaction:
      type: object
      description: Asset transaction enriched with display-ready fields.
      required:
        - id
        - category
        - status
        - orders
      properties:
        id:
          type: string
        category:
          type: string
          enum:
            - AssetTransaction
        status:
          type: string
          description: >-
            Current transaction status (`Pending`, `PendingGift`, `Settled`,
            etc.).
        portfolioTransactionCategory:
          type: string
          enum:
            - update
            - buy
            - sell
        owner:
          type: string
          description: User identifier owning the transaction.
        portfolio:
          type: string
          description: Portfolio identifier associated with the transaction.
        consideration:
          type: object
          properties:
            currency:
              type: string
              description: Portfolio currency (EUR, GBP, USD, etc.).
            amount:
              type: number
              format: double
              description: Raw consideration amount in whole currency.
        executionWindow:
          allOf:
            - $ref: '#/components/schemas/ExecutionWindowsType'
          nullable: true
        orders:
          type: array
          items:
            $ref: '#/components/schemas/Order'
        fees:
          allOf:
            - $ref: '#/components/schemas/TransactionFees'
          nullable: true
        partnerFees:
          allOf:
            - $ref: '#/components/schemas/PartnerFees'
          nullable: true
          description: Present for partner users when countervalue fees apply.
    MarketBuyAssetOrderRequest:
      type: object
      description: Market buy order. `orderType` defaults to `Market` when omitted.
      required:
        - side
        - isin
        - amount
      properties:
        side:
          type: string
          enum:
            - buy
        isin:
          type: string
          description: ISIN of the asset to trade.
          pattern: ^[A-Z]{2}[A-Z0-9]{9}[0-9]$
        orderType:
          type: string
          description: Order type. Omit to default to market.
          enum:
            - Market
          default: Market
        amount:
          type: number
          format: double
          description: Whole-currency amount to invest.
          minimum: 0.01
        quantity:
          type: number
          format: double
          description: >-
            Optional. Ignored for buy orders; included for backward
            compatibility.
          minimum: 0.0001
        executeEtfOrdersInRealtime:
          type: boolean
          description: >-
            Optional override for ETF instruments. Only users flagged for
            real-time execution can set this to `true`.
      additionalProperties: false
    MarketSellAssetOrderRequest:
      type: object
      description: Market sell order. `orderType` defaults to `Market` when omitted.
      required:
        - side
        - isin
        - quantity
      properties:
        side:
          type: string
          enum:
            - sell
        isin:
          type: string
          description: ISIN of the asset to trade.
          pattern: ^[A-Z]{2}[A-Z0-9]{9}[0-9]$
        orderType:
          type: string
          description: Order type. Omit to default to market.
          enum:
            - Market
          default: Market
        quantity:
          type: number
          format: double
          description: Number of asset units to sell.
          minimum: 0.0001
        amount:
          type: number
          format: double
          description: >-
            Optional. Ignored for sell orders; included for backward
            compatibility.
          minimum: 0.01
        executeEtfOrdersInRealtime:
          type: boolean
          description: >-
            Optional override for ETF instruments. Only users flagged for
            real-time execution can set this to `true`. Selling ETFs as
            aggregated orders is rejected for real-time-enabled users.
      additionalProperties: false
    LimitBuyAssetOrderRequest:
      type: object
      description: Limit buy order.
      required:
        - side
        - isin
        - orderType
        - amount
        - limitPrice
        - timeInForce
      properties:
        side:
          type: string
          enum:
            - buy
        isin:
          type: string
          description: ISIN of the asset to trade.
          pattern: ^[A-Z]{2}[A-Z0-9]{9}[0-9]$
        orderType:
          type: string
          enum:
            - Limit
        amount:
          type: number
          format: double
          description: Whole-currency amount to invest.
          minimum: 0.01
        quantity:
          type: number
          format: double
          description: >-
            Optional. Ignored for buy orders; included for backward
            compatibility.
          minimum: 0.0001
        limitPrice:
          type: number
          format: double
          description: Price per unit in the asset's traded currency.
          minimum: 0.01
        timeInForce:
          $ref: '#/components/schemas/TimeInForce'
      additionalProperties: false
    LimitSellAssetOrderRequest:
      type: object
      description: Limit sell order.
      required:
        - side
        - isin
        - orderType
        - quantity
        - limitPrice
        - timeInForce
      properties:
        side:
          type: string
          enum:
            - sell
        isin:
          type: string
          description: ISIN of the asset to trade.
          pattern: ^[A-Z]{2}[A-Z0-9]{9}[0-9]$
        orderType:
          type: string
          enum:
            - Limit
        quantity:
          type: number
          format: double
          description: Number of asset units to sell.
          minimum: 0.0001
        amount:
          type: number
          format: double
          description: >-
            Optional. Ignored for sell orders; included for backward
            compatibility.
          minimum: 0.01
        limitPrice:
          type: number
          format: double
          description: Price per unit in the asset's traded currency.
          minimum: 0.01
        timeInForce:
          $ref: '#/components/schemas/TimeInForce'
      additionalProperties: false
    ExecutionWindowsType:
      type: object
      description: >-
        Execution windows separated by asset category (matches domain
        ExecutionWindowsType)
      properties:
        stocks:
          $ref: '#/components/schemas/ExecutionWindowType'
        etfs:
          $ref: '#/components/schemas/ExecutionWindowType'
      additionalProperties: false
    Order:
      type: object
      description: Order information including execution details and fees
      required:
        - id
        - displayId
        - isin
        - side
        - status
        - orderType
        - displayDate
        - isCancellable
      properties:
        id:
          type: string
        displayId:
          type: string
          description: User-friendly display identifier for the order (e.g., ORD-XXXXX)
          example: ORD-ABC12
        isin:
          type: string
        side:
          type: string
          enum:
            - Buy
            - Sell
        status:
          type: string
          enum:
            - Pending
            - Matched
            - Settled
            - Rejected
            - Cancelled
        orderType:
          type: string
          enum:
            - Market
            - Limit
          description: Order type (`Market` or `Limit`).
        quantity:
          type: number
          format: double
          description: Asset units (may be null for pending buy orders)
        executionWindow:
          allOf:
            - $ref: '#/components/schemas/ExecutionWindow'
          nullable: true
        consideration:
          type: object
          properties:
            currency:
              type: string
            amount:
              type: number
              format: double
        limitPrice:
          allOf:
            - $ref: '#/components/schemas/UnitPriceType'
          nullable: true
          description: Limit price per unit for limit orders
        expiresAt:
          type: string
          format: date-time
          nullable: true
          description: ISO datetime when a limit order expires
        fees:
          allOf:
            - $ref: '#/components/schemas/TransactionFees'
          nullable: true
        partnerFees:
          allOf:
            - $ref: '#/components/schemas/PartnerFees'
          nullable: true
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the order was created (optional)
        settledAt:
          type: string
          format: date-time
          nullable: true
          description: ISO datetime when the order settled or is expected to settle
        filledAt:
          type: string
          format: date-time
          nullable: true
          description: ISO datetime when order was matched
        displayDate:
          type: string
          format: date-time
          description: Display date (`filledAt` when matched, otherwise `createdAt`)
        isCancellable:
          type: boolean
          description: Whether the order can be cancelled by the user
        unitPrice:
          allOf:
            - $ref: '#/components/schemas/UnitPriceType'
          nullable: true
        fxRate:
          allOf:
            - $ref: '#/components/schemas/ExchangeRate'
          nullable: true
          description: Exchange rate used
    TransactionFees:
      type: object
      description: >-
        Wealthyhood fees on orders and settled transactions (commission, FX, and
        real-time execution when applicable).
      properties:
        commission:
          $ref: '#/components/schemas/FeeBreakdown'
        fx:
          $ref: '#/components/schemas/FeeBreakdown'
      additionalProperties: false
    PartnerFees:
      type: object
      description: >-
        ETE/NBG countervalue fees charged to partner users (sibling of
        Wealthyhood `fees`)
      properties:
        commission:
          $ref: '#/components/schemas/FeeBreakdown'
        fx:
          $ref: '#/components/schemas/FeeBreakdown'
      additionalProperties: false
    ApiErrorResponse:
      type: object
      properties:
        status:
          type: integer
        error:
          type: object
          properties:
            message:
              type: string
            description:
              type: string
              nullable: true
        responseId:
          type: string
          format: uuid
    TimeInForce:
      type: object
      required:
        - type
        - expiresAt
      properties:
        type:
          type: string
          enum:
            - goodTillDate
          description: Time-in-force type. Currently only `goodTillDate` is supported.
        expiresAt:
          type: string
          format: date-time
          description: >-
            ISO 8601 datetime when the limit order expires. Must be in the
            future and within 30 days.
      additionalProperties: false
    ExecutionWindowType:
      type: object
      description: Base execution window type matching domain structure
      properties:
        executionType:
          type: string
          enum:
            - REALTIME
            - MARKET_HOURS
          description: Internal execution type
        start:
          type: string
          format: date-time
          nullable: true
          description: Execution window start (ISO datetime)
        end:
          type: string
          format: date-time
          nullable: true
          description: Execution window end (ISO datetime)
      additionalProperties: false
    ExecutionWindow:
      type: object
      description: Execution timing communicated to the client.
      properties:
        executionType:
          type: string
          description: Internal execution type such as `REALTIME` or `MARKET_HOURS`.
        start:
          type: string
          format: date-time
          nullable: true
        end:
          type: string
          format: date-time
          nullable: true
      additionalProperties: true
    UnitPriceType:
      type: object
      description: Price per unit in major units (e.g. 200.00 for €200.00).
      properties:
        amount:
          type: number
          format: double
          description: Price per unit in major units (e.g. 200.00 for €200.00).
        currency:
          type: string
          description: ISO 4217 currency code
          enum:
            - GBP
            - EUR
            - USD
      additionalProperties: false
    ExchangeRate:
      type: object
      description: Exchange rate with currency information
      properties:
        rate:
          type: number
          format: double
          description: Exchange rate value
        currency:
          type: string
          description: ISO 4217 currency code
          enum:
            - GBP
            - EUR
            - USD
      additionalProperties: false
    FeeBreakdown:
      type: object
      properties:
        currency:
          type: string
        amount:
          type: number
          format: double
      additionalProperties: false
  responses:
    BadRequestError:
      description: Validation failure or business rule violation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorResponse'
          example:
            status: 400
            error:
              message: Target allocation is not set up for this portfolio
              description: Operation failed
            responseId: 3f0fd3bf-a2ff-4c0e-9b1d-5d7055dbf6cd
    UnauthorizedError:
      description: Missing or invalid bearer token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorResponse'
          example:
            status: 401
            error:
              message: User not found
            responseId: 145f2b0d-1d5b-4e91-8d0d-7af0ae9ad13a
    ForbiddenError:
      description: >-
        Authenticated user cannot act on the requested portfolio or lacks
        scopes.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorResponse'
          example:
            status: 403
            error:
              message: Portfolio does not belong to user
            responseId: 5e467f79-c62c-4d83-9810-7a0f8529fd76
    NotFoundError:
      description: Portfolio or related resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorResponse'
          example:
            status: 404
            error:
              message: Portfolio not found
            responseId: 65c0b1f6-2a48-4c4f-a5aa-9b9c8c6f9b58
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Auth0-issued access token that includes the scopes listed for the
        endpoint.

````