Govern

Architecture & Custody

MyStocks Partner API

What happens between your POST /trade and settled units on an African exchange — who executes, who holds the assets, where the cash sits, and how MyStocks reconciles omnibus custody against per-sub-account holdings.

Integration guides Get a sandbox key

Explore endpoints

12 of 12

GET

/users/{userId}/buying-power

Sub-account buying power (settlement-aware)

Full endpoint documentation

Sandbox availablegetSubAccountBuyingPower

Settlement-aware balance for a sub-account. buyingPowerUsd is cash available to trade (unsettled SELL proceeds are usable for new buys, as is standard). withdrawableUsd excludes unsettled SELL proceeds, which remain locked until exchange settlement (T+N) — this is the free-riding guard. settlements[] lists each unsettled tranche and its settlement date.

Parameters

userIdstringpathRequired

Example: usr_abc123

Headers

AuthorizationstringRequired

Bearer sk_sandbox_<your_key> for sandbox requests.

Response fields

accountTypeMASTER | SUBACCOUNT

subAccountIdstring | null

currencystring

Example: "USD"

cashBalanceUsdnumber

Current USD wallet balance.

buyingPowerUsdnumber

Cash available to place new orders (already net of open-BUY escrow; includes unsettled SELL proceeds).

unsettledUsdnumber

SELL proceeds credited but not yet settled at the exchange (T+N).

withdrawableUsdnumber

Cash available to withdraw — cashBalanceUsd minus unsettledUsd. The free-riding guard.

pendingBuyEscrowUsdnumber

Funds locked in open (PENDING) BUY orders.

settlementsobject[]

settlements[].amountUsdnumber

settlements[].settlesOnstring

settlements[].symbolstring | null

settlements[].exchangestring | null

settlements[].orderIdstring | null

Response codes

200Settlement-aware balance.

404Sub-account not found.

Sandbox playground

Read-only sandbox request

userId Required · pathSandbox API keyYour key stays in this page’s memory.

https://mystocks.africa/api/sandbox/v1/partner/users/%7BuserId%7D/buying-power

Open in API Tester API Reference

Response schema

{
  "type": "object",
  "description": "Settlement-aware balance for a master or sub-account.",
  "properties": {
    "accountType": {
      "type": "string",
      "enum": [
        "MASTER",
        "SUBACCOUNT"
      ]
    },
    "subAccountId": {
      "type": [
        "string",
        "null"
      ]
    },
    "currency": {
      "type": "string",
      "example": "USD"
    },
    "cashBalanceUsd": {
      "type": "number",
      "description": "Current USD wallet balance."
    },
    "buyingPowerUsd": {
      "type": "number",
      "description": "Cash available to place new orders (already net of open-BUY escrow; includes unsettled SELL proceeds)."
    },
    "unsettledUsd": {
      "type": "number",
      "description": "SELL proceeds credited but not yet settled at the exchange (T+N)."
    },
    "withdrawableUsd": {
      "type": "number",
      "description": "Cash available to withdraw — cashBalanceUsd minus unsettledUsd. The free-riding guard."
    },
    "pendingBuyEscrowUsd": {
      "type": "number",
      "description": "Funds locked in open (PENDING) BUY orders."
    },
    "settlements": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "amountUsd": {
            "type": "number"
          },
          "settlesOn": {
            "type": "string",
            "format": "date-time"
          },
          "symbol": {
            "type": [
              "string",
              "null"
            ]
          },
          "exchange": {
            "type": [
              "string",
              "null"
            ]
          },
          "orderId": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      }
    }
  }
}

curl -X GET 'https://mystocks.africa/api/sandbox/v1/partner/users/%7BuserId%7D/buying-power' \
  -H "Authorization: Bearer $MYSTOCKS_SANDBOX_API_KEY"

What actually happens between your POST /trade and settled units on an African exchange — who executes, who holds the assets, and where the cash sits.

The stack — one integration, every supported market

Your app

partner backend + clients

↓

MyStocks Partner API

/api/v1/partner — one REST surface

↓

MyStocks internal book

automatic execution and immutable fills

↓

Exchange

NSE · NGX · JSE · GSE · BRVM · ZSE · BSE · LuSE · EGX · DSE · USE · MSE · CSE · SEM

↓

CSD / custodian

