openapi: 3.0.1
info:
  title: Bamboo Account Management US Stock Trading API
  version: ''
  description: "Account creation enables users to invest on Bamboo. Ensure KYC has been completed and each user’s identity verified before creating a brokerage account.\n\n**Best Practice:** To avoid maintenance fees on inactive accounts, create and fund brokerage accounts **only when users initiate their first trade**. You may collect account details in advance but delay sending the request until they’re ready to buy.\n\n##### Prerequisites\n- **Minimum Age:** 18 years (verified via government-issued ID)\n- **Compliance:** Must meet local investment regulations\n\n##### Document Requirements\n<table>\n  <thead>\n    <tr>\n      <th>Country</th>\n      <th>Primary ID</th>\n      <th>Image Requirements</th>\n    </tr>\n  </thead>\n  <tbody>\n    <tr>\n      <th>Nigeria</th>\n      <td>BVN</td>\n      <td>Passport photo</td>\n    </tr>\n    <tr>\n      <th>Ghana</th>\n      <td>National ID</td>\n      <td>Front & back ID images</td>\n    </tr>\n    <tr>\n      <th>South Africa</th>\n      <td>National ID</td>\n      <td>Front & back ID images</td>\n    </tr>\n  </tbody>\n</table>\n\n**Note:** Images must be in Base64 format. The `front_id_image` and `back_id_image` fields apply only to Ghana and South Africa.\n\n##### Phone Number Format\n- Must be in international format (e.g., +2347083864023)\n- Country code must match user’s residence\n- Used for notifications and account security\n"
servers:
- url: https://powered-by-bamboo-sandbox.investbamboo.com
tags:
- name: US Stock Trading
  description: "Users can buy and sell US securities, with support for multiple order types and fractional shares. Understanding order calculations, execution timing, and fees is crucial for integration.\n### Trading Fundamentals\n- **Fractional Shares:** Users can buy/sell portions of expensive stocks (e.g., 0.1 shares of a $3,000 stock), with minimum investment of $1 today. *Note* that fractional shares are supported for only MARKET orders to enable portfolio diversification for users with smaller capital.\n- **Market Hours and Execution:** Bamboo supports trading during US Stock extended hours, allowing users to place trades during pre and post market sessions alongside the regular trading hours. Orders placed outside trading hours wait for market to open and no active session on US market holidays, but users are able to still send in their trade requests.\n- **Settlement and Cash Impact:** Trades settle T+1; i.e., trade date + 1 business days. Buy orders immediately reduce buying power, sale proceeds appear as unsettled cash immediately and become withdrawable after T+1, while failed orders return funds to buying power instantly.\n\n<table>\n  <thead>\n    <tr>\n      <th>Order Types</th>\n      <th>Behaviours</th>\n      <th>Use Cases</th>\n      <th>Risks</th>\n      <th>Duration</th>\n    </tr>\n  </thead>\n  <tbody>\n    <tr>\n      <td>Market</td>\n      <td>Execute immediately at current market price</td>\n      <td>When speed of execution matters more than exact price</td>\n      <td>Price may move between order submission and execution</td>\n      <td>Immediately during market open</td>\n    </tr>\n    <tr>\n      <td>Limit</td>\n      <td>Execute only at specified price</td>\n      <td>`Buy` at specific price below current market or `SELL` at a price higher than market price</td>\n      <td>May never execute if price doesn't reach limit</td>\n      <td>Good Till Canceled (GTC) or specific expiration date (default OF 90 days)</td>\n    </tr>\n    <tr>\n      <td>Stop</td>\n      <td>Execute when stock reaches trigger price</td>\n      <td>`Buy` at specific price above current market or `SELL` at a price lower than market price</td>\n      <td>May never execute if price doesn't reach the set price</td>\n      <td>Good Till Canceled (GTC) or specific expiration date (default OF 90 days)</td>\n    </tr>\n  </tbody>\n</table>\n\n**NB:** Trading fees apply to all order types, are deducted from the user’s cash balance (upfront for buy orders, from proceeds for sell orders), and vary based on partnership agreements; use the <a href=\"#tag/US-Stock-Trading/operation/Web.Api.OrderController.calculate_market_order\"> calculate order endpoint </a> to determine exact fees before <a href=\"#tag/US-Stock-Trading/operation/Web.Api.OrderController.place_market_order\"> order placement</a>.\n"
