# 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

1\. Your app: partner backend + clients

2\. MyStocks Partner API: /api/v1/partner — one REST surface

3\. MyStocks internal book: automatic execution and immutable fills

4\. Exchange: NSE · NGX · JSE · GSE · BRVM · ZSE · BSE · LuSE · EGX · DSE · USE · MSE · CSE · SEM

5\. CSD / custodian: central securities depository per market

6\. 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](/partners/docs/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](/partners/docs/fx-model).                                                                                               |

## 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](/compliance) for licensing, investor-protection, and per-market disclosures.

## Money map — in, invested, out

**Funding & investing**

1\. Your bank: remittance

2\. Master wallet: GET /float — headroom & credit line

3\. Sub-account wallet: per end user, USD

4\. Escrow: held at order placement

5\. Holding: settled units + tax lots

**Divesting & withdrawing**

1\. Holding: SELL order

2\. Unsettled proceeds: T+N — excluded from withdrawableUsd

3\. Sub-account wallet: settled cash

4\. Master wallet: aggregated

5\. Your bank: payout

Full endpoint detail in [Fund Flow](/partners/docs/fund-flow); currency handling in
[FX & Currency](/partners/docs/fx-model).

For the production control model, continue with [Customer ownership and omnibus custody](/partners/docs/customer-ownership),
[Client-money segregation](/partners/docs/client-money-segregation), and
[Complaints, corporate actions, and insolvency](/partners/docs/complaints-corporate-actions-insolvency).

## Anatomy of a market BUY

1\. Your backend: quote → trade

2\. Partner API: order PENDING — cost + fees escrowed

3\. MyStocks internal book: executes automatically

4\. Exchange: order executed

5\. Your webhook endpoint: order.filled (+ trade.settled alias)

6\. 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`.