Skip to main content
Documentation Powered by Redocly

Download OpenAPI specification:Download

Authentication

Before you start making requests, you’ll need to generate an access token. Every request to the API must be authenticated using access tokens and user context headers — this ensures secure and authorized access to your resources.

Here are a few quick tips to help you integrate smoothly and keep your tokens active:

  • x-client-token: A tenant-level access token that expires after 24 hours. You can generate up to 3 tokens per hour.
  • Refresh Strategy: Generate a new token before the current one expires to keep your requests running without interruption.

Each endpoint’s required headers are outlined throughout this documentation, so you always know what’s needed to make a successful call.

Generate Access Token

This endpoint generates your access token, referred to as your x-client-token within Bamboo’s system. The credentials needed to generate it will be provided by the Bamboo Team during account setup.

header Parameters
content-type
required
string
Default: application/json

Acceptable content type

accept-language
required
string
Default: en

Acceptable language; 'en' for English

app-key
required
string
Example: 1755d3dd-e6b9-4df1-9537-eb9017da70g9

Application key that uniquely identifies a tenant as an API consumer.

Request Body schema: application/json

Tenant Level Authentication Request

username
required
string

Username

password
required
string

Password

Responses

Request samples

Content type
application/json
{
  • "username": "invest-bamboo",
  • "password": "32qC6I2U5J-0i73zJDEdapFJvwICJAl1I7ScekqupVfouiAMz_J7obWHI3kuDVOL"
}

Response samples

Content type
application/json
{
  • "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Ikx6aTZoUVRwc2gtS21BNjdzbXdCWiJ9.\neyJodHRwczovL2V4YW1wbGUuY29tL2NsYWltIjoiYmFyIiwiaXNzIjoiaHR0cHM6Ly9pbnZlc3RiYW1ib28uYXV0aDAuY29tLyIsInN1YiI6IjZWdUVjV1NFdUZWdGRJM1ExYlliRVV6UGZOVHljTkM4QGNsaWVudHMiLCJhdWQiOiJodHRwczovL3Bvd2VyZWQtYnktYmFtYm9vLXNhbmRib3guaW52ZXN0YmFtYm9vLmNvbS8iLCJpYXQiOjE3NTk1MDU1MzQsImV4cCI6MTc1OTU5MTkzNCwic2NvcGUiOiJyZWFkOmJhbWJvb19kYXRhIGV4dHJhIiwiZ3R5IjoiY2xpZW50LWNyZWRlbnRpYWxzIiwiYXpwIjoiNlZ1RWNXU0V1RlZ0ZEkzUTFiWWJFVXpQZk5UeWNOQzgifQ.\nF-bR5wEFxtD-3Y93Lzjfi2UY_9V9k8ckGkndhnLa-SXjp9GvitG79MSyUaNahvT6TVmFUw6Us59GhQAltlcETPoBk3wF934FbfGyofAPzsJ6j2mLIHY2YH-l4KO7_ZA9KAPeh8lGN24R5ZMLuDFGjbteNcHp_rCba1KhTYA_EJIL8p2zYsfYn72PAMb0pWUb5v9YC_HYNf95Q5bNHp0W0m7ZI21VwPVD0TRAazT931xCkF4d0oukvEmGkZ0ns8u1VxsZ0b2nUzV0K1YL6nBn68lg8b7lX7tLMReGUCxE_qsfI1vr0WYvQxCrmvjUsMFrDvW5oDlASa25WOcxYDWweQ\n",
  • "expires_in": 86400
}

Account Management

Account creation enables users to invest on Bamboo. Ensure KYC has been completed and each user’s identity verified before creating a brokerage account.

Best Practice: To avoid maintenance fees on inactive accounts, you're required to only send brokerage account creation requests when the user intends to make their first deposit. You may collect account details in advance, but delay sending the request until they're ready to deposit.

Prerequisites
  • Minimum Age: 18 years (verified via government-issued ID)
  • Compliance: Must meet local investment regulations
Document Requirements
Country Primary ID Image Requirements
Nigeria BVN Passport photo
Ghana National ID Front & back ID images
South Africa National ID Front & back ID images

Note: Images must be in Base64 format. The front_id_image and back_id_image fields apply only to Ghana and South Africa.

Phone Number Format
  • Must be in international format (e.g., +2347083864023)
  • Country code must match user’s residence
  • Used for notifications and account security

Create New User

This single endpoint helps you create brokerage accounts for your users. The required data below are used to determine user trading eligibility and are required by US regulations:

  • basic_info: Personal details, contact information, residence
  • verified_identity_info: Government ID verification data
  • affiliation_info: Professional associations, director roles
  • brokerage_account_info: Investment profile required to confirm US trading eligibility

A dictionary endpoint is provided below to give insight into all the questions and acceptable values for the fields within the payload.

Enabling Extended Hours at Account Creation

To enable Extended Hours trading for a user at the point of account creation, add the following field inside the brokerage_account_info object in your request payload:

"extended_hours_opt_in": "REQUESTED"

When this field is included, the user's account will be configured to support trading during pre-market and post-market sessions as soon as the account is active.

Note: You are not required to opt users in at account creation. Users are also able to opt out at any time using the Enable or Disable Extended Hours Trading endpoint.

header Parameters
content-type
required
string
Example: application/json

Acceptable content type

accept-language
required
string
Example: en

Acceptable language; 'en' for English

x-request-source
required
string

The tenant's username

x-client-token
required
string

API Consumer Authorisation Token

Request Body schema: application/json

Register credentials. (Provide details to subscribe to at least one market)

required
object (User basic info)
required
object (User verified identity info)
required
object (Affiliation info)
required
object (Brokerage account info)

Responses

Request samples

Content type
application/json
{
  • "basic_info": {
    },
  • "verified_identity_info": {
    },
  • "affiliation_info": {
    },
  • "brokerage_account_info": {
    }
}

Response samples

Content type
application/json
{
  • "expiration_time": 1697532406,
  • "jwt": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJ3ZWIiLCJleHAiOjE2OTc1MzI0MDYsImlhdCI6MTY5NDk0MDQwNiwiaXNzIjoid2ViIiwianRpIjoiMTE5MGRjMDEtZjQxNS00NmQ3LWFjOTctYzM5M2Y2MWEzYWJjIiwibmJmIjoxNjk0OTQwNDA1LCJyZXNpZGVuY2VfY291bnRyeSI6Ik5HQSIsInN1YiI6NTc3MSwidHlwIjoiYWNjZXNzIn0.GN3THXBJPynv0BcKuWKc84UHexAD22iGtO8A7kSjR92VKxLaiXxz0bDC-CEa8pVKum3oVwjjdRdAXeJL6c4Tsw",
  • "refresh_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJ3ZWIiLCJleHAiOjE2OTczNTk2MDYsImlhdCI6MTY5NDk0MDQwNiwiaXNzIjoid2ViIiwianRpIjoiYWQ4MDA2MzMtMWU4Ny00MGQ0LWFkMTMtNzc4YjY0M2JlNWQwIiwibmJmIjoxNjk0OTQwNDA1LCJyZXNpZGVuY2VfY291bnRyeSI6Ik5HQSIsInN1YiI6NTc3MSwidHlwIjoicmVmcmVzaCJ9.a5Vn2ApDrDBnroDk-7n3neJOuZPDOJxSP29V85rej_eKx4w0JiJ112-tghkSi3xijf0RSkw_AeVq-9sS7bjr0w",
  • "user": {
    }
}