paths:
  /api/order/calculate:
    post:
      tags:
      - US Stock Trading
      summary: Calculate Order
      description: "This endpoint estimates the exact order cost, fees, and trade feasibility for the specified order type before execution.  \n\nIt supports **Market**, **Limit**, and **Stop** order types and determines the precise values that should be used when placing an actual order.\n\nThe values returned guide what to send in the `/api/order` request.\n\n**Integration Flow:**\n- First, call this endpoint to calculate the order.\n- Then, use the `order_price` from the calculation response as the `total_price` when placing the order.\n- All other response fields (e.g., `price_per_share`, `quantity`, `fee`) must be reused exactly as returned.\n\n**Developer Note:**  \n- Multiple example payloads are available below. Please **switch to the relevant example (Market, Limit, or Stop)** before copying and testing your request.\n- Recall that **Limit/Stop orders** are *Good Till Canceled (GTC)* or the set `expiration_date` (default of 90 days applies if no expiration is set).\n"
      operationId: Web.Api.OrderController.calculate_market_order
      parameters:
      - name: content-type
        in: header
        description: Advertises which content type is acceptable.
        example: application/json
        required: true
        schema:
          type: string
      - name: accept-language
        in: header
        description: Advertises which languages the tenant is able to understand. For example, 'en' for English Language.
        example: en
        required: true
        schema:
          type: string
      - name: x-user-id
        in: header
        description: Required for user authentication
        required: true
        schema:
          type: string
      - name: x-subject-type
        in: header
        description: For user request -> 'tenant'.
        required: true
        schema:
          type: string
      - name: x-client-token
        in: header
        description: API Consumer Authorisation Token
        required: true
        schema:
          type: string
      - name: x-request-source
        in: header
        description: The tenant's username
        required: true
        schema:
          type: string
      - name: currency
        in: header
        description: NGN - to order in Naira
        schema:
          type: string
      requestBody:
        description: Order Parameters (Select based on desired order_type)
        required: true
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/MarketOrderRequest'
              - $ref: '#/components/schemas/LimitOrderRequest'
              - $ref: '#/components/schemas/StopOrderRequest'
      responses:
        '200':
          description: Calculated order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CalculatedOrderResponse'
        '401':
          description: Token have expired or invalid token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
        '422':
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-codegen-request-body-name: body
  /api/order:
    post:
      tags:
      - US Stock Trading
      summary: Place Order
      description: 'This is used to place an order using results from calculate order endpoint after confirming the user is eligible to make trades.


        Bamboo supports trading during extended hours, to specify that you want your trade executed during extended hours, pass  `extended_hours_order`: `true` or `false` in your request payload.


        **Critical Requirements**

        - Use `order_price` from `calculate-order` response as your `total_price` when placing your order

        - For `LIMIT/STOP` orders, use `price_per_share` from order calculation response

        - **Note:** We currently only support LIMIT orders and whole unit trading during extended hours

        '
      operationId: Web.Api.OrderController.place_market_order
      parameters:
      - name: content-type
        in: header
        description: Advertises which content type is acceptable.
        example: application/json
        required: true
        schema:
          type: string
      - name: accept-language
        in: header
        description: Advertises which languages the tenant is able to understand. For example, 'en' for English Language.
        example: en
        required: true
        schema:
          type: string
      - name: x-user-id
        in: header
        description: Required for user authentication
        required: true
        schema:
          type: string
      - name: x-subject-type
        in: header
        description: For user request -> 'tenant'.
        required: true
        schema:
          type: string
      - name: x-client-token
        in: header
        description: API Consumer Authorisation Token
        required: true
        schema:
          type: string
      - name: x-request-source
        in: header
        description: The tenant's username
        required: true
        schema:
          type: string
      - name: currency
        in: header
        description: USD
        schema:
          type: string
      requestBody:
        description: Market order placement
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderStockRequest'
        required: true
      responses:
        '200':
          description: Order ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderStockIdResponse'
        '401':
          description: Token have expired or invalid token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFound'
        '422':
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-codegen-request-body-name: body
  /api/order/{id}/status:
    get:
      tags:
      - US Stock Trading
      summary: Fetch Order Status
      description: 'This endpoint is used to check the status of an order that has been placed, providing comprehensive details about order execution and current state.


        **Order status information includes:**

        - Order identification with unique order ID and stock details

        - Execution details showing order type, side (buy/sell), and quantity

        - Pricing information with execution price and total value

        - Fee breakdown in both USD and local currency

        - Current status and any status change reasons

        - Timestamps for order creation and updates


        **Order Status Types:**

        - **New:** Order received, awaiting execution

        - **Filled:** Order successfully executed, shares/cash updated

        - **Cancelled:** Order cancelled by the user before execution

        - **Rejected:** Order rejected by broker (invalid parameters like the price or quantity passed)

        '
      operationId: Web.Api.OrderController.status
      parameters:
      - name: content-type
        in: header
        description: Acceptable content type
        example: application/json
        required: true
        schema:
          type: string
      - name: accept-language
        in: header
        description: Acceptable language; 'en' for English
        example: en
        required: true
        schema:
          type: string
      - name: x-user-id
        in: header
        description: Required for user authentication
        required: true
        schema:
          type: string
      - name: x-subject-type
        in: header
        description: For user request -> 'tenant'.
        required: true
        schema:
          type: string
      - name: x-client-token
        in: header
        description: API Consumer Authorisation Token
        required: true
        schema:
          type: string
      - name: x-request-source
        in: header
        description: The tenant's username
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: Order id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Order status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderStatusResponse'
        '401':
          description: Token have expired or invalid token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFound'
        '422':
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/pending_orders:
    get:
      tags:
      - US Stock Trading
      summary: View Pending Orders
      description: 'This endpoint is used to check all pending orders made by users, displaying orders that are awaiting execution in the market.


        **Pending order management features:**

        - Active orders showing all LIMIT and STOP orders awaiting execution

        - Order specifications including trigger prices and expiration dates

        - Complete order details for user review


        This endpoint supports comprehensive order management by monitoring all pending orders across user portfolios, tracking order expiration dates and renewal needs, providing real-time order status updates to users, and enabling order cancellation functionality.

        '
      operationId: Web.Api.OrderController.pending
      parameters:
      - name: content-type
        in: header
        description: Acceptable content type
        example: application/json
        required: true
        schema:
          type: string
      - name: accept-language
        in: header
        description: Acceptable language; 'en' for English
        example: en
        required: true
        schema:
          type: string
      - name: x-user-id
        in: header
        description: Required for user authentication
        required: true
        schema:
          type: string
      - name: x-subject-type
        in: header
        description: For user request -> 'tenant'.
        required: true
        schema:
          type: string
      - name: x-client-token
        in: header
        description: API Consumer Authorisation Token
        required: true
        schema:
          type: string
      - name: x-request-source
        in: header
        description: The tenant's username
        required: true
        schema:
          type: string
      - name: currency
        in: header
        description: NGN - to get prices in Naira
        schema:
          type: string
      responses:
        '200':
          description: Pending orders
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PendingOrdersResponse'
        '401':
          description: Token have expired or invalid token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
        '422':
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/order/{id}/cancel:
    post:
      tags:
      - US Stock Trading
      summary: Cancel Order
      description: 'This endpoint is used to cancel a pending order before it executes, allowing users to modify their trading strategy.


        **Cancellation rules include:**

        - Pending orders can be cancelled for LIMIT and STOP orders before execution

        - You can only cancel market orders when market is closed because they usually execute too quickly to cancel during market hours

        - Executed orders cannot be cancelled once they have already filled

        - No fees are charged for order cancellation.


        Cash impact of cancellation involves reserved cash being released back to available buying power immediately, making funds available for other trades instantly.

        '
      parameters:
      - name: content-type
        in: header
        description: Acceptable content type
        example: application/json
        required: true
        schema:
          type: string
      - name: accept-language
        in: header
        description: Acceptable language; 'en' for English
        example: en
        required: true
        schema:
          type: string
      - name: x-user-id
        in: header
        description: Required for user authentication
        required: true
        schema:
          type: string
      - name: x-subject-type
        in: header
        description: For user request -> 'tenant'.
        required: true
        schema:
          type: string
      - name: x-client-token
        in: header
        description: API Consumer Authorisation Token
        required: true
        schema:
          type: string
      - name: x-request-source
        in: header
        description: The tenant's username
        required: true
        schema:
          type: string
      - name: currency
        in: header
        description: NGN - to order in Naira
        schema:
          type: string
      - name: id
        in: path
        description: Order id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Cancel Order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancelOrderStockIdResponse'
        '401':
          description: Token have expired or invalid token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFound'
        '422':
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-codegen-request-body-name: body
components:
  schemas:
    CancelOrderStockIdResponse:
      title: Order Cancelled
      type: string
      example: KJ.836a28cc-46ad-45d8-af25-a48812a9b7ae
    PendingOrdersResponse:
      title: List of pending orders
      required:
      - currency_symbol
      - pending_orders
      type: object
      properties:
        pending_orders:
          type: array
          description: Pending order list
          items:
            title: Pending order details
            required:
            - avatar
            - avg_price
            - background_color
            - created_at
            - creation_timestamp
            - id
            - limit_expiration
            - logo
            - name
            - number
            - order_price
            - price_per_share
            - quantity
            - side
            - status
            - symbol
            - type
            type: object
            properties:
              type:
                type: string
                description: 'Order type: Market, Limit, Stop'
              symbol:
                type: string
                description: Stock symbol
              status:
                type: string
                description: 'Order status: New, Partial Fill, Fill, Canceled, Rejected'
              side:
                type: string
                description: Order side Buy/Sell
              quantity:
                type: number
                description: Quantity of shares requested up to 6 decimal places
              price_per_share:
                type: number
                description: Price per 1.0 stock
              order_price:
                type: number
                description: Order price
              order_expiration_timestamp:
                type: integer
                description: Order expiration timestamp, unix UTC, for limit type only
              number:
                type: string
                description: Order number
              name:
                type: string
                description: Stock name
              logo:
                type: string
                description: Stock logo
              limit_expiration:
                type: string
                description: Expiration of order (limits only) ISO 8601
              id:
                type: string
                description: Order ID
              creation_timestamp:
                type: number
                description: Order creation date in UTC unix timestamp
              created_at:
                type: string
                description: Date in ISO 8601
              background_color:
                type: string
                description: Background color of stock in hex
              avg_price:
                type: number
                description: Average price
              avatar:
                type: string
                description: Stock avatar
        currency_symbol:
          type: string
          description: Prices currency symbol
          example: $
    Unauthorized:
      title: Unauthorized response
      required:
      - message
      type: object
      properties:
        message:
          type: string
          description: Unauthorized/Invalid Token/Token has expired
          example: Invalid client token supplied.
      description: Token is invalid or have expired
    LimitOrderRequest:
      type: object
      properties:
        order_type:
          type: string
          description: 'Order type options: `MARKET`, `LIMIT`, `STOP`'
          enum:
          - LIMIT
        symbol:
          type: string
          description: Stock ticker symbol
          example: AAPL
        side:
          type: string
          description: BUY or SELL
          enum:
          - buy
          - sell
        price_per_share:
          type: number
          description: Current price per share
          example: 9.13
        price:
          type: number
          description: Price at which the user wants their LIMIT or STOP orders to be executed
          example: 9.13
        quantity:
          type: number
          description: Specified quantity
          example: 100
        sell_all:
          type: boolean
          description: set to true if the user wants to sell_all the shares they have for the specified stock symbol.
          example: false
      required:
      - order_type
      - symbol
      - side
      - price_per_share
      - price
      - quantity
    MarketOrderRequest:
      type: object
      properties:
        order_type:
          type: string
          description: 'Order type options: `MARKET`, `LIMIT`, `STOP`'
          enum:
          - MARKET
        symbol:
          type: string
          description: Stock ticker symbol
          example: AAPL
        side:
          type: string
          description: BUY or SELL
          enum:
          - buy
          - sell
        amount:
          type: number
          description: Investment amount
          default: 100000
        sell_all:
          type: boolean
          description: set to true if the user wants to sell_all the shares they have for the specified stock symbol.
          example: false
      required:
      - order_type
      - symbol
      - side
      - amount
    OrderStockIdResponse:
      title: Order id response
      required:
      - order_id
      type: object
      properties:
        order_id:
          type: string
          description: Order ID to fetch status by REST
          example: KJ.836a28cc-46ad-45d8-af25-a48812a9b7ae
    OrderStatusResponse:
      title: Order status response
      type: object
      properties:
        id:
          type: string
          description: Order ID
          example: KJ.836a28cc-46ad-45d8-af25-a48812a9b7ae
        name:
          type: string
          description: Stock name
          example: 2U, Inc.
        type:
          type: string
          description: 'Type: Market, Stop, Limit'
          example: Market
        symbol:
          type: string
          description: Symbol
          example: TWOU
        logo:
          type: string
          description: Stock logo
          example: https://d3an3cesqmrf1x.cloudfront.net/images/symbols/twou.png
        quantity:
          type: number
          description: Quantity requested
          example: 9.70873786
        side:
          type: string
          description: Side Buy/Sell
          example: BUY
        dollar_fee:
          type: float
          description: dollar fee
          example: 1
        price:
          type: number
          description: Price
          example: 2.06
        avatar:
          type: string
          description: Stock avatar url
          example: https://firebasestorage.googleapis.com/v0/b/bamboo-16d59.appspot.com/o/staging%2Fstocks%2Fimage.png1668765461965?alt=media&token=6467a544-ddd2-4b0d-8e5a-4c4ef4d70510
        naira_fee:
          type: float
          description: naira fee
          example: 868.8
        background_color:
          type: string
          description: Background color of stock in hex
          example: '121212'
        order_status:
          type: string
          description: Order status
          example: Filled
        dollar_price:
          type: float
          description: dollar price
          example: 20
        naira_price:
          type: float
          description: naira price
          example: 17360
        limit_price:
          type: number
          description: Limit price
          example: 0
        stop_price:
          type: number
          description: Stop price
          example: 0
        commision:
          type: float
          description: Orderd commision
          example: 1
        created_when:
          type: string
          description: Date in ISO 8601
          example: '2023-10-25T15:28:26.779Z'
        update_reason:
          type: string
          description: Update reason if order was Rejected
          example: market_order-buy-filled
    ErrorResponse:
      title: Error response
      required:
      - message
      type: object
      properties:
        message:
          type: string
          description: Error response for external or internal errors not connected to data
          example: Message why request didn't succeed
      description: Error response for external or internal errors not connected to data
    ResourceNotFound:
      title: Resource not found
      required:
      - message
      type: object
      properties:
        message:
          type: string
          description: Resource not found (an incorrect url may have been used)
          example: Resource Not Found
      description: Error response for when the resource is not found within our data.
    OrderStockRequest:
      title: Order Placement Parameters
      required:
      - fee
      - order_type
      type: object
      properties:
        fee:
          type: number
          description: Fee from calculate order response for all order types
          default: 150
        order_type:
          type: string
          description: 'Order type options: `MARKET`, `STOP`, `LIMIT`'
          default: MARKET
        quantity:
          type: number
          description: 'Order quantity or number of shares. NB: Fractional shares not allowed for LIMT and STOP Orders.'
          default: 38.22748653
        total_price:
          type: number
          description: Order price returned from the calculate order response
          default: 9850
        price:
          type: number
          description: Price per share from the calculate order response. Used for only LIMIT and STOP Orders
          default: 257.668
        price_per_share:
          type: number
          description: Price per share from the calculate order response
          default: 257.668
        side:
          type: string
          description: 'Order side options: `BUY` or `SELL`'
          default: BUY
        symbol:
          type: string
          description: Stock ticker symbol
          default: AAPL
        sell_all:
          type: boolean
          description: set to true if the user is trying to sell_all the shares they have for that particular stock.
          example: false
        expiration:
          type: string
          description: Used to set expiration date for `LIMIT` or `STOP` orders
          default: 90 Days if no date is set
          example: '2025-06-13'
        extended_hours_order:
          type: boolean
          description: Set to true if the user wants their trade executed during extended hours. This only supports LIMIT orders and whole unit trading during extended hours.
          example: false
    CalculatedOrderResponse:
      title: Calculated order response
      required:
      - fee
      - order_price
      - total_price
      - blocked_quantity
      - quantity
      - currency_symbol
      - gfv_occurs
      - number_of_violations
      - price_per_share
      type: object
      properties:
        quantity:
          type: number
          description: Calculated quantity
          example: 38.22748653
        currency_symbol:
          type: string
          description: Currency symbol based on currency passed in header
          example: $
        price_per_share:
          type: number
          description: Price Per Share for all order
          format: float
          example: 257.668
        fee:
          type: integer
          description: calculated fees
          example: 150
        order_price:
          type: number
          description: calculated order price
          example: 9850
        number_of_violations:
          type: integer
          description: Number of violations
          example: 0
        blocked_quantity:
          type: number
          description: Blocked quantity for position
        gfv_occurs:
          type: boolean
          description: GFV occurs
          example: false
        total_price:
          type: number
          description: calculated total price
          example: 10000
    StopOrderRequest:
      type: object
      properties:
        order_type:
          type: string
          description: 'Order type options: `MARKET`, `LIMIT`, `STOP`'
          enum:
          - STOP
        symbol:
          type: string
          description: Stock ticker symbol
          example: AAPL
        side:
          type: string
          description: BUY or SELL
          enum:
          - buy
          - sell
        price_per_share:
          type: number
          description: Current price per share
          example: 9.13
        price:
          type: number
          description: Price at which the user wants their LIMIT or STOP orders to be executed
          example: 9.13
        quantity:
          type: number
          description: Specified quantity
          example: 100
        sell_all:
          type: boolean
          description: set to true if the user wants to sell_all the shares they have for the specified stock symbol.
          example: false
      required:
      - order_type
      - symbol
      - side
      - price_per_share
      - price
      - quantity
x-logo:
  url: bamboo-logo.png
  altText: bamboo logo
x-tagGroups:
- name: Authentication
  tags:
  - Authentication
  - Account Management
- name: Money Movement
  tags:
  - Overview
  - Deposits
  - Withdrawals
- name: US Brokerage Services
  tags:
  - Portfolio Reporting
  - US Securities
  - US Stock Trading
  - US Stock Events
- name: Utilities
  tags:
  - Dictionaries
  - Market Activity
  - Exchange Rate
  - Featured Themes
  - Financial Documents