Skip to content
MyStocks Developers
API v1

API v1

Current stable contract

Versioning policyRelease changelog
Sandbox console
Operate

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

  1. Fetch GET /report/reconciliation?asOf=YYYY-MM-DD.
  2. Persist the JSON response, X-Request-ID, and retrieval timestamp.
  3. Compare the cash section with MyStocks wallet balances and your internal ledger.
  4. Compare securities with sub-account holdings and custody positions.
  5. Classify every unsettled trade by order, execution, expected settlement date, and status.
  6. Reconcile fees, dividends, and corporate-action distributions.
  7. Record exceptions with an owner, expected resolution date, and supporting event IDs.
  8. 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.

curl 'https://mystocks.africa/api/v1/partner/report/reconciliation?asOf=2026-06-30' \
  -H 'Authorization: Bearer pk_live_<your_key>'

Exception handling

The JSON response includes proof.status:

  • BALANCED — beneficial units match pooled custody units within tolerance;
  • EXCEPTIONS — inspect proof.custody.exceptions for 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.

GET

/orders/blotter

List orders across owned customer accounts

Full endpoint documentation
Sandbox availablelistCustomerOrderBlotter

Customer 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

limitintegerquery

Page size, default 50.

Example: 50

cursorstringquery

Opaque continuation from this endpoint.

symbolstringquery

Instrument symbol.

statusALL | PENDING | WORKING | PARTIALLY_FILLED | FILLED | REJECTED | CANCELLED | EXPIRED | COMPLETEDquery

Canonical execution status; COMPLETED aliases FILLED.

fromstringquery

Inclusive ISO date or timezone-aware timestamp.

tostringquery

Inclusive ISO date (through 23:59:59.999 UTC) or timezone-aware timestamp.

Headers

AuthorizationstringRequired

Bearer sk_sandbox_<your_key> for sandbox requests.

Response fields

ordersobject[]Required
orders[].orderIdstring
orders[].subAccountIdstring
orders[].externalIdstring | null
orders[].symbolstring
orders[].typestring
orders[].statusstring
orders[].canonicalStatusstring
orders[].settlementStatusstring
orders[].quantitynumber
orders[].filledQuantitynumber
orders[].remainingQuantitynumber
orders[].currencystring
orders[].createdAtstring | null
orders[].filledAtstring | null
orders[].settledAtstring | null
orders[].rejectionCodestring | null
orders[].orderLifecyclestring | null

EXPIRED for expiry; expiry is not a rejection.

orders[].cancelReasonstring | null
countintegerRequired
hasMorebooleanRequired
nextCursorstring | nullRequired
orderingstringRequired
scopestring
snapshotModelstring
scannedOrdersinteger
sandboxboolean

Response 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.
GET

/orders

List orders

Full endpoint documentation
Sandbox availablelistOrders

Returns 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 | EXPIREDquery
symbolstringquery

Example: SCOM.KE

fromstringquery

ISO date (whole UTC day) or timezone-qualified ISO date-time; invalid or reversed bounds return 400.

Example: 2026-01-01

tostringquery

ISO date (whole UTC day) or timezone-qualified ISO date-time; invalid or reversed bounds return 400.

Example: 2026-03-31

cursorstringquery

Opaque cursor from nextCursor of the previous response. Omit for the first page.

limitintegerquery

Example: 50

Headers

AuthorizationstringRequired

Bearer sk_sandbox_<your_key> for sandbox requests.

Response fields

ordersobject[]Required
orders[].orderIdstring

Unique order ID. Use to poll status or cancel.

Example: "ord_abc123xyz"

orders[].symbolstring

Example: "SCOM.KE"

orders[].namestring

Example: "Safaricom PLC"

orders[].exchangestring

Example: "NSE"

orders[].orderTypeMARKET | LIMIT | STOP | STOP_LIMIT

Order type. MARKET orders are quote-gated; LIMIT/STOP/STOP_LIMIT rest as WORKING until triggered.