Dictionary

Returns acceptable values for account creation fields, ensuring data validation and compliance with brokerage requirements.

Categories:

  • Employment Information – Status, type, industry, position.
  • Investment Profile – Experience, risk tolerance, goals.
  • Financial Information – Assets, source of wealth, marital status.

Usage:

  • Values are case-sensitive.
  • Validate user inputs against dictionary before account creation.
  • Update dictionary cache periodically.

Responses

Response samples

Content type
application/json
{
  • "assets_range": [
    ],
  • "employment_status": [
    ],
  • "employment_type": [
    ],
  • "experience": [
    ],
  • "goal": [
    ],
  • "marital_status": [
    ],
  • "position": [
    ],
  • "risk_tolerance": [
    ],
  • "source_of_wealth": [
    ]
}

View User Profile

Retrieve comprehensive user profile information including account restrictions statuses.

header Parameters
content-type
required
string
Example: application/json

Acceptable content type

accept-language
required
string
Example: en

Acceptable language; 'en' for English

x-user-id
required
string

Required for user authentication

x-subject-type
required
string

For user request -> 'tenant'.

x-client-token
required
string

API consumer token

Responses

Response samples

Content type
application/json
{
  • "surname": "Doe",
  • "street": "4383 Ms. Godspower Savage Squares, Ngaski Lagos",
  • "province": "Lagos State",
  • "postal_code": "+234",
  • "phone_number": "+2347083864023",
  • "next_of_kin": "Phil Doe",
  • "name": "John",
  • "gender": "Man",
  • "engagement_status": "no_trade",
  • "email_verified": false,
  • "email": "[email protected]",
  • "city": "Lekki",
  • "citizenship": "Nigeria",
  • "carrot_integration_status": "not_available",
  • "age": 96,
  • "account_restriction": {
    },
  • "account_number": "84861889"
}

View User Investment Profile

Access detailed investment profile information and brokerage account details.

header Parameters
content-type
required
string
Example: application/json

Acceptable content type

accept-language
required
string
Example: en

Acceptable language; 'en' for English

x-user-id
required
string

Required for user authentication

x-subject-type
required
string

For user request -> 'tenant'.

x-client-token
required
string

API consumer token

Responses

Response samples

Content type
application/json
{
  • "position": "ARTIST",
  • "marital_status": "SINGLE",
  • "employment_status": "UNEMPLOYED",
  • "company": "BAMBOO",
  • "employment_type": "MANAGEMENT",
  • "goal": "ACTIVE_DAILY",
  • "experience": "NONE",
  • "yearly_income": 12500,
  • "liquid": 12500,
  • "net_worth": 12500,
  • "risk_tolerance": "HIGH",
  • "dependents": 0,
  • "source_of_wealth": "SAVINGS"
}

Enable or Disable Extended Hours Trading

This endpoint enables you to give your users the option to enable or disable Extended Hours trading for their accounts.

Request Body schema: application/json
extended_hours_status
required
boolean

Boolean value indicating the desired extended hours status:

  • true → Sets status to ENABLED
  • false → Sets status to DISABLED
market
required
string

Market for which extended hours trading is being set.

Responses

Request samples

Content type
application/json
{
  • "extended_hours_status": true,
  • "market": "US"
}

Response samples

Content type
application/json
{
  • "message": "Extended hours status updated successfully.",
  • "extended_hours_status": "ENABLED"
}

Extended Hours Trading

Bamboo supports Extended Hours (X-Hrs) trading for US Stocks. This allows your users to buy and sell US stocks outside of regular market hours — during pre-market and post-market sessions. This gives users the ability to react to news, earnings, and market events as they happen.

Session Windows
Session Hours (ET) Description
Pre-Market 4:00 AM – 9:30 AM Trading before the regular session opens
Core Market 9:30 AM – 4:00 PM Regular trading hours
Post-Market 4:00 PM – 8:00 PM Trading after the regular session closes
Enabling X-Hours for Users

There are two ways to opt a user into Extended Hours trading:

See also: Place Order — for a full overview of stock eligibility, and order type rules when placing an X-Hr order.

Overview

Money movement is the backbone of investment operations, enabling users to fund their brokerage accounts and withdraw profits. Understanding the settlement process is critical for accurate integration and operational transparency.

How Settlement Works

The settlement process ensures verification, credit/debit updates, and proper brokerage processing:

  • Deposit/Withdrawal Requests: Notify Bamboo of user intent via our deposit and withdrawal endpoints.
  • Verification: Bamboo validates the transaction using your webhook verification endpoint.
  • Credit/Debit User: User accounts are updated once verification is successful; events are sent via Google Pub/Sub to confirm status.
  • Brokerage Processing: Our settlements team moves funds between brokerage and settlement accounts offline.
  • Funds Settlement: Actual money movement occurs offline. Engage Bamboo’s settlements team to establish procedures.

Deposits

Deposits fund user brokerage accounts for stock purchases. All deposits require verification through your webhook endpoint before funds are credited.

On the Portfolio endpoint, different cash fields serve specific purposes as explained below:

Field Description
cash Total cash in the user's brokerage account available for investment (buying power). Includes deposits, stock sales, cancelled and rejected trades.
unsettled_cash Funds from stock sales pending settlement; not yet available for withdrawal.
withdrawal_cash Settled funds available for withdrawal from the user brokerage account.
actual_value Total portfolio value, calculated as sum of US stock holdings, unsettled_cash, and cash balance.

Note: Your withdrawal_cash and unsettled_cash are components within your total cash balance. But those fields are used to specifically distinguish between cash settled/unsettled for withdrawal.

Create Deposit

To make a deposit, you send a notification request with the necessary details to credit the user's brokerage account. Upon receiving the request, a record is created in our system and verification checks are performed to confirm the deposit source.

Verification is carried out using an endpoint you provide to our integration team during account setup. Once the deposit is verified, the specified amount is credited to the user's brokerage account, and deposit status events are sent via Google Pub/Sub. (see details under events section)

Verification Endpoint Requirements:

  • Request Type: GET
  • URL Pattern: THE_URL/deposit/status/YOUR_UNIQUE_REFERENCE
  • Authentication: Static hash in headers (share this hash with Bamboo along with your verification URL)

Example JSON Webhook Response:

{
  "data": {
    "status": "settled", // or "failed"
    "currency": "NGN",
    "amount": 30000.00
  },
  "status": "settled" // or "failed"  
}

NB: You can also monitor all deposit activity through the PBB Dashboard.

header Parameters
content-type
required
string
Example: application/json

Acceptable content type

accept-language
required
string
Example: en

Acceptable language; 'en' for English

x-user-id
required
string

Required for user authentication

x-subject-type
required
string

For user request -> 'tenant'.

x-client-token
required
string

API Consumer Authorisation Token

x-request-source
required
string

The tenant's username

Request Body schema: application/json

