openapi: 3.0.1
info:
  title: Bamboo Account Management NG 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: NG Stock Trading
  description: "The stock trading section details all the endpoints needed to calculate and make trade orders for all NG stock available  on Bamboo. Please note that trade charges are applicable and should be agreed upon with the business team. During system setup,  the agreed charges would be applied by the integration team. \n"
paths:
  /api/lsx/ng/order/calculate:
    post:
      tags:
      - NG Stock Trading
      summary: Calculate Order
      description: 'This endpoint is used to calculate an order request to help determine if a user can proceed with their desired BUY or SELL order.  Please note that the only order type you can place here is a Market Order.

        '
      operationId: Web.Api.OrderController.calculate_order
      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: currency
        in: header
        description: NGN - to order in Naira
        schema:
          type: string
      requestBody:
        description: Order params
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/lsxngcalculate_order'
        required: true
      responses:
        '200':
          description: Calculated order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/lsxngcalculate_order_response'
        '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/lsx/ng/order/:order_id:
    get:
      tags:
      - NG Stock Trading
      summary: Fetch Order Details by ID
      description: "This endpoint is used to fetch the details of an order. \n"
      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: order_id
        in: path
        description: Order id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Order status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/lsxngorder_details_response'
        '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/lsx/ng/order/:order_id/status:
    get:
      tags:
      - NG Stock Trading
      summary: Fetch Order Status by ID
      description: "This endpoint is used to fetch the status of an order. \n"
      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: order_id
        in: path
        description: Order id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Order status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/lsxngorder_status_response'
        '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/lsx/ng/pending_orders:
    get:
      tags:
      - NG Stock Trading
      summary: Fetch Pending Orders
      description: "This endpoint is used to fetch a list of pending orders. \n"
      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: order_id
        in: path
        description: Order id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Order status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/lsxngpending_order_response'
        '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/lsx/ng/order/:order_id/cancel:
    post:
      tags:
      - NG Stock Trading
      summary: Cancel An Order on the NGX
      description: 'This endpoint is used to cancel an order. Kindly note that only pending orders can be cancelled.

        '
      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: order_id
        in: path
        description: Order id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Cancel an order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/lsxngcancel_orders_response'
        '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'