Example: "LIMIT"

orders[].limitPricenumber | null

Limit price in the stock's local currency (LIMIT / STOP_LIMIT only).

orders[].stopPricenumber | null

Stop price in the stock's local currency (STOP / STOP_LIMIT only).

orders[].cancelableboolean

Whether the order can be cancelled now (DELETE). True while PENDING or WORKING.

orders[].replaceableboolean

Whether the order can be modified now (PATCH). True only for a WORKING resting order.

orders[].typeBUY | SELL
orders[].statusPENDING | WORKING | PARTIALLY_FILLED | PROCESSING | COMPLETED | FILLED | REJECTED | CANCELLED | EXPIRED

PENDING 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 | null

Pre-trade quote ID consumed by this order.

orders[].quoteExpiresAtstring | null
orders[].quoteUsdPricenumber | null
orders[].clientOrderIdstring | null

Partner-supplied order reference.

orders[].omsStatusstring | null

Canonical OMS lifecycle status.

orders[].timeInForcestring | null
orders[].filledQuantitynumber
orders[].remainingQuantitynumber
orders[].averageFillPricenumber | null
orders[].executionVenuestring | null
orders[].lastExecutionReportIdstring | null
orders[].executionSlaunion

Live execution SLA clock for orders that have entered the PENDING dealing-desk queue. Null while a resting order is still WORKING.

orders[].quantityinteger
orders[].priceAtOrdernumber

Stock price in local currency at submission.

orders[].usdPriceAtOrdernumber

USD equivalent of priceAtOrder.

orders[].fxRateAtOrdernumber | null

Managed FX rate used for local-to-USD conversion at order submission.

orders[].fxSourcestring | null
orders[].fxRateAsOfstring | null
orders[].fxConversionunion
orders[].feenumber

Total fee in USD (base + partner markup).

orders[].baseFeenumber

MyStocks base broker fee (0.75% of gross).

orders[].partnerMarkupFeenumber

Your markup fee component. Zero if markupBps = 0.

orders[].totalAmountnumber

BUY: gross + fee. SELL: gross - fee.

orders[].currencystring

Example: "USD"

orders[].localCurrencystring

Example: "KES"

orders[].rejectionCodestring | null

Structured rejection code. Populated when status = REJECTED.

orders[].rejectionReasonstring | null

Free-text rejection detail provided by the MyStocks internal-book execution service. Populated when status = REJECTED.

orders[].cancelledAtstring | null
orders[].settledAtstring | null

Set 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[].createdAtstring
orders[].canonicalStatusPENDING | WORKING | PARTIALLY_FILLED | FILLED | REJECTED | CANCELLED | EXPIRED
orders[].settlementStatusPENDING | SETTLED | FAILED
orders[].orderLifecyclestring | null

EXPIRED for expiry; expiry is not a rejection.

orders[].cancelReasonstring | null
countintegerRequired
hasMorebooleanRequired
nextCursorstring | nullRequired

Response codes

200Order list.
GET

/users/summary

Read up to 20 customer wallet summaries

Full endpoint documentation
Sandbox availablegetCustomerWalletSummaries

Supply 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

userIdsstringqueryRequired

1–20 distinct comma-separated customer IDs or external IDs.

Headers

AuthorizationstringRequired

Bearer sk_sandbox_<your_key> for sandbox requests.

Response fields

accountsobject[]Required
accounts[].requestedIdstring
accounts[].subAccountIdstring
accounts[].userIdstring
accounts[].externalIdstring
accounts[].statusstring
accounts[].asOfstring
accounts[].currencyWalletsobject[]
accounts[].buyingPowerobject
accounts[].currencyClosureBlockersobject[]
accounts[].errorobject
countintegerRequired
asOfstringRequired
snapshotModelstringRequired
sandboxboolean

Response 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.

Send note

Last updated on

On this page