Customer ownership and omnibus custody

Every production launch must answer three questions without ambiguity: whose customer is this, who legally holds the security, and which record proves the end investor's entitlement? The commercial agreement, customer terms, custody agreement, and API implementation must give the same answer.

Operating model

MyStocks maintains the sub-account ledger used to attribute pooled positions. The relevant regulated broker, custodian, nominee, or CSD holds the market-level position under the arrangement approved for that jurisdiction. A portfolio response is therefore an operational entitlement record, not a claim that the end investor has an individually named CSD account.

Responsibility matrix

Minimum customer record

Keep one durable customer record that connects your identity system to the MyStocks ledger:

Do not store passport images, biometrics, or unnecessary source documents in free-text API fields. Keep sensitive evidence in the approved KYC system and send only the structured assertion required by POST /users/{userId}/kyc.

Daily books-and-records control

1. Reconcile each security's pooled broker/custodian units to the sum of attributed sub-account units.
2. Reconcile cash, unsettled trades, dividends, fees, and corporate-action allocations.
3. Classify differences as timing, mapping, external statement, or ledger exceptions.
4. Prevent silent balancing entries; require an identified owner, evidence, and approval.
5. Escalate unresolved unit or cash differences before the next trading session.

Use GET /report/reconciliation for the platform view and compare it with the dated broker/CSD statement. The Custody and beneficial ownership page describes the evidence required for GA.

Customer-facing disclosure checklist

• Identify the contracting entity and the entity providing regulated brokerage or custody.
• Explain whether securities are held in an omnibus, nominee, or individually named account.
• State how beneficial ownership is recorded and how customers receive statements and confirmations.
• Separate execution from legal settlement and explain when cash or securities become withdrawable.
• Explain the treatment of fractional entitlements, voting rights, dividends, taxes, fees, and FX.
• Describe transfer-out, account closure, death, incapacity, attachment, and insolvency procedures.
• Disclose applicable investor-compensation or protection arrangements without implying universal coverage.

Evidence required before production

Reference standards

• CPMI-IOSCO Principles for financial market infrastructures
• FATF beneficial-ownership guidance

Canonical customer identifiers

Persist subAccountId from creation. The userId response alias contains the same value and corresponds to the path parameter in /users/{userId}. List, detail and create responses use the same identity mapping. An externalId lookup is scoped to your partner; never substitute another partner's internal ID.

Freeze and close safely

Use PATCH /users/{userId} with { "status": "frozen" } to stop new financial activity. Existing resting orders may be cancelled; a frozen customer cannot receive new simulated or dealing-room-approved fills. Freeze and reactivation record audit evidence and queue account notifications. Freezing does not automatically cancel every order or constitute a legal/regulatory certification.

Use DELETE /users/{userId} only after resolving open orders, positions and settlements. CURRENCY_CLOSE_BLOCKED supplies currencyBlockers with the currency, reason and next action. Non-USD cash, wallet reservations and remaining native funding entitlements must be resolved first. Use native internal transfers to return traceable funds. Legacy transfer_to_partner handles only eligible residual USD cash and does not convert currencies or move native funding entitlements. Closed accounts cannot be reopened.