Daily Processes and Reconciliation
Run a repeatable daily control process for cash, securities, unsettled trades, fees, dividends, corporate actions, and custody positions.
The reconciliation pack is the durable operational record for your integration. Run it after the relevant market close and again after settlement windows or correction events.
Daily sequence
- Fetch
GET /report/reconciliation?asOf=YYYY-MM-DD. - Persist the JSON response,
X-Request-ID, and retrieval timestamp. - Compare the cash section with MyStocks wallet balances and your internal ledger.
- Compare securities with sub-account holdings and custody positions.
- Classify every unsettled trade by order, execution, expected settlement date, and status.
- Reconcile fees, dividends, and corporate-action distributions.
- Record exceptions with an owner, expected resolution date, and supporting event IDs.
- Export CSV sections for operations or audit retention.
Available sections
Use format=csv with one of cash, securities, unsettled, fees, dividends, corporate_actions, custody_positions, or summary. The JSON response is better for automated ingestion; CSV is useful for review and data-warehouse loads.
Exception handling
The JSON response includes proof.status:
BALANCED— beneficial units match pooled custody units within tolerance;EXCEPTIONS— inspectproof.custody.exceptionsfor the exact instrument and unit difference;INCOMPLETE— no pooled custody records were available, so custody equality has not been proven.
proof.cashRollForward states completed credits, completed debits, net movement, the derived opening
balance, and the equation used to reach the reported closing balance. This is an internal ledger
roll-forward; partners should still compare it with their own opening balance and external bank records.
Do not infer a missing record as a zero balance. Investigate stale data, unsettled trades, rejected orders, corporate-action adjustments, and custody differences. Use /client-activity, order executions, signed events, and the Statements and Confirms workflow to resolve mismatches.
The reconciliation endpoint is read-only. It is safe to retry, but persist the request ID and source period so repeated exports do not create duplicate internal records.
Sandbox reconciliation limits
GET /api/sandbox/v1/partner/report/reconciliation reads current virtual USD wallets and holdings, including the master account and at most 500 sub-accounts. It returns status: INCOMPLETE, actual ledger totals, null custody totals and fixture: false. There is no independent custody comparison. Use format=csv for current account totals. Historical asOf, from or to receive HTTP 422; section filtering receives HTTP 400. Do not treat simulated fills, event delivery or virtual balances as live settlement proof.
How do I read across my customers?
Use GET /orders/blotter for owned customer orders. The master GET /orders remains a master-account endpoint. The blotter orders customers by customer ID, then orders by newest createdAt within each customer; it is not a globally chronological feed. Each request scans at most 20 customers and 1,000 orders and returns up to 200 matching orders (default 50). Follow nextCursor while hasMore is true, even when a filtered page is empty. Keep the same filters and environment on continuation.
Use GET /users/summary?userIds=customer-1,external-2 for 1–20 distinct owned customer IDs or external IDs. Unknown and foreign customers receive the same per-item NOT_FOUND error. Each account includes its canonical identity, actual currency wallets, USD buying power, currency closure blockers and read timestamp. The request reads each account independently and reuses the wallet accounting checks; it is not an atomic consolidated statement or a replacement for final closure checks. Wallet read cost depends on each customer's wallet, entitlement and order history. Do not add USD and KES balances together.
Set API_BASE=https://partners.mystocks.africa/api/sandbox/v1/partner for virtual Sandbox accounts, or /api/v1/partner for approved Live access. Customer reads appear in the partner currency workspace and /admin/partners currency workspace. Admin reads require ledger-view permission; hosted API reads require the relevant scoped credential.
/orders/blotter
List orders across owned customer accounts
Full endpoint documentationlistCustomerOrderBlotterCustomer ID ascending, then createdAt descending within each customer; not global chronological ordering. Scans at most 20 customers and 1,000 orders per request. Continue using nextCursor even when orders is empty. Cursors are scoped to partner, environment and filters. This does not change the master-account /orders endpoint.
Parameters
limitintegerqueryPage size, default 50.
Example: 50
cursorstringqueryOpaque continuation from this endpoint.
symbolstringqueryInstrument symbol.
statusALL | PENDING | WORKING | PARTIALLY_FILLED | FILLED | REJECTED | CANCELLED | EXPIRED | COMPLETEDqueryCanonical execution status; COMPLETED aliases FILLED.
fromstringqueryInclusive ISO date or timezone-aware timestamp.
tostringqueryInclusive ISO date (through 23:59:59.999 UTC) or timezone-aware timestamp.
Headers
AuthorizationstringRequiredBearer sk_sandbox_<your_key> for sandbox requests.
Response fields
ordersobject[]Requiredorders[].orderIdstringorders[].subAccountIdstringorders[].externalIdstring | nullorders[].symbolstringorders[].typestringorders[].statusstringorders[].canonicalStatusstringorders[].settlementStatusstringorders[].quantitynumberorders[].filledQuantitynumberorders[].remainingQuantitynumberorders[].currencystringorders[].createdAtstring | nullorders[].filledAtstring | nullorders[].settledAtstring | nullorders[].rejectionCodestring | nullorders[].orderLifecyclestring | nullEXPIRED for expiry; expiry is not a rejection.
orders[].cancelReasonstring | nullcountintegerRequiredhasMorebooleanRequirednextCursorstring | nullRequiredorderingstringRequiredscopestringsnapshotModelstringscannedOrdersintegersandboxbooleanResponse codes
200Owned customer results with explicit read and continuation limits.400Invalid bounds, identifiers or cursor.401Valid environment-specific API key required.403Required read permission is missing.429Partner request rate limit exceeded./orders
List orders
Full endpoint documentationlistOrdersReturns your partner order history. Filter by status, symbol, or date range. Filters from/to are enforced against createdAt. ISO dates cover full UTC days. Sparse matches may yield an empty page with hasMore=true; follow nextCursor. Each call scans at most 1000 source records. Invalid limits, dates and cursors return 400.
Parameters
statusPENDING | WORKING | PARTIALLY_FILLED | PROCESSING | COMPLETED | FILLED | REJECTED | CANCELLED | EXPIREDquerysymbolstringqueryExample: SCOM.KE
fromstringqueryISO date (whole UTC day) or timezone-qualified ISO date-time; invalid or reversed bounds return 400.
Example: 2026-01-01
tostringqueryISO date (whole UTC day) or timezone-qualified ISO date-time; invalid or reversed bounds return 400.
Example: 2026-03-31
cursorstringqueryOpaque cursor from nextCursor of the previous response. Omit for the first page.
limitintegerqueryExample: 50
Headers
AuthorizationstringRequiredBearer sk_sandbox_<your_key> for sandbox requests.
Response fields
ordersobject[]Requiredorders[].orderIdstringUnique order ID. Use to poll status or cancel.
Example: "ord_abc123xyz"
orders[].symbolstringExample: "SCOM.KE"
orders[].namestringExample: "Safaricom PLC"
orders[].exchangestringExample: "NSE"
orders[].orderTypeMARKET | LIMIT | STOP | STOP_LIMITOrder type. MARKET orders are quote-gated; LIMIT/STOP/STOP_LIMIT rest as WORKING until triggered.
Example: "LIMIT"
orders[].limitPricenumber | nullLimit price in the stock's local currency (LIMIT / STOP_LIMIT only).
orders[].stopPricenumber | nullStop price in the stock's local currency (STOP / STOP_LIMIT only).
orders[].cancelablebooleanWhether the order can be cancelled now (DELETE). True while PENDING or WORKING.
orders[].replaceablebooleanWhether the order can be modified now (PATCH). True only for a WORKING resting order.
orders[].typeBUY | SELLorders[].statusPENDING | WORKING | PARTIALLY_FILLED | PROCESSING | COMPLETED | FILLED | REJECTED | CANCELLED | EXPIREDPENDING after submission. WORKING = resting LIMIT/STOP/STOP_LIMIT order waiting for its trigger price (becomes PENDING on trigger). PARTIALLY_FILLED and FILLED are the canonical execution states. REJECTED, CANCELLED, and EXPIRED are terminal outcomes. PROCESSING is a legacy transition alias and COMPLETED is a v1 compatibility alias of FILLED; neither represents custody settlement. Settlement is tracked separately as PENDING, SETTLED, or FAILED.
orders[].quoteIdstring | nullPre-trade quote ID consumed by this order.
orders[].quoteExpiresAtstring | nullorders[].quoteUsdPricenumber | nullorders[].clientOrderIdstring | nullPartner-supplied order reference.
orders[].omsStatusstring | nullCanonical OMS lifecycle status.
orders[].timeInForcestring | nullorders[].filledQuantitynumberorders[].remainingQuantitynumberorders[].averageFillPricenumber | nullorders[].executionVenuestring | nullorders[].lastExecutionReportIdstring | nullorders[].executionSlaunionLive execution SLA clock for orders that have entered the PENDING dealing-desk queue. Null while a resting order is still WORKING.
orders[].quantityintegerorders[].priceAtOrdernumberStock price in local currency at submission.
orders[].usdPriceAtOrdernumberUSD equivalent of priceAtOrder.
orders[].fxRateAtOrdernumber | nullManaged FX rate used for local-to-USD conversion at order submission.
orders[].fxSourcestring | nullorders[].fxRateAsOfstring | nullorders[].fxConversionunionorders[].feenumberTotal fee in USD (base + partner markup).
orders[].baseFeenumberMyStocks base broker fee (0.75% of gross).
orders[].partnerMarkupFeenumberYour markup fee component. Zero if markupBps = 0.
orders[].totalAmountnumberBUY: gross + fee. SELL: gross - fee.
orders[].currencystringExample: "USD"
orders[].localCurrencystringExample: "KES"
orders[].rejectionCodestring | nullStructured rejection code. Populated when status = REJECTED.
orders[].rejectionReasonstring | nullFree-text rejection detail provided by the MyStocks internal-book execution service. Populated when status = REJECTED.
orders[].cancelledAtstring | nullorders[].settledAtstring | nullSet when custody settlement completes; independent of the canonical FILLED execution state. Legacy completed records that pre-date this field return their immutable completion/creation timestamp as compatibility evidence.
orders[].createdAtstringorders[].canonicalStatusPENDING | WORKING | PARTIALLY_FILLED | FILLED | REJECTED | CANCELLED | EXPIREDorders[].settlementStatusPENDING | SETTLED | FAILEDorders[].orderLifecyclestring | nullEXPIRED for expiry; expiry is not a rejection.
orders[].cancelReasonstring | nullcountintegerRequiredhasMorebooleanRequirednextCursorstring | nullRequiredResponse codes
200Order list./users/summary
Read up to 20 customer wallet summaries
Full endpoint documentationgetCustomerWalletSummariesSupply 1–20 distinct owned customer IDs or external IDs, separated by commas. Unknown and foreign IDs return the same NOT_FOUND item error. Actual currency wallets, USD buying power and currency closure blockers are returned per account. Accounts are read independently, not as an atomic consolidated statement. Open orders, positions and settlements still require closure-time checks.
Parameters
userIdsstringqueryRequired1–20 distinct comma-separated customer IDs or external IDs.
Headers
AuthorizationstringRequiredBearer sk_sandbox_<your_key> for sandbox requests.
Response fields
accountsobject[]Requiredaccounts[].requestedIdstringaccounts[].subAccountIdstringaccounts[].userIdstringaccounts[].externalIdstringaccounts[].statusstringaccounts[].asOfstringaccounts[].currencyWalletsobject[]accounts[].buyingPowerobjectaccounts[].currencyClosureBlockersobject[]accounts[].errorobjectcountintegerRequiredasOfstringRequiredsnapshotModelstringRequiredsandboxbooleanResponse codes
200Owned customer results with explicit read and continuation limits.400Invalid bounds, identifiers or cursor.401Valid environment-specific API key required.403Required read permission is missing.429Partner request rate limit exceeded.Was this page useful?
Your signal helps us tighten partner onboarding docs.
Last updated on