Deposit request

amount_paid
required
number

Amount to be deposited

currency
required
string

Currency

provider
required
string

API Consumer Name

reference
required
string

Deposit reference

phone_number
required
string

User phone number

transaction_date
required
string

Date of creating the transaction

market
string

Either "US" or "NGX". It's used to specify desired stock market. If no market is specified, it defaults to US.

Responses

Request samples

Content type
application/json
{
  • "amount_paid": 5000,
  • "currency": "NGN",
  • "provider": "invest-bamboo",
  • "reference": "INVcal2VzeVGJkCXNx",
  • "phone_number": "+2348036477166",
  • "transaction_date": "2022-02-02",
  • "market": "US"
}

Response samples

Content type
application/json
""

Fetch All Deposits

Paginated list of all user deposits with date range filtering and status information

query Parameters
limit
string

Number of requested results default=20

next_token
integer

Next token for pagination

start_date
string

Unix datetime stamp

end_date
string

Unix datetime stamp

header Parameters
accept-language
required
string
Example: en

Acceptable language; 'en' for English

x-user-id
required
string

Required for user authentication

x-subject-type
required
string

For user request -> 'tenant'.

x-client-token
required
string

API Consumer Authorisation Token

x-request-source
required
string

The tenant's username

Responses

Response samples

Content type
application/json
{
  • "next_token": 10,
  • "deposits": [
    ]
}

Fetch User-Specific Deposits

Individual user deposits for performance tracking

query Parameters
limit
string

Number of requested results default=20

next_token
integer

Next token for pagination

start_date
string

Unix datetime stamp

end_date
string

Unix datetime stamp

header Parameters
accept-language
required
string
Example: en

Acceptable language; 'en' for English

x-user-id
required
string

Required for user authentication

x-subject-type
required
string

For user request -> 'tenant'.

x-client-token
required
string

API Consumer Authorisation Token

x-request-source
required
string

The tenant's username

Responses

Response samples

Content type
application/json
{
  • "next_token": 10,
  • "deposits": [
    ]
}

Deposit Status Check

Real-time status updates for specific deposit transactions

header Parameters
accept-language
required
string
Example: en

Acceptable language; 'en' for English

x-user-id
required
string

Required for user authentication

x-subject-type
required
string

For user request -> 'tenant'.

x-client-token
required
string

API Consumer Authorisation Token

x-request-source
required
string

The tenant's username

Responses

Response samples

Content type
application/json
{
  • "amount": 100.02,
  • "currency": "USD",
  • "status": "Settlemented",
  • "txref": "BIO63894410548a7f170d8159978UIO"
}

Withdrawals

Withdrawals allow users to extract funds from their brokerage accounts after successful trades. Understanding the settlement timeline is essential.

Settlement Timeline

  • Stock sale proceeds settle at T+1 business day.
  • unsettled_cash indicates funds that are pending settlement.
  • Once settled, funds move to withdrawal_cash and become available for withdrawal.

Remember that cash represents total funds in the user's brokerage account from all sources—deposits, stock sales, cancelled and rejected trades. All cash components (cash, unsettled_cash, withdrawal_cash) are available under the Portfolio endpoint.

Create Withdrawal

Withdrawal requests follow a similar verification flow as deposits. You send a notification request with the necessary details to debit the user's brokerage account, we verify that the user has the amount requested. Once verified, the specified amount is deducted from the user's brokerage account, and withdrawal status events are sent via Google Pub/Sub.

Offline settlement happens between our teams using established procedures. (see event details under withdrawal status events)

header Parameters
content-type
required
string
Example: application/json

Acceptable content type

accept-language
required
string
Example: en

Acceptable language; 'en' for English

x-user-id
required
string

Required for user authentication

x-subject-type
required
string

For user request -> 'tenant'.

x-client-token
required
string

API Consumer Authorisation Token

Request Body schema: application/json

tenant withdraw body parameter for NGN

currency
required
string

currency

amount
required
integer

amount

reference
required
string

reference

market
string

Either "US" or "NGX". It is used to specify desired stock market. If no market is specified, it defaults to US.

Responses

Request samples

Content type
application/json
{
  • "currency": "NGN",
  • "amount": 13400,
  • "reference": "INVKPxiJVc40BNaQBH",
  • "market": "US"
}

Response samples

Content type
application/json
""

Fetch All Withdrawals

Complete withdrawal history with date filtering

query Parameters
limit
string

Number of requested results default=20

next_token
integer

Next token for pagination

start_date
string

Unix datetime stamp

end_date
string

Unix datetime stamp

header Parameters
accept-language
required
string
Example: en

Acceptable language; 'en' for English

x-user-id
required
string

Required for user authentication

x-subject-type
required
string

For user request -> 'tenant'.

x-client-token
required
string

API Consumer Authorisation Token

x-request-source
required
string

The tenant's username

Responses

Response samples

Content type
application/json
{
  • "next_token": 10,
  • "withdrawals": [
    ]
}

Fetch User Withdrawals

Individual user withdrawal history for performance tracking

path Parameters
id
required
string

User ID

query Parameters
limit
string

Number of requested results default=20

next_token
integer

Next token for pagination

start_date
string

Unix datetime stamp

end_date
string

Unix datetime stamp

header Parameters
accept-language
required
string
Example: en

Acceptable language; 'en' for English

x-user-id
required
string

Required for user authentication

x-subject-type
required
string

For user request -> 'tenant'.

x-client-token
required
string

API Consumer Authorisation Token

x-request-source
required
string

The tenant's username

Responses

Response samples

Content type
application/json
{
  • "next_token": 10,
  • "withdrawals": [
    ]
}

Withdrawal Status Check

Real-time status checking for specific withdrawal transactions

path Parameters
reference
required
string

withdrawal reference

header Parameters
content-type
required
string
Example: application/json

Acceptable content type

accept-language
required
string
Example: en

Acceptable language; 'en' for English

x-user-id
required
string

Required for user authentication

x-subject-type
required
string

For user request -> 'tenant'.

x-client-token
required
string

API Consumer Authorisation Token

x-request-source
required
string

The tenant's username

Responses

Response samples

Content type
application/json
{
  • "status": "pending",
  • "reference": "INVKPxiJVc40BNaQBH",
  • "currency": "NGN",
  • "amount": 13400
}

Portfolio Reporting

The user's portfolio provides comprehensive views of investment performance, cash positions, and account status. Understanding the different cash types and portfolio calculations is essential for presenting accurate information to users.

Key Portfolio Terms

Cash Categories:

  • cash: Total cash in the user’s brokerage account available for investment (buying power). All funds from deposits, stock sales, and cancelled or rejected trades are credited here.
  • unsettled_cash: Funds from stock sale are accounted for here, pending when they settle into withdrawal_cash
  • withdrawal_cash: Settled cash available for withdrawal from a user brokerage account. (Funds settle here after successful stock sale)
  • actual_value: Total portfolio value—sum of US stock holdings, unsettled cash, and cash balance

Performance Metrics:

  • value: Current total portfolio value
  • value_change: Dollar change from previous close
  • value_percent_change: Percentage change from previous close
  • total_return: Lifetime gains/losses across all investments
  • total_invested: Cumulative amount invested by user

