openapi: 3.0.1
info:
  title: Bamboo Account Management NG Securities 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 Securities
  description: "The section provides us endpoints that allows a client to fetch all the information pertaining to the NG stocks available on Bamboo. \n"
paths:
  /api/lsx/ng/stocks:
    get:
      tags:
      - NG Securities
      summary: Fetch List of All Stocks
      description: 'This endpoint fetches the list of stocks with basic information about them like their symbol and logo.

        '
      operationId: Web.Api.StockController.index
      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: limit
        in: query
        description: Number of requested results. (Default = 20)
        schema:
          type: string
      - name: next_token
        in: query
        description: Next token for pagination
        schema:
          type: integer
      - name: search_term
        in: query
        description: Stock symbol. E.g. `ZENITHBANK`
        schema:
          type: string
      responses:
        '200':
          description: Stock list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/lsxngstocks_response'
        '401':
          description: Token have expired or invalid token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
  /api/lsx/ng/stocks/{symbol}:
    get:
      tags:
      - NG Securities
      summary: Fetch Stock by Symbol
      description: 'This endpoint returns all the details of a specified stock. This is used to offer a user more insight into a specific  stock option.

        '
      operationId: Web.Api.StockDataController.about
      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: symbol
        in: path
        description: Stock Symbol
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Stock about info
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/lsxngstock_about_info'
        '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/my_stocks:
    get:
      tags:
      - NG Securities
      summary: Fetch List of All Stocks
      description: 'This endpoint fetches the list of stocks with basic information about them like their symbol and logo.

        '
      operationId: Web.Api.StockController.index
      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
      responses:
        '200':
          description: Stock list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/lsxngmy_stocks_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'
components:
  schemas:
    lsxngstock_about_info:
      title: Stock About Info
      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
        close_price:
          type: integer
          description: close_price
          example: 33.4
        description:
          type: string
          description: Stock name
          example: ZENITHBANK
        favourite:
          type: string
          description: Stock favourite
          example: false
        logo:
          type: string
          description: Stock logo URL
        market_cap:
          type: integer
          description: market_cap
          example: 0
        market_price:
          type: integer
          description: market_price
          example: 33.4
        name:
          type: string
          description: Stock name
          example: ZENITH BANK
        open_price:
          type: integer
          description: open_price
          example: 33.4
        percent_change:
          type: number
          description: Total percentage change
          example: 0
        symbol:
          type: string
          description: Stock symbol
          example: ZENITHBANK
        value_change:
          type: integer
          description: Equity value change
          example: 0
        volume:
          type: number
          description: volume
          example: 0
    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
    lsxngmy_stocks_response:
      title: Array of users NGX stocks
      type: object
      properties:
        total_user_equity:
          type: number
          description: total_user_equity
          example: 0
        stocks:
          type: array
          description: List of Stock
          items:
            title: Stock 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
              average_cost:
                type: integer
                description: average_cost
                example: 0
              cost_basis:
                type: integer
                description: cost_basis
                example: 0
              favourite:
                type: string
                description: Stock favourite
                example: false
              logo:
                type: string
                description: Stock logo URL
              market_cap:
                type: integer
                description: market_cap
                example: 0
              market_price:
                type: integer
                description: market_price
                example: 33.4
              name:
                type: string
                description: Stock name
                example: ZENITH BANK
              percent_change:
                type: number
                description: Total percentage change
                example: 0
              quantity:
                type: number
                description: Quantity
                default: 10
              symbol:
                type: string
                description: Stock symbol
                example: ZENITHBANK
              total_percent_change:
                type: number
                description: Total portfolio change
                example: 0
              total_return:
                type: number
                description: Total return
                example: 0
              value_change:
                type: integer
                description: Equity value change
                example: 0
              volume:
                type: number
                description: volume
                example: 0
    lsxngstocks_response:
      title: List of all active stocks response
      type: object
      properties:
        next_token:
          type: integer
          description: Next token for pagination
          example: 20
        stocks:
          type: array
          description: Stock response
          items:
            title: Stock 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
              close_price:
                type: integer
                description: close_price
                example: 33.4
              description:
                type: string
                description: Stock name
                example: ZENITHBANK
              favourite:
                type: string
                description: Stock favourite
                example: false
              logo:
                type: string
                description: Stock logo URL
              market_cap:
                type: integer
                description: market_cap
                example: 0
              market_price:
                type: integer
                description: market_price
                example: 33.4
              name:
                type: string
                description: Stock name
                example: ZENITH BANK
              open_price:
                type: integer
                description: open_price
                example: 33.4
              percent_change:
                type: number
                description: Total percentage change
                example: 0
              symbol:
                type: string
                description: Stock symbol
                example: ZENITHBANK
              value_change:
                type: integer
                description: Equity value change
                example: 0
              volume:
                type: number
                description: volume
                example: 0
    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.
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