Architecture & Custody
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.
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
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/{id}/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 dealing desk + the licensed broker on each exchange | Orders move PENDING → COMPLETED (resting limit/stop orders rest at WORKING until triggered); per-fill detail at GET /orders/{id}/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/{id}/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
Divesting & withdrawing
Full endpoint detail in Fund Flow; currency handling in FX & Currency.
Anatomy of a market BUY
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.