Fetch User Portfolio

This endpoint returns summarized information about a user's total portfolio value, gains and losses, cash positions, and pending deposits and withdrawals with regards to the US market.

The portfolio overview includes:
  • Current valuation: with real-time portfolio value and daily changes
  • Comprehensive cash positions: breaking down all cash types and availability
  • Currency conversion: showing values in both USD and the user's local currency
  • Deposit and withdrawal status: for pending money movement operations
  • Account restrictions: indicating any limitations on account activities
header Parameters
content-type
required
string
Example: application/json

Acceptable content type

accept-language
required
string
Example: en

Acceptable language; 'en' for English

x-user-id
required
string

Required for user authentication

x-subject-type
required
string

For user request -> 'tenant'.

currency
string

NGN - to get prices in Naira

x-client-token
required
string

API consumer token

Responses

Response samples

Content type
application/json
{
  • "withdrawal_cash": 0,
  • "withdraw_details": [
    ],
  • "value_percent_change": 0,
  • "value_change": 0,
  • "value": 0,
  • "user_currency_to_usd": 0.001152073732718894,
  • "user_currency_symbol": "₦",
  • "usd_to_user_currency": 868,
  • "usd_to_naira": 868,
  • "extended_hours_status": "ENABLED",
  • "unsettled_cash": 0,
  • "total_cash": 0,
  • "residence_country": "NGA",
  • "reserved_cash": 0,
  • "referral_cashback_blocked_value": 0,
  • "processing_withdrawal": 0,
  • "processing_gift_sent": 0,
  • "processing_gift_received": 0,
  • "pending_deposit": 0,
  • "naira_to_usd": 0.001152073732718894,
  • "dollar_cash": 0,
  • "dollar_balance": 0,
  • "currency_symbol": "₦",
  • "currency_name": "Nigerian Naira",
  • "currency_code": "NGN",
  • "cash": 0,
  • "carrot_held_value": 0,
  • "base_wallet_balance": 0,
  • "actual_value": 0,
  • "account_restricted": false
}

Fetch User Portfolio Breakdown

This endpoint provides information about the user's good faith violation status, account restrictions, money available for investment or withdrawal, and overall investment performance metrics.

Advanced portfolio analytics include:
  • Good faith violations: showing trading rule violation count and impact
  • Available to invest: Exact buying power for new trades
  • Withdrawable cash: showing funds eligible for withdrawal
  • Total return analysis: with comprehensive performance metrics
  • Equity Value: Current value of all stock holdings

Risk management information covers day trading restrictions based on account equity levels, violation tracking for pattern day trader rule compliance, and overall account health status.

header Parameters
content-type
required
string
Example: application/json

Acceptable content type

accept-language
required
string
Example: en

Acceptable language; 'en' for English

x-user-id
required
string

Required for user authentication

x-subject-type
required
string

For user request -> 'tenant'.

currency
string

NGN - to get prices in Naira

x-client-token
required
string

API consumer token

Responses

Response samples

Content type
application/json
{
  • "withdrawable_cash": 0,
  • "value": 0,
  • "total_return": 0,
  • "total_percent_change": 0,
  • "total_invested": 0,
  • "total_aum": 0,
  • "restricted_by_dw": false,
  • "number_of_violations": 0,
  • "equity_value": 0,
  • "currency_symbol": "$",
  • "base_wallet_balance": 0,
  • "available_to_invest": 0
}

Fetch User Ownership Details

This endpoint provides detailed ownership information about a specific stock that a user owns, including insights into portfolio performance since acquiring the stock.

Individual stock analysis covers:
  • Position size showing shares owned and current market value
  • Performance tracking with total return and daily return for the holding
  • Cost basis indicating average purchase price and total invested amount
  • Portfolio diversity percentage that this holding represents
  • Outstanding buy or sell orders for this stock

This data supports detailed stock performance analysis, portfolio rebalancing decisions, tax reporting and cost basis tracking, and individual position management.

header Parameters
content-type
required
string
Example: application/json

Acceptable content type

accept-language
required
string
Example: en

Acceptable language; 'en' for English

x-user-id
required
string

Required for user authentication

x-subject-type
required
string

For user request -> 'tenant'.

currency
string

NGN - to get prices in Naira

x-client-token
required
string

API consumer token

Responses

Response samples

Content type
application/json
{
  • "currency_symbol": "₦",
  • "ownership": {
    },
  • "pending_orders": [ ]
}

US Securities

The section provides comprehensive information about available US stocks, including real-time pricing, company details, and market data.

Stock themes also help users discover investment opportunities based on trends, sectors, and investment strategies. See the Featured Themes section for detailed information about theme-based stock discovery and categorization.

Fetch List of All Stocks

This endpoint fetches the list of stocks with basic information about them like their symbol and logo for building stock catalogs and search functionality.

Stock catalog features include:

  • Basic information: with symbol, company name, and logo imagery
  • Pagination support: for efficient loading of large stock universes
  • Search integration: providing foundation data for search functionality
  • High-quality company logos for UI integration

Integration considerations include caching stock lists to reduce API calls, updating periodically for new stock additions, and using pagination for optimal performance.

query Parameters
limit
string

Number of requested results. (Default = 20)

next_token
integer

Next token for pagination

header Parameters
x-user-id
string

Optional. User ID for user-specific requests.

x-subject-type
required
string

For user request -> 'tenant'.

x-client-token
required
string

API consumer token

Responses

Response samples

Content type
application/json
{}

Fetch Stock Details

This endpoint returns comprehensive details of a specific stock, including its pricing information, designed to provide users with in-depth insight into the stock.

Comprehensive stock information includes:

  • Real-time pricing: with current price, daily change, and percentage movement
  • Market data: showing volume, market cap, P/E ratio, and 52-week high/low
  • Company information: including business description, CEO, and sector classification
  • Investment story: with detailed analysis and investment thesis
  • Dividend information: showing yield and payment history
  • Earnings data: with historical earnings and upcoming dates

Enhanced features:

  • Support multi-currency pricing requests in local currency
  • ich content with company stories and investment analysis
  • Visual assets including company logos and brand colors for UI theming
  • Market context with industry comparisons and sector performance
  • Indicates that extended hours trading is active for that particular stock.

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

path Parameters
symbol
required
string

Stock Symbol

header Parameters
content-type
required
string
Example: application/json

Acceptable content type

accept-language
required
string
Example: en

Acceptable language; 'en' for English

x-user-id
required
string

Required for user authentication

x-subject-type
required
string

For user request -> 'tenant'.

x-client-token
required
string

API consumer token

x-request-source
required
string

The tenant's username

currency
string

NGN - to order in Naira

Responses

Response samples

