> ## 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.

# Preview portfolio buy

> Get a preview of a portfolio buy transaction showing execution options, fees, and estimated orders



## OpenAPI

````yaml POST /investments/portfolio/preview
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/portfolio/preview:
    post:
      tags:
        - Investments
      summary: Preview portfolio buy transaction
      description: >
        Get a preview of a portfolio buy transaction showing execution options,
        fees, and estimated orders.

        Returns preview data for both express (real-time) and smart (market
        hours) execution scenarios.


        The preview helps users understand:

        - Estimated fees (commission and FX)

        - Execution windows for both execution types

        - Estimated quantities per asset

        - Foreign currency rates
      parameters:
        - $ref: '#/components/parameters/XUserId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PortfolioPreviewRequest'
            examples:
              holdings:
                summary: Preview buy using current holdings
                value:
                  portfolioId: 64f0c51e7fb3fc001234abcd
                  orderAmount: 250.5
                  allocationMethod: holdings
      responses:
        '200':
          description: Portfolio buy preview retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionPreview'
              example:
                executionWindow:
                  express:
                    etfs:
                      executionType: REALTIME
                      start: '2024-07-12T13:00:00.000Z'
                      end: '2024-07-12T15:30:00.000Z'
                    stocks:
                      executionType: REALTIME
                      start: '2024-07-12T09:30:00.000Z'
                      end: '2024-07-12T16:00:00.000Z'
                  smart:
                    etfs:
                      executionType: MARKET_HOURS
                      start: '2024-07-12T13:00:00.000Z'
                      end: '2024-07-12T18:00:00.000Z'
                    stocks:
                      executionType: MARKET_HOURS
                      start: '2024-07-12T09:30:00.000Z'
                      end: '2024-07-12T16:00:00.000Z'
                fees:
                  express:
                    fx:
                      currency: EUR
                      amount: 0.22
                    commission:
                      currency: EUR
                      amount: 1
                  smart:
                    fx:
                      currency: EUR
                      amount: 0.22
                    commission:
                      currency: EUR
                      amount: 0.13
                partnerFees:
                  express:
                    fx:
                      currency: EUR
                      amount: 0.03
                    commission:
                      currency: EUR
                      amount: 1
                  smart:
                    fx:
                      currency: EUR
                      amount: 0.03
                    commission:
                      currency: EUR
                      amount: 1
                orders:
                  express:
                    - isin: US0378331005
                      side: Buy
                      quantity: 0.5
                      consideration:
                        currency: EUR
                        amount: 50
                  smart:
                    - isin: US0378331005
                      side: Buy
                      quantity: 0.5
                      consideration:
                        currency: EUR
                        amount: 50
                foreignCurrencyRates:
                  US0378331005:
                    rate: 1.1
                    currency: USD
        '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:
    PortfolioPreviewRequest:
      type: object
      required:
        - portfolioId
        - orderAmount
        - allocationMethod
      properties:
        portfolioId:
          type: string
          description: Portfolio identifier (MongoDB ObjectId)
          pattern: ^[a-f0-9]{24}$
        orderAmount:
          type: number
          format: double
          description: Amount to invest in whole currency units (e.g., 100.0 for 100 EUR)
          minimum: 0.01
        allocationMethod:
          type: string
          description: Method for distributing the investment across assets
          enum:
            - targetAllocation
            - holdings
      additionalProperties: false
    TransactionPreview:
      type: object
      description: >-
        Preview of a transaction showing execution options, fees, and estimated
        orders
      properties:
        executionWindow:
          $ref: '#/components/schemas/DualExecutionValueExecutionWindow'
        fees:
          $ref: '#/components/schemas/DualExecutionValueFees'
        partnerFees:
          $ref: '#/components/schemas/DualExecutionValuePartnerFees'
          description: >-
            Partner (ETE/NBG) countervalue fees per execution mode; omitted for
            retail Wealthyhood users.
        orders:
          $ref: '#/components/schemas/DualExecutionValueOrders'
        foreignCurrencyRates:
          type: object
          description: Foreign currency exchange rates keyed by ISIN
          additionalProperties:
            $ref: '#/components/schemas/ExchangeRate'
        willSkipOrders:
          type: boolean
          description: Whether orders will be skipped due to low amounts
        willResultInLowQuantityHolding:
          type: boolean
          description: Whether the transaction will result in a low quantity holding
        hasETFOrders:
          type: boolean
          description: Whether the transaction includes ETF orders
    DualExecutionValueExecutionWindow:
      type: object
      description: Execution window for both express and smart execution scenarios
      properties:
        express:
          $ref: '#/components/schemas/ExecutionWindowsType'
        smart:
          $ref: '#/components/schemas/ExecutionWindowsType'
      additionalProperties: false
    DualExecutionValueFees:
      type: object
      description: >-
        Wealthyhood fee breakdown for express vs smart execution (commission and
        FX only on preview)
      properties:
        express:
          $ref: '#/components/schemas/PreviewTransactionFees'
        smart:
          $ref: '#/components/schemas/PreviewTransactionFees'
      additionalProperties: false
    DualExecutionValuePartnerFees:
      type: object
      description: >-
        Partner countervalue fees for express vs smart execution (when
        applicable)
      properties:
        express:
          $ref: '#/components/schemas/PartnerFees'
        smart:
          $ref: '#/components/schemas/PartnerFees'
      additionalProperties: false
    DualExecutionValueOrders:
      type: object
      description: Orders preview for both express and smart execution scenarios
      properties:
        express:
          type: array
          items:
            $ref: '#/components/schemas/OrderPreview'
        smart:
          type: array
          items:
            $ref: '#/components/schemas/OrderPreview'
      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
    ApiErrorResponse:
      type: object
      properties:
        status:
          type: integer
        error:
          type: object
          properties:
            message:
              type: string
            description:
              type: string
              nullable: true
        responseId:
          type: string
          format: uuid
    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
    PreviewTransactionFees:
      type: object
      description: >-
        Wealthyhood fees exposed on transaction previews (commission and FX;
        real-time execution omitted).
      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
    OrderPreview:
      type: object
      description: Preview of an order showing estimated quantities and consideration
      required:
        - isin
        - side
        - orderType
        - quantity
        - consideration
      properties:
        isin:
          type: string
        side:
          type: string
          enum:
            - Buy
            - Sell
        orderType:
          type: string
          enum:
            - Market
            - Limit
          description: Order type (`Market` or `Limit`).
        quantity:
          type: number
          format: double
          description: Estimated quantity of asset units
        consideration:
          type: object
          properties:
            currency:
              type: string
            amount:
              type: number
              format: double
              description: Estimated consideration amount in whole currency units
          additionalProperties: false
        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
      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
    FeeBreakdown:
      type: object
      properties:
        currency:
          type: string
        amount:
          type: number
          format: double
      additionalProperties: false
    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
  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.

````