components:
  schemas:
    lsxngorder_details_response:
      title: NGX Order details response
      type: object
      properties:
        avatar:
          type: string
          description: Theme avatar
          example: https://firebasestorage.googleapis.com/v0/b/bamboo-16d59.appspot.com/o/staging%2Fcategories%2FMost%20Popular.png1605885112566?alt=media&token=7300dc44-f067-4aec-a3a6-6e0498de775d
        dollar_fee:
          type: number
          description: Dollar Fee
          example: 0.42
        dollar_price_per_share:
          type: number
          description: Dollar equivalent of price for order
          example: 0.42
        execution_history:
          type: object
          properties:
            timestamp:
              type: number
              description: Timestamp
              example: string
            quantity:
              type: number
              description: Quantity requested
              example: 0
            idempotency_key:
              type: float
              description: idempotency_key
              example: 0
            amount:
              type: float
              description: Naira fee
              example: 0
        filled_quantity:
          type: number
          description: Quantity filled
          example: 0
        id:
          type: string
          description: Order ID
          example: BB.LAMB_21046bcd-0400-4ac1-a6a1-91c439455ef2
        logo:
          type: string
          description: Stock logo URL
        naira_fee:
          type: float
          description: Naira fee
          example: 33.15
        naira_order_price:
          type: number
          description: Naira price for order
          example: 364.65
        naira_price_per_share:
          type: number
          description: Naira price for order
          example: 0.42
        price:
          type: number
          description: Price
          example: 33.15
        quantity:
          type: number
          description: Quantity requested
          example: 10
        side:
          type: string
          description: Side; BUY or SELL
          example: BUY
        status:
          type: string
          description: Status
          example: Successful
        symbol:
          type: string
          description: Stock symbol to `BUY` or `SELL`
          default: DDD
        type:
          type: string
          description: 'Type: MARKET, STOP, LIMIT'
          example: MARKET
    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
    lsxngorder_status_response:
      title: NGX Order status response
      type: object
      properties:
        dollar_fee:
          type: number
          description: Dollar Fee
          example: 0.42
        dollar_price:
          type: number
          description: Dollar equivalent of price for order
          example: 0.42
        id:
          type: string
          description: Order ID
          example: BB.LAMB_21046bcd-0400-4ac1-a6a1-91c439455ef2
        naira_fee:
          type: float
          description: Naira fee
          example: 33.15
        naira_price:
          type: number
          description: Naira price for order
          example: 364.65
        price:
          type: number
          description: Price
          example: 33.15
        quantity:
          type: number
          description: Quantity requested
          example: 10
        side:
          type: string
          description: Side; BUY or SELL
          example: BUY
        status:
          type: string
          description: Status
          example: Successful
        symbol:
          type: string
          description: Stock symbol to `BUY` or `SELL`
          default: DDD
        type:
          type: string
          description: 'Type: MARKET, STOP, LIMIT'
          example: MARKET
    lsxngpending_order_response:
      title: NGX Pending Order Response
      type: object
      properties:
        pending_orders:
          type: array
          description: List of pending orders
          items:
            title: List of pending orders
            type: object
            properties:
              avatar:
                type: string
                description: Theme avatar
                example: https://firebasestorage.googleapis.com/v0/b/bamboo-16d59.appspot.com/o/staging%2Fcategories%2FMost%20Popular.png1605885112566?alt=media&token=7300dc44-f067-4aec-a3a6-6e0498de775d
              broker_code:
                type: string
                description: broker_code
                example: LABB
              created_at:
                type: integer
                description: Creation date in unix timestamp UTC
                example: 2022-02-02 01:10:20 UTC
              dollar_fee:
                type: number
                description: Dollar Fee
                example: 0.42
              dollar_price:
                type: number
                description: Dollar equivalent of price for order
                example: 0.42
              id:
                type: string
                description: Order ID
                example: BB.LAMB_21046bcd-0400-4ac1-a6a1-91c439455ef2
              logo:
                type: string
                description: Stock logo URL
              naira_fee:
                type: float
                description: Naira fee
                example: 33.15
              naira_price:
                type: number
                description: Naira price for order
                example: 364.65
              order_value:
                type: string
                description: Total price debited from the user including fee
                example: 1.01
              price:
                type: number
                description: Price for order
                default: 8
              price_per_share:
                type: number
                description: Price per share for all order
                default: 8.27
              quantity:
                type: number
                description: Quantity requested
                example: 10
              side:
                type: string
                description: Side; BUY or SELL
                example: BUY
              status:
                type: string
                description: Status
                example: Successful
              symbol:
                type: string
                description: Stock symbol to `BUY` or `SELL`
                default: DDD
              type:
                type: string
                description: 'Type: MARKET, STOP, LIMIT'
                example: MARKET
        currency_symbol:
          type: string
          description: Currency Symbol
          example: ₦
    lsxngcalculate_order:
      title: Calculate order request
      required:
      - type
      - symbol
      - side
      - quantity
      - price
      - currency
      type: object
      properties:
        type:
          type: string
          description: Order type options; MARKET
          default: MARKET
        symbol:
          type: string
          description: Stock symbol
          default: ZENITHBANK
        side:
          type: string
          description: ‘BUY’ or ‘SELL’
          default: BUY
        quantity:
          type: number
          description: whole number of stocks to buy or sell
          default: 10
        price:
          type: number
          description: Stop price or limit price
          default: 10
        currency:
          type: string
          description: Currency
          example: NGN
    lsxngcalculate_order_response:
      title: Calculated order response
      required:
      - currency
      - currency_symbol
      - fee
      - order_price
      - price_per_share
      - quantity
      - side
      - symbol
      - total_price
      - type
      type: object
      properties:
        currency:
          type: string
          description: Currency based on currency passed in header
          example: NGN
        currency_symbol:
          type: string
          description: Currency symbol based on currency passed in header
          example: ₦
        fee:
          type: integer
          description: calculated fees
          example: 33.15
        order_price:
          type: number
          description: calculated order price
          example: 331.5
        price_per_share:
          type: number
          description: Stock price per share
          example: 33.15
        quantity:
          type: number
          description: Calculated quantity
          example: 10
        side:
          type: string
          description: Market side, BUY or SELL
          example: BUY
        symbol:
          type: string
          description: Stock symbol
          example: ZENITHBANK
        total_price:
          type: number
          description: calculated total price
          example: 364.65
        type:
          type: boolean
          description: Trade type, MARKET, LIMIT or STOP
          example: null
    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.
    lsxngcancel_orders_response:
      title: Cancel an Order on the NGX
      required:
      - message
      type: object
      properties:
        message:
          type: sting
          description: Order cancellation message
          example: Order Cancelled
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