Content type
application/json
{
  • "high": 257.9,
  • "low": 257.45,
  • "name": "Apple, Inc.",
  • "open": 257.86,
  • "symbol": "AAPL",
  • "logo": "https://d3an3cesqmrf1x.cloudfront.net/images/symbols/mdy.png",
  • "currency_symbol": "$",
  • "price": 257.85,
  • "avatar": "string",
  • "story": "When we talk about “the value of branding” and “brand investing”, you need look no further than Apple to understand how important and powerful a well-branded company can be... and how clearly that can be reflected in its share price.\r\n\r\nIn fact, in 2014, Interbrand determined Apple to be the world's most valuable brand and Forbes named Apple the most admired company in the world for five consecutive years.\r\n\r\nThat reputation carries over into each one of its products and services, including the iPhone, iPad, iPod, Mac computer, iTunes, iCloud and the Safari web browser.\r\n\r\nApple was founded by Steve Jobs, Steve Wozniak and Ronald Wayne on April Fools' Day of 1976. Their first product was the Apple 1 Personal Computer Kit and each one was painstakingly hand-built by Wozniak.\r\n\r\nBy the end of the 1970s, Apple had earned enough profits to bring on a full-time staff of computer designers and a legitimate production line.\r\n\r\nIn 1980, Apple went public and generated more capital than any IPO since Ford Motor Company did in 1956.\r\n\r\nIn January 1984, Apple grabbed the world's attention with the introduction of the Macintosh, changing personal computing forever.\r\n\r\nIn 1985, Steve Jobs was ousted, and went on to found NeXT, and also buy Pixar, and eventually returned as CEO in July 1997.\r\n\r\nIn August 1998, Jobs rejuvenated the stagnant Apple with the introduction of the iMac, stunning the tech industry.\r\n\r\nBy the end of 2001, a staple of Apple emerged, the iPod and iTunes, which later evolved into Apple Music. Apple also created the OS X software the same year, which was later used to power the iPhone, iPad, and Apple Watch.\r\n\r\nIn January 2007, Apple unveiled its first iPhone, and we all know how that story goes. Since then, Apple has sold more than 2 billion units. \r\n\r\nIn the following 3 years, the iPhone was improved, while the iPad and Apple TV were developed. \r\n\r\nIn 2011, Jobs, who had been diagnosed with pancreatic cancer, resigned as CEO and became chairman of the board. Tim Cook was named the new CEO in August of that year. Six weeks later, Jobs succumbed to his illness, and his death provoked widespread mourning as well as statements from Bill Gates, George Lucas and President Barack Obama.\r\n\r\nUnder Tim Cook’s leadership, the company has continued its astounding growth. In 2015, Apple released the Apple Watch, the first entirely new product in the post-Jobs era.\r\n\r\nIn 2016, Apple released the AirPods — a new wireless earphone. \r\n\r\nIn 2018, Apple became the first US company to be valued above $1 trillion.\r\n\r\nMarch 2019 - After more than four decades making money primarily by selling gadgets, Apple said it intended to expand efforts in monthly subscriptions. The company has expanded services in news, streaming, music, video-games and more. \r\n\r\nAs of 2020, the company’s wearables segment, including the Apple Watch and AirPods, had overtaken the Mac in revenue generation. The same year the company announced the Apple HomePod. \r\n\r\n_MyWallSt operates a full disclosure policy. MyWallSt staff hold long positions in this stock._",
  • "background_color": "ff9201",
  • "extended_hours_status": "active",
  • "percent_change": 1.4200000000000002,
  • "price_change": 2.8,
  • "earnings": [ ],
  • "avg_volume": 43464062,
  • "dividend_yield": 43464062,
  • "latest_update": 43464062,
  • "latest_volume": 43464062,
  • "market_cap": 2081325483000,
  • "pe_ratio": 2081325483000,
  • "wk_52_high": 2081325483000,
  • "wk_52_low": 2081325483000,
  • "short_description": "Apple is one of the world's largest companies. Its most well-known products are the iPhone, iPod and MAC computer. Apple is currently the world's most valuable brand.",
  • "about": {
    },
  • "categories": [ ],
  • "opinion": {
    },
  • "data_source": "Polygon.io, DriveWealth"
}

Search Stocks

This endpoint searches for a stock by a given query phrase or set of phrases, supporting advanced search capabilities with multiple filtering and sorting options.

The search functionality supports complex queries like filtering stocks between specific price ranges, performance thresholds, or market cap sizes, with predefined filters for top gainers, top losers, and user-owned stocks.

Advanced search capabilities include:

Query Options:

  • Text Search: Query by company names, stock symbols, ticker matching
  • Theme Filtering: Filter by investment themes and categories
  • Multi-Parameter: Combine text search with theme filters

Sorting Options:

  • Alphabetical: alphabetical:asc or alphabetical:desc
  • Price-Based: price:asc, percent_change:asc
  • Fundamentals: market_cap:asc, pe_ratio:asc, eps:asc
  • Trading Metrics: volume:asc, div_yield:asc

Advanced Filtering:

  • Price Ranges: price;a:10,price;b:50 (between $10-$50)
  • Performance: percent_change;a:5 (gaining above 5%)
  • Market Cap: market_cap;b:1000000000 (under $1B market cap)
  • Fundamentals: pe_ratio;a:15 (P/E ratio above 15)
  • Predefined Filters: top_gainers, top_losers, my_stocks

Example Usage:

GET /api/stock/search?query=apple&sorting=market_cap:desc&filters=price;a:100,my_stocks
query Parameters
query
required
string

Query phrase to match stock name or symbol

theme_id
string

Theme id to filter by. This takes only one value

sorting
string
Example: sorting=alphabetical:asc

Used to sort the search either by ascending order, descending order, etc. The acceptable values are stated in the description above.

filters
string
Example: filters=price;a:10, price;b:50

Used to filter the search by providing certain string values separated by a comma. The expected values to be passed for the filters param are stated in the description above.

header Parameters
content-type
required
string
Example: application/json

Acceptable content type

accept-language
required
string
Example: en

Acceptable language; 'en' for English

x-user-id
required
string

Required for user authentication

x-subject-type
required
string

For user request -> 'tenant'.

x-client-token
required
string

API consumer token

Responses

Response samples

Content type
application/json
{}

Fetch User Stock Ownership

This endpoint is used to get the list of stocks a user owns, providing a complete view of their current investment positions.

User portfolio stocks include:
  • Owned positions: showing all stocks currently held by the user
  • Position details: with share quantities, current values, and performance metrics
  • Equity breakdown: showing individual stock contributions to total portfolio
  • Multi-currency support: displaying local currency values with exchange rates

This endpoint supports portfolio management by tracking all user investments in one view, calculating portfolio diversity and concentration, monitoring individual position performance, and supporting portfolio rebalancing decisions.

header Parameters
content-type
required
string
Example: application/json

Acceptable content type

accept-language
required
string
Example: en

Acceptable language; 'en' for English

x-user-id
required
string

Required for user authentication

x-subject-type
required
string

For user request -> 'tenant'.

x-client-token
required
string

API consumer token

x-request-source
required
string

The tenant's username

currency
string

NGN - to order in Naira

Responses

Response samples

Content type
application/json
{
  • "currency_symbol": "$",
  • "equity_value": 2267.91,
  • "stocks": {
    }
}

US Stock Trading

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.

Trading Fundamentals

  • 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.
  • 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.
  • 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.
