> ## 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 asset buy or sell

> Get a preview of a single asset buy or sell transaction showing execution options, fees, and estimated orders



## OpenAPI

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

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

        orders. **Limit** orders are always express (smart is omitted).


        **Order type:** Omit `orderType` or set it to `Market` for market
        previews; set `orderType: Limit` with

        `limitPrice` and `timeInForce` for limit previews (same field rules as
        submit order).


        **For buy orders**: Specify `isin`, `amount`, and `side: "buy"`

        **For sell orders**: Specify `isin`, `quantity`, and `side: "sell"`


        The preview helps users understand:

        - Estimated fees (commission and FX)

        - Execution windows for both execution types (market) or express only
        (limit)

        - Estimated quantity (for buys) or consideration amount (for sells)

        - Foreign currency rates

        - Limit price and expiry for limit orders
      parameters:
        - $ref: '#/components/parameters/XUserId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssetPreviewRequest'
            examples:
              buyOrder:
                summary: Preview market asset buy order
                value:
                  isin: US0378331005
                  amount: 25.5
                  side: buy
              sellOrder:
                summary: Preview market asset sell order
                value:
                  isin: IE00B4L5Y983
                  quantity: 1.25
                  side: sell
              limitBuyOrder:
                summary: Preview limit asset buy order
                value:
                  isin: US0378331005
                  side: buy
                  orderType: Limit
                  amount: 50
                  limitPrice: 150
                  timeInForce:
                    type: goodTillDate
                    expiresAt: '2026-07-28T12:00:00.000Z'
              limitSellOrder:
                summary: Preview limit asset sell order
                value:
                  isin: US0378331005
                  side: sell
                  orderType: Limit
                  quantity: 2
                  limitPrice: 200
                  timeInForce:
                    type: goodTillDate
                    expiresAt: '2026-07-28T12:00:00.000Z'
      responses:
        '200':
          description: Asset transaction preview retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionPreview'
              examples:
                buyPreview:
                  summary: NBG foreign stock buy (€800)
                  value:
                    executionWindow:
                      express:
                        stocks:
                          executionType: MARKET_HOURS
                          start: '2024-07-12T09:30:00.000Z'
                          end: '2024-07-12T16:00:00.000Z'
                    fees:
                      express:
                        fx:
                          currency: EUR
                          amount: 3.6
                        commission:
                          currency: EUR
                          amount: 0
                    partnerFees:
                      express:
                        fx:
                          currency: EUR
                          amount: 0.4
                        commission:
                          currency: EUR
                          amount: 2
                    orders:
                      express:
                        - isin: US0378331005
                          side: Buy
                          orderType: Market
                          quantity: 4.4529
                          consideration:
                            currency: EUR
                            amount: 800
                    foreignCurrencyRates:
                      US0378331005:
                        rate: 1.1
                        currency: USD
                sellPreview:
                  summary: NBG foreign stock sell (1 × €12.51 gross)
                  value:
                    executionWindow:
                      express:
                        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.05
                        commission:
                          currency: EUR
                          amount: 0
                    partnerFees:
                      express:
                        fx:
                          currency: EUR
                          amount: 0.01
                        commission:
                          currency: EUR
                          amount: 1
                    orders:
                      express:
                        - isin: US0378331005
                          side: Sell
                          orderType: Market
                          quantity: 1
                          consideration:
                            currency: EUR
                            amount: 11.51
                    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:
    AssetPreviewRequest:
      description: >
        Asset preview request. `orderType` defaults to `Market` when omitted.
        Limit orders are always

        express (no smart/aggregate leg).


        - **Market buy** — `side: buy`, `amount` required; `orderType` omitted
        or `Market`;
          `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.
        - **Limit sell** — `side: sell`, `orderType: Limit`, `quantity`,
        `limitPrice`, and `timeInForce`
          required.
      oneOf:
        - $ref: '#/components/schemas/MarketBuyAssetPreviewRequest'
        - $ref: '#/components/schemas/MarketSellAssetPreviewRequest'
        - $ref: '#/components/schemas/LimitBuyAssetPreviewRequest'
        - $ref: '#/components/schemas/LimitSellAssetPreviewRequest'
    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
    MarketBuyAssetPreviewRequest:
      type: object
      description: Market buy preview. `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: Required when `side` is `buy`. 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
      additionalProperties: false
    MarketSellAssetPreviewRequest:
      type: object
      description: Market sell preview. `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: Required when `side` is `sell`. 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
      additionalProperties: false
    LimitBuyAssetPreviewRequest:
      type: object
      description: Limit buy preview. Limit orders are always express.
      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
    LimitSellAssetPreviewRequest:
      type: object
      description: Limit sell preview. Limit orders are always express.
      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
    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
    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
    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.

````