central securities depository per market

↓

Settlement

T+N business days

You integrate one API. MyStocks routes orders to the regulated broker for each exchange, normalizes market data, currencies (FX model), settlement cycles, and corporate-action handling behind a single USD-denominated surface.

Who does what

Function	Performed by	How it surfaces in the API
KYC	You — the partner runs KYC and asserts the outcome	`POST /users/{userId}/kyc`. Trading is blocked until status is `VERIFIED` (`403 KYC_REQUIRED`).
AML & sanctions screening	MyStocks, at platform level	A frozen account fires `account.frozen`; frozen sub-accounts cannot trade or move funds.
Order execution	MyStocks automatic internal book	Orders move through `WORKING`, `PENDING`, `PARTIALLY_FILLED`, and `FILLED` (or a terminal rejection/cancellation/expiry); per-fill detail at `GET /orders/{orderId}/executions`.
Custody of securities	Regulated brokers, custodians and the CSD in each market	Pooled custody positions reconciled against per-sub-account holdings daily — custody section of `GET /report/reconciliation`.
Cash ledger	MyStocks — master wallet + sub-account wallets (USD)	`GET /float` (master headroom), sub-account wallet endpoints, cash section of the reconciliation report.
Settlement	Exchange + CSD, T+N business days	Unsettled SELL proceeds tracked per tranche in `GET /users/{userId}/buying-power`; excluded from `withdrawableUsd` until settled.
Corporate actions & dividends	MyStocks processes and distributes	`dividend.paid` and `corporateaction.declared` webhooks with per-sub-account breakdowns.
FX	MyStocks, at quote/trade time	Local-currency prices, USD wallets — see FX & Currency.

Where assets and cash live

MyStocks is a financial technology platform, not a broker-dealer. Brokerage, custody, settlement, and regulated dealing activities are performed by regulated stockbrokers, investment banks, broker-dealers, custodians, or appointed partners in each market; specific executing partners are disclosed at the point of trade execution.

Securities bought through the API are held in an omnibus (nominee) structure with the relevant market's custodian or CSD: the pooled custody account holds the units, and MyStocks maintains the beneficial-ownership ledger attributing exact units — including fractions — to each sub-account. That attribution is auditable any day via the custody section of GET /report/reconciliation, which reconciles pooled positions against the sum of per-sub-account holdings.

Cash — your master wallet and every sub-account wallet — is a USD ledger balance maintained by MyStocks, funded by your remittances (POST /topup) and depleted by payouts. Wallet balances are platform ledger entries, not bank deposits held in your end users' names. See the compliance hub for licensing, investor-protection, and per-market disclosures.

Money map — in, invested, out

Funding & investing

Your bank

remittance

↓POST /topup

Master wallet

GET /float — headroom & credit line

↓POST /users/{userId}/deposit

Sub-account wallet

per end user, USD

↓POST /users/{userId}/trade

Escrow

held at order placement

↓fill + settlement

Holding

settled units + tax lots

Divesting & withdrawing

Holding

SELL order

↓fill

Unsettled proceeds

T+N — excluded from withdrawableUsd

↓settlement date

Sub-account wallet

settled cash

↓POST /users/{userId}/withdraw

Master wallet

aggregated

↓POST /payout

Your bank

payout

Full endpoint detail in Fund Flow; currency handling in FX & Currency.

For the production control model, continue with Customer ownership and omnibus custody, Client-money segregation, and Complaints, corporate actions, and insolvency.

Anatomy of a market BUY

Your backend

quote → trade

↓POST /users/{userId}/trade + quoteId + Idempotency-Key

Partner API

order PENDING — cost + fees escrowed

↓review & routing

MyStocks internal book

executes automatically

↓execution

Exchange

order executed

↓signed webhook (at-least-once)

Your webhook endpoint

order.filled (+ trade.settled alias)

↓you update your UI / ledger

Portfolio updated

GET /users/{userId}/portfolio · tax lots · buying power

LIMIT/STOP orders rest in status WORKING until the trigger price is crossed (firing order.triggered), then follow the same path. Rejections release the escrow and fire order.rejected.

Was this page useful?

Your signal helps us tighten partner onboarding docs.

Send note

Last updated on

Broker API FAQs

KYC, AML, sanctions, and beneficial owners