Order Types Behaviours Use Cases Risks Duration
Market Execute immediately at current market price When speed of execution matters more than exact price Price may move between order submission and execution Immediately during market open
Limit Execute only at specified price `Buy` at specific price below current market or `SELL` at a price higher than market price May never execute if price doesn't reach limit Good Till Canceled (GTC) or specific expiration date (default OF 90 days)
Stop Execute when stock reaches trigger price `Buy` at specific price above current market or `SELL` at a price lower than market price May never execute if price doesn't reach the set price Good Till Canceled (GTC) or specific expiration date (default OF 90 days)

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 calculate order endpoint to determine exact fees before order placement.

Calculate Order

This endpoint estimates the exact order cost, fees, and trade feasibility for the specified order type before execution.

It supports Market, Limit, and Stop order types and determines the precise values that should be used when placing an actual order.

The values returned guide what to send in the /api/order request.

Integration Flow:

  • First, call this endpoint to calculate the order.
  • Then, use the order_price from the calculation response as the total_price when placing the order.
  • All other response fields (e.g., price_per_share, quantity, fee) must be reused exactly as returned.

Developer Note:

  • Multiple example payloads are available below. Please switch to the relevant example (Market, Limit, or Stop) before copying and testing your request.
  • Market order calculation requires amount; Limit and Stop order calculation require price_per_share, price, and quantity.
  • 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).
header Parameters
content-type
required
string
Example: application/json

Advertises which content type is acceptable.

accept-language
required
string
Example: en

Advertises which languages the tenant is able to understand. For example, 'en' for English Language.

x-user-id
required
string

Required for user authentication

x-subject-type
required
string

For user request -> 'tenant'.

x-client-token
required
string

API Consumer Authorisation Token

x-request-source
required
string

The tenant's username

currency
string

NGN - to order in Naira

Request Body schema: application/json

Select the request payload that matches the desired order_type.

order_type
required
string

Market order calculation.

symbol
required
string

Stock ticker symbol

side
required
string
Enum: "buy" "sell"

BUY or SELL

amount
required
number
Default: 100000

Investment amount for a market order.

sell_all
boolean

set to true if the user wants to sell_all the shares they have for the specified stock symbol.

Responses

Request samples

Content type
application/json
Example
{
  • "order_type": "MARKET",
  • "symbol": "AAPL",
  • "side": "buy",
  • "amount": 100000
}

Response samples

Content type
application/json
{
  • "quantity": 38.22748653,
  • "currency_symbol": "$",
  • "price_per_share": 257.668,
  • "fee": 150,
  • "order_price": 9850,
  • "number_of_violations": 0,
  • "blocked_quantity": 0,
  • "gfv_occurs": false,
  • "total_price": 10000
}

Place Order

This is used to place an order using results from calculate order endpoint after confirming the user is eligible to make trades.

Placing an Extended Hours Order

To specify that an order should be executed during Extended Hours, include the following field in your request payload:

"extended_hours_order": true

Set this to false to restrict the order to core market hours only.

Supported Order Types

Every stock has a status during Extended Hours that determines which order types are supported. Each stock’s status is specified in the extended_hours_status field on the stock details endpoint.

As a tenant, ensure your UI reflects this to prevent invalid order attempts. Also, before placing an order, you should check the stock’s current status and ensure the order type selected is permitted.

See the Stock Status section below for details.

Stock Status Permitted Order Types Restrictions
Active Market & Limit Fractional and notional orders supported
Inactive Limit only Whole shares only — no fractional or notional
Close Only Limit or Market (sell side only) No buy orders permitted

Critical Requirements

  • Use order_price from calculate-order response as your total_price when placing your order
  • Reuse fee, quantity, and price_per_share from the calculate order response
  • For LIMIT/STOP orders, include the requested execution price
header Parameters
content-type
required
string
Example: application/json

Advertises which content type is acceptable.

accept-language
required
string
Example: en

Advertises which languages the tenant is able to understand. For example, 'en' for English Language.

x-user-id
required
string

Required for user authentication

x-subject-type
required
string

For user request -> 'tenant'.

x-client-token
required
string

API Consumer Authorisation Token

x-request-source
required
string

The tenant's username

currency
string

USD

Request Body schema: application/json

Select the request payload that matches the calculated order_type.

fee
required
number

Fee from the calculate order response.

order_type
required
string

Market order type.

quantity
required
number

Quantity returned from the calculate order response.

total_price
required
number

Use order_price from the calculate order response.

price_per_share
required
number

Price per share from the calculate order response.

side
required
string
Enum: "BUY" "SELL"

Order side.

symbol
required
string

Stock ticker symbol.

sell_all
boolean

Set to true if the user is selling all shares held for the stock.

Responses

Request samples

Content type
application/json
Example
{
  • "order_type": "MARKET",
  • "symbol": "AAPL",
  • "side": "BUY",
  • "quantity": 38.22748653,
  • "total_price": 9850,
  • "price_per_share": 257.668,
  • "fee": 150
}

Response samples

Content type
application/json
{
  • "order_id": "KJ.836a28cc-46ad-45d8-af25-a48812a9b7ae"
}

Fetch Order Status

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)
path Parameters
id
required
string

Order id

header Parameters
content-type
required
string
Example: application/json

Acceptable content type

accept-language
required
string
Example: en

Acceptable language; 'en' for English

x-user-id
required
string

Required for user authentication

x-subject-type
required
string

For user request -> 'tenant'.

x-client-token
required
string

API Consumer Authorisation Token

x-request-source
required
string

The tenant's username

Responses

Response samples

Content type
application/json
{}

View Pending Orders

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.

header Parameters
content-type
required
string
Example: application/json

Acceptable content type

accept-language
required
string
Example: en

Acceptable language; 'en' for English

x-user-id
required
string

Required for user authentication

x-subject-type
required
string

For user request -> 'tenant'.

x-client-token
required
string

API Consumer Authorisation Token

x-request-source
required
string

The tenant's username

currency
string

NGN - to get prices in Naira

Responses

Response samples

Content type
application/json
{
  • "pending_orders": [
    ],
  • "currency_symbol": "$"
}

Cancel Order

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.

path Parameters
id
required
string

Order id

header Parameters
content-type
required
string
Example: application/json

Acceptable content type

accept-language
required
string
Example: en

Acceptable language; 'en' for English

x-user-id
required
string

Required for user authentication

x-subject-type
required
string

For user request -> 'tenant'.

x-client-token
required
string

API Consumer Authorisation Token

x-request-source
required
string

The tenant's username

currency
string

NGN - to order in Naira

Responses

Response samples

Content type
application/json
"KJ.836a28cc-46ad-45d8-af25-a48812a9b7ae"

US Stock Events

Events within the Bamboo ecosystem signifies account or transaction status changes. Using Google Cloud Pub/Sub, we notify tenants of status changes in operations like brokerage account creation, deposits, withdrawals and trades.

This section outlines the events published to tenants through the Pub/Sub mechanism. To integrate this functionality, tenants are expected to subscribe to the designated Pub/Sub topic and utilize the provided JSON service account file to listen for published messages to ensure receipt of events. Please note that our product team will provide the necessary Pub/Sub topics and JSON service file during integration.

To find the right Google Cloud client library to use, refer to Cloud Client Libraries | Cloud APIs.

Brokerage Account Creation

When a user account is created on the PBB system, a brokerage account is also created for the user after the user details are verified, the possible statuses for a brokerage account creation request are provided in the table below.

When these status changes on the user account, events will be triggered. The user's account is ready for activities like deposits or placing trades when the Completed event is triggered.

Status Description Events available
Accepted User's brokerage account details have been received and a request has been sent for account creation. Yes
Completed User brokerage account is created and ready for trading Yes 
{
     event: "brokerage_account_update",
     payload: {
       "status": "Completed",
       "user_id": 12345
     }
   }

Deposit Event

To deposit money into your user's brokerage account, a deposit webhook is used and the deposit is verified through a service provided by your organisation during integration. Refer to the Deposits Section for more details.

All deposits are created with a default pending status and transition into the final states of the transaction after verification.

Deposit transactions status can also be verified or confirmed via a Deposit Status Check. The following are the valid transaction status in relation to Bamboo.

Funds are available for trading when the deposit status is “Settlemented”.

Status Description Events available
Accepted Payment has been received by Bamboo Yes
Pending Awaiting verification from Tenant Yes
awaiting_brokerage_account_activation Deposit verified, but awaiting brokerage account creation before it can be processed Yes
Sent to DW Deposit was successful sent to brokerage account. No
Settlemented Fund has been credited to brokerage account Yes
Failed The transaction exists with the Tenant but some information on their records like currency or amount does not match what we have. Yes
Deleted Reference doesn't exist (unable to verify from Tenant) Yes

Event Structure

{
     "event": "deposit_status_update",
     "paylaod": {
       "status": "accepted",
       "description": "USX_DEPOSIT",
       "reference": "TX987654321",
       "source_name": null,
       "currency": "NGN",
       "event": "deposit_status_update",
       "inserted_at": "2025-11-10T17:32:57",
       "updated_at": "2025-11-10T17:32:57",
       "provider": "tenant_username",
       "deposit_type": "instant",
       "payment_channel_id": 1,
       "exchange_rate": "867",
       "fee": "0.0",
       "dollar_fee": "0.0",
       "verified_amount": "0.0",
       "dollar_amount": "0.0",
       "amount_paid": "0.0",
       "dollar_instant_deposit_fee": "0.0",
       "dollar_processing_fee": "0.0",
       "reference_document": null
   }
  }

Withdrawal Event

Withdrawals are transactions that take funds out of the user's brokerage account. When a withdrawal request is created, it is depicted with a Requested status. Once the withdrawal is successfully initiated, Bamboo triggers a withdraw event using the payload structure defined below.

Withdrawal Initiation Event Structure

{
     "event": "withdraw",
     "paylaod": {
       "id": 33333,
       "reason": "USX_CAFW",
       "status": "Awaiting Broker",
       "reference": "reference",
       "currency": "NGN",
       "amount": "10000.0",
       "event": "withdraw",
       "inserted_at": "2025-11-21T12:38:43",
       "updated_at": "2025-11-21T12:39:38",
       "bank_address": "address",
       "account_number": "Not provided",
       "additional_instructions": "additional_instructions",
       "bank_code": "code",
       "bank_country": "country",
       "bank_name": "Not provided",
       "bank_state": "state",
       "bank_zip_code": "code",
       "beneficiary_name": "name",
       "intermediary_bank": "bank",
       "intermediary_bank_swift_code": "code",
       "swift_aba_code": "swift_aba_code",
       "fees": "0.0",
       "account_currency": "NGN",
       "exchange_rate_value": "1446.2",
       "bank_fw_id": null,
       "requested_by": "Tenant",
       "brokerage_withdrawal_request_id": "request_id"
   }
  }

A second event type "withdraw_status_update" is used to communicate changes to a withdrawal’s transaction state.

Status Update Event Structure

{
     event: "withdraw_status_update",
     payload: {
        "account_number": "1234567890",
        "additional_instructions": "Please process the withdrawal for this user",
        "amount": 1500.00,
        "bank_address": "123 Bank Street, Lagos, Nigeria",
        "bank_code": "123456",
        "bank_country": "NG",
        "bank_fw_id": "FW123456",
        "bank_name": "Guaranty Trust Bank",
        "bank_state": "Lagos",
        "bank_zip_code": "100001",
        "beneficiary_name": "Bamboo Global Inc",
        "brokerage_withdrawal_request_id": 987654321,
        "currency": "USD",
        "exchange_rate_value": 0.0027,
        "fees": 25.00,
        "requested_by": "Jane Doe",
        "intermediary_bank": "Intermediary Bank Name",
        "intermediary_bank_swift_code": "IBSWIFT123",
        "reason": "Personal expenses",
        "status": "sent",
        "reference": "WD123456789",
        "swift_aba_code": "SWIFT123456",
        "account_currency": "NGN"
      } 
  }

Below are the valid statuses a withdrawal can transition through within Bamboo.

Status Description Events available
Awaiting Broker Brokerage withdrawal successful initiated. Yes
Sent A.K.A Received From Broker. This means the customer’s brokerage account has been debited and funds credited to the tenant. This indicates a successful user withdrawal and is the only trigger for disbursing value. Yes
Rejected The withdrawal request failed and we couldn’t retrieve funds from the customer’s brokerage account. Yes

Trade Event

The process of buying and selling stocks triggers a number of events from trade initiation to its fulfillment or rejection.

When a trade is successfully created and acknowledged by the broker, Bamboo triggers a trade event with the structure shown below.

Successful Trade Creation Event

{
  "event": "trade",
  "payload": {
    "status": "New",
    "type": "MARKET",
    "user_id": 11111,
    "side": "BUY",
    "stock_symbol": "TEST",
    "order_id": "TT.test-1234567890"
  }
}

Bamboo additionally sends trade_status_update events to communicate status changes as the order transitions through its lifecycle.

Trade Status Update Event Structure

{
     event: "trade_status_update",
     payload: {
        "dollar_fee": 15.00,
        "dw_order_id": "ORD123456789",
        "naira_fee": 12000.00,
        "price_per_share": 50.75,
        "quantity": 100.00,
        "side": "buy",
        "status": "filled",
        "stock_symbol": "AAPL",
        "transaction_value": 5075.00,
        "type": "market",
        "user_currency_fee": 9000.00,
        "user_currency_price_per_share": 45.00,
        "user_currency_transaction_value": 4500.00,
        "rejection_reason": "Insufficient funds. NBNY179850 accountNo=BBSC000116        accountCash= 473.45 totalRequiredEquity= 473.46 commission=-3.29"
      }
   }

NB: Trade statuses can also be retrieved through an api call at any point from the time of placing the order using the FETCH Order Status endpoint.

The following are the set of trade events fired at the different status changes.

Trade Order Statuses & Available Events

Status Description Events available
New The order has been sent to the broker and its received Yes
Filled The order has been filled and should be visible on the Tenant app Yes
Cancelled The order has been canceled because the user canceled the request before it was processed. This can happen when an order is sent at the time the market is closed Yes
Rejected The order could not be executed and so it got rejected. Yes

Event Structure

{
     event: "trade_status_update",
     payload: {
        "dollar_fee": 15.00,
        "dw_order_id": "ORD123456789",
        "naira_fee": 12000.00,
        "price_per_share": 50.75,
        "quantity": 100.00,
        "side": "buy",
        "status": "filled",
        "stock_symbol": "AAPL",
        "transaction_value": 5075.00,
        "type": "market",
        "user_currency_fee": 9000.00,
        "user_currency_price_per_share": 45.00,
        "user_currency_transaction_value": 4500.00,
        "rejection_reason": "Insufficient funds. NBNY179850 accountNo=BBSC000116        accountCash= 473.45 totalRequiredEquity= 473.46 commission=-3.29"
      }
   }

Dividend Event

This event is used to communicate when a dividend has been paid for a stock that a user owns. See the sample event structure below:

Event Structure

{
 "event": "dividend_paid",
 "payload": {
   "amount": 10,
   "stock_symbol": "BPY",
   "stock_name": "Brookfield Property Partners L.P.",
   "user_id": "9283",
   "comment": "BPY dividend, $0.3043/share",
   "market": "US"
   }
 }

Market Activity

The market activity section provides you with endpoints that return the opening and closing times for markets we support, allowing you to check when market is open/closed.

This endpoint supports US Stock extended trading hours, allowing users to place trades during pre-market and post-market sessions in addition to regular market hours.

Response Fields

market_session - Indicates which market session is currently open:

  • pre_market - Pre-market session (4:00 AM to 9:30 AM ET)
  • core_market - Regular market hours (9:30 AM - 4:00 PM ET)
  • post_market - Post-market session (4:00 PM to 8:00 PM ET)

Each field returns a boolean value (true if that session is currently open, false otherwise).

open_date - Provides Unix timestamps for when each market session opens on the current trading day.

market_session_timestamp - Provides Unix timestamps indicating when each market session opens for the current day.

US Market Activity Status

This endpoint indicates whether the US market is open/close. Orders placed when market is closed are queued for the next trading session.

Market status information includes a boolean indicator for whether the market is currently active, Unix timestamp of the current market date, operating trading hours, and holiday schedule showing market closures on US federal holidays.

query Parameters
market
required
string

Market Type; US

header Parameters
content-type
required
string
Example: application/json

Acceptable content type

accept-language
required
string
Example: en

Acceptable language; 'en' for English

x-client-token
required
string

API consumer token

x-user-id
required
string

Required for user authentication

x-subject-type
required
string

For user request -> 'tenant'.

Responses

Response samples

Content type
application/json
{
  • "market_session": {
    },
  • "open_date": {
    },
  • "market_session_timestamp": {
    }
}

Exchange Rate

The exchange rate section provides you with an endpoint that fetches real-time exchange rates effortlessly, enabling accurate currency conversions and financial calculations.

Fetch Exchange Rate

Real-time exchange rate data enables accurate currency conversions for deposit, withdrawals and trade transactions.

Exchange rate data provides buy rates for converting USD to local currency when displaying prices, sell rates for converting local currency to USD when processing deposits, real-time updates with rates refreshed throughout the trading day, and support for multiple currencies including NGN, GHS, and ZAR.

Usage Guidelines:

  • If deposit is being made in local currency, use the sell rate for deposits.
  • Use the Buy rate for Withdrawals if withdrawal is being converted back to local currency.
  • Apply consistent rates across user sessions for pricing consistency
header Parameters
content-type
required
string
Example: application/json

Acceptable content type

accept-language
required
string
Example: en

Acceptable language; 'en' for English

x-client-token
required
string

API consumer token

Responses

Response samples

Content type
application/json
{
  • "exchange_rates": [
    ]
}

Featured Themes

Stocks are grouped into various categories which help users explore and filter stocks based on common themes, sectors, or other criteria. The endpoints in this section allow you to retrieve a list of categories that group different stocks together and also view details about these categories.

Fetch List of Themes

This is the endpoint to fetch the list of all Themed categories within our system.

header Parameters
content-type
required
string
Example: application/json

Acceptable content type

accept-language
required
string
Example: en

Acceptable language; 'en' for English

x-client-token
required
string

API Consumer Authorisation Token

x-request-source
required
string

The tenant's username

x-subject-type
required
string

If standard user -> 'standard’, if manager -> 'manager’.

Responses

Response samples

Content type
application/json
{}

View Theme Details

This endpoint is used to fetch an existing theme by its unique theme id.

query Parameters
featured
boolean

Featured Themes Flag

header Parameters
content-type
required
string
Example: application/json

Acceptable content type

accept-language
required
string
Example: en

Acceptable language; 'en' for English

x-client-token
required
string

API Consumer Authorisation Token

x-request-source
required
string

The tenant's username

x-subject-type
required
string

If standard user -> 'standard’, if manager -> 'manager’.

Responses

Response samples

Content type
application/json
{}

Financial Documents

Access various financial documents required for user account management, tax reporting, and regulatory compliance through secure document retrieval endpoints.

Document Types and Generation

The system generates three primary document categories to meet regulatory requirements and provide users with comprehensive account records.

Trade Confirmations:

  • Generation: Generated for users who have engaged in stock trades at the end of each trading day
  • Content: Trade details, execution prices, fees, settlement dates
  • Purpose: Legal confirmation of executed trades

Account Statements:

  • Generation: Generated at the end of each month
  • Content: Portfolio holdings, cash balances, transaction history
  • Purpose: Comprehensive account activity summary

Tax Documents:

  • Generation: Generated once, at the end of each year
  • Content: Realized gains/losses, dividend income, tax obligations
  • Purpose: Support user tax filing requirements

Fetch List of All Documents

Document retrieval begins with obtaining available document lists filtered by document type for efficient access to specific document categories.

Document Type Parameters:

  • confirms: Trade confirmation documents
  • statements: Monthly account statements
  • taxforms: Annual tax reporting documents

Document metadata includes unique file keys for document retrieval, generation dates showing when documents were created, coverage periods indicating date ranges covered by each document, and file formats with all documents provided as PDF files.

query Parameters
document_type
required
string

Used to state the type of document you want to download;

  • confirms for Trade Confirmations
  • statements for Account Statement
  • taxforms for Tax Documents
header Parameters
content-type
required
string
Example: application/json

Acceptable content type

accept-language
required
string
Example: en

Acceptable language; 'en' for English

x-client-token
required
string

API consumer token

x-user-id
required
string

Required for user authentication

x-subject-type
required
string

For user request -> 'tenant'.

Responses

Response samples

Content type
application/json
{
  • "documents": [
    ]
}

Fetch a Single Document

This endpoint is used to access individual document download URLs using unique file key identifiers gotten from the document_list endpoint.

Security features include expiring URLs where download links expire for security, IP restrictions limiting access to authorized requests, and user verification ensuring documents are only accessible by account owners.

query Parameters
file_key
required
string
Example: file_key=2024081901

File key gotten from the document list

header Parameters
content-type
required
string
Example: application/json

Acceptable content type

accept-language
required
string
Example: en

Acceptable language; 'en' for English

x-client-token
required
string

API consumer token

x-user-id
required
string

Required for user authentication

x-subject-type
required
string

For user request -> 'tenant'.

Responses

Response samples

Content type
application/json
{}