Quick Start
Go from zero to your first executed trade — register, create a sub-account, deposit, quote, and trade — all against the MyStocks sandbox with no approval required.
Explore endpoints
9 of 9/market/settlement
Settlement cycles and live fill target
Full endpoint documentationgetMarketSettlementReturns the configured T+N settlement cycle for each supported exchange (i.e. when title and beneficial ownership transfer after trade execution), plus the MyStocks live fill SLA for market orders submitted during exchange hours. Important distinction - MyStocks live fill SLA — the time before a PENDING live order moves to COMPLETED or REJECTED. Execution window: 1 to 5 minutes during market hours. - Exchange settlement cycle — the configured operational cycle; confirm the current broker/CSD terms before launch. This governs when the underlying shares clear through the depository according to the current broker/CSD terms. A configured cycle is not independent settlement proof. Use ?exchange=NSE to filter to a single exchange.
Parameters
exchangestringqueryFilter to a single exchange code (NSE, NGX, JSE, GSE, BRVM, ZSE, BSE, LUSE, EGX, DSE, USE, MSE, CSE, SEM).
Example: NSE
Headers
AuthorizationstringRequiredBearer sk_sandbox_<your_key> for sandbox requests.
Response fields
processingWindowobjectprocessingWindow.targetTurnaroundHoursnumberLegacy hour equivalent of the live 5-minute fill target.
Example: 0.083
processingWindow.minTurnaroundMinutesintegerEarliest expected live execution window, in minutes.
Example: 1
processingWindow.maxTurnaroundMinutesintegerMaximum live execution window, in minutes.
Example: 5
processingWindow.targetTurnaroundMinutesintegerMonitoring deadline between live market order submission and fill/rejection during market hours.
Example: 5
processingWindow.descriptionstringprocessingWindow.outsideHoursNotestringprocessingWindow.processingDaysstringExample: "Monday – Friday (excluding public holidays)"
processingWindow.webhookNotestringprocessingWindow.pollEndpointstringExample: "GET /api/v1/partner/orders/{orderId}"
exchangesobjectResponse codes
200Settlement cycles and live fill target.401Unauthorized.404Unknown exchange code.Go from zero to your first executed trade — all against the sandbox, no approval required.
This guide covers customer accounts and trading. For prices and charts only, start with the Market Data guide. For other workflows, browse the integration guides.
Sandbox path
- 1
Register
Get a sandbox key from the partner portal session.
POST /register - 2
Create user
Create an isolated wallet for your end-user.
POST /users - 3
Deposit
Credit the user wallet using MyStocks-managed FX.
POST /users/{userId}/deposit - 4
Optional: assert KYC
Exercise the production-style KYC assertion flow; sandbox trading does not require it.
POST /users/{userId}/kyc - 5
Quote
Fetch a single-use quoteId that expires after 60 seconds.
GET /quote/{symbol} - 6
Trade
Submit the order with the matching quoteId and idempotency key.
POST /users/{userId}/trade
Register and get your API key
Sign in (or sign up) on the partner portal first — /register authenticates
with your Firebase ID token from that session, not an API key. The easiest path is the portal's
"Create Key" or "Rotate Key" button, which calls this endpoint for you. Rotation is explicit because
calling it again invalidates the previous sandbox key.
curl -X POST https://mystocks.africa/api/sandbox/v1/register \
-H "Authorization: Bearer <firebase-id-token>"{ "apiKey": "sk_sandbox_xxxxxxxxxxxxxxxx", "walletBalance": 100000, "currency": "USD" }Create a sub-account for your end-user
Each of your end-users gets an isolated wallet. Alternatively use
POST /api/sandbox/v1/partner/auto-register (idempotent — safe to call on every login).
curl -X POST https://mystocks.africa/api/sandbox/v1/partner/users \
-H "Authorization: Bearer sk_sandbox_<your_key>" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: create-user-42-001" \
-d '{ "externalId": "user_42", "displayName": "Jane Doe", "email": "jane@example.com" }'{
"subAccountId": "usr_xxxxxxxxxxxx",
"externalId": "user_42",
"displayName": "Jane Doe",
"kycStatus": "NONE",
"status": "active",
"wallet": { "currency": "USD", "balance": 0 }
}Deposit funds
Production deposits follow collection of a real customer payment. Sandbox deposits move virtual funds only. Send a USD amount or a supported local amount and currency; MyStocks reads the managed FX configuration and returns the USD credit and conversion metadata. Unsupported currencies or unavailable rates fail without moving funds. Use conversion quote terms and the applied rate in the receipt; bulk /fx/rates export is disabled. Never assume a fixed conversion rate.
curl -X POST https://mystocks.africa/api/sandbox/v1/partner/users/usr_xxxxxxxxxxxx/deposit \
-H "Authorization: Bearer sk_sandbox_<your_key>" \
-H "Idempotency-Key: dep_user42_001" \
-H "Content-Type: application/json" \
-d '{ "amount": 65000, "currency": "KES", "note": "Mpesa ref mpesa_QHJ29SK" }'The following response is illustrative only if the configured rate is 130 KES per USD; the actual rate and balances are returned by the API. Sandbox responses also include simulationOnly: true.
{ "message": "Deposit successful.", "subAccountId": "usr_xxxxxxxxxxxx", "amount": 500, "currency": "USD", "fxRate": 130, "fxSource": "MYSTOCKS_MANAGED_FX", "newSubBalance": 500, "newMasterBalance": 99500 }Optional: assert KYC
You run KYC in your own onboarding flow, then assert the result. The sandbox permits synthetic
customers to trade without KYC so a new integration can reach its first fill immediately. Production
still requires VERIFIED; an unverified production sub-account receives 403 KYC_REQUIRED. Use this
optional sandbox step, or the KYC_REQUIRED simulation scenario in the API Tester, to exercise your
production error and recovery UX.
curl -X POST https://mystocks.africa/api/sandbox/v1/partner/users/usr_xxxxxxxxxxxx/kyc \
-H "Authorization: Bearer sk_sandbox_<your_key>" \
-H "Idempotency-Key: kyc_user42_001" \
-H "Content-Type: application/json" \
-d '{ "status": "VERIFIED", "level": "BASIC", "reference": "kyc_provider_ref_123" }'{ "message": "KYC status updated.", "subAccountId": "usr_xxxxxxxxxxxx", "kycStatus": "VERIFIED", "kycLevel": "BASIC" }Get a quote (returns the required quoteId)
Every MARKET trade — sandbox and production — starts with a quote. LIMIT, STOP and STOP_LIMIT orders follow the quote-free resting-order contract in the trading guide. It returns the latest delayed price observation, the full fee
breakdown, and a single-use quoteId that expires after 60 seconds.
curl "https://mystocks.africa/api/sandbox/v1/partner/quote/SCOM.KE?type=BUY&quantity=1000&subAccountId=usr_xxxxxxxxxxxx" \
-H "Authorization: Bearer sk_sandbox_<your_key>"This illustration uses 130 KES/USD, a client price of 16.5 KES, a 0.75% fee and cent rounding. Live quotes disclose their actual terms; do not calculate an execution price from this example.
{
"quoteId": "qt_9f2c81d4b7a3",
"quoteExpiresAt": "2026-07-07T09:46:00Z",
"quoteTtlSeconds": 60,
"symbol": "SCOM.KE",
"name": "Safaricom PLC",
"exchange": "NSE",
"currency": "KES",
"type": "BUY",
"quantity": 1000,
"localPrice": 16.5,
"usdPrice": 0.126923,
"gross": 126.92,
"fee": 0.95,
"totalCost": 127.87,
"sufficientFunds": true
}Place a trade on behalf of the sub-account
Pass the quoteId from the previous step within 60 seconds. You can use the full exchange-qualified
symbol (SCOM.KE) or just the bare ticker (SCOM) — the API resolves it automatically.
curl -X POST https://mystocks.africa/api/sandbox/v1/partner/users/usr_xxxxxxxxxxxx/trade \
-H "Authorization: Bearer sk_sandbox_<your_key>" \
-H "Idempotency-Key: trade_user42_001" \
-H "Content-Type: application/json" \
-d '{ "symbol": "SCOM.KE", "type": "BUY", "quantity": 1000, "quoteId": "qt_9f2c81d4b7a3" }'{
"status": "FILLED",
"orderId": "ord_xxxxxxxxxxxx",
"subAccountId": "usr_xxxxxxxxxxxx",
"type": "BUY",
"symbol": "SCOM.KE",
"quantity": 1000,
"totalCost": 127.87,
"newSubBalance": 372.13,
"note": "Order filled instantly in sandbox. Live production trades are PENDING until filled or rejected."
}Check order history (or use webhooks)
curl "https://mystocks.africa/api/sandbox/v1/partner/users/usr_xxxxxxxxxxxx/orders?limit=1" \
-H "Authorization: Bearer sk_sandbox_<your_key>"In sandbox, sub-account trades settle instantly (FILLED) with no admin queue. In production,
status progresses PENDING → FILLED (or REJECTED) through the execution flow during exchange hours. v1 may emit legacy COMPLETED as an alias of FILLED.
Settlement timeline — production
| Phase | Timeline | Notes |
|---|---|---|
| MyStocks live fill target | Within 5 minutes | Market orders submitted during exchange hours. Outside hours → queued for next session. |
| Exchange settlement | Read the configured market cycle from GET /market/settlement and verify the current broker/CSD terms before launch | A configured cycle is an operational expectation, not proof that a particular order has settled. |
The MyStocks execution target is when your PENDING order becomes FILLED — this triggers the
order.filled webhook and credits shares/proceeds to the wallet. The exchange settlement cycle
(T+2/T+3) governs when the underlying title and custody transfer through the exchange depository; it
can leave credited SELL proceeds unavailable for withdrawal. Ledger balance, available-to-trade cash and withdrawable cash are distinct; read buying power and settlement fields before cash-out. Full per-exchange data is at GET /api/v1/partner/market/settlement.
Order lifecycle
A PENDING order can instead terminate as REJECTED (BUY escrow refunded · order.rejected) or,
while still PENDING, be CANCELLED by your DELETE (order.cancelled).
Sandbox only: orders skip the escrow wait and resolve immediately as FILLED. A live order can be
cancelled while it is still PENDING (or WORKING, for resting limit/stop orders) — once it reaches a
terminal state (FILLED, REJECTED, CANCELLED, or EXPIRED) the DELETE returns HTTP 409.
Cancelling a PENDING order
While an order is still PENDING, cancel it with a DELETE. For BUY orders the escrowed funds are
refunded atomically; SELL orders carry no wallet impact so cancellation is immediate. Once an order
has filled (FILLED) or otherwise reached a terminal state (REJECTED, CANCELLED, EXPIRED) it can no
longer be cancelled (HTTP 409). A
successful cancellation fires an order.cancelled webhook so downstream systems react without polling.
# Cancel a sub-account order
curl -X DELETE "https://mystocks.africa/api/v1/partner/users/usr_xxxxxxxxxxxx/orders/ord_xxxxxxxxxxxx" \
-H "Authorization: Bearer pk_live_<your_key>" \
-H "Idempotency-Key: cancel-subaccount-order-ord_xxxxxxxxxxxx"
# Cancel a master-account order
curl -X DELETE "https://mystocks.africa/api/v1/partner/orders/ord_xxxxxxxxxxxx" \
-H "Authorization: Bearer pk_live_<your_key>" \
-H "Idempotency-Key: cancel-master-order-ord_xxxxxxxxxxxx"Modifying a resting order (replace)
A resting LIMIT/STOP/STOP_LIMIT order sits in status WORKING until its price triggers. While
WORKING you can modify its limitPrice, stopPrice, and/or quantity with a PATCH — the order
keeps the same orderId, and the BUY escrow or SELL unit reservation is adjusted by the delta
atomically. Increasing a BUY escrow beyond the available balance returns 400 INSUFFICIENT_FUNDS; the
replaceable field on the order tells you when a modify is allowed. Market orders cannot be modified —
cancel and re-submit instead. Requires an Idempotency-Key.
# Re-price and re-size a WORKING resting order (same orderId)
curl -X PATCH "https://mystocks.africa/api/v1/partner/users/usr_xxxxxxxxxxxx/orders/ord_xxxxxxxxxxxx" \
-H "Authorization: Bearer pk_live_<your_key>" \
-H "Idempotency-Key: replace_ord_xxxxxxxxxxxx_1" \
-H "Content-Type: application/json" \
-d '{ "limitPrice": 21.5, "quantity": 150 }'A successful modify fires an order.replaced webhook and writes a REPLACE execution report.
Skip polling — use webhooks. Register a webhook URL to receive order.filled, order.rejected,
and order.cancelled events in real time. See Webhooks, and the
Going Live checklist when you're ready to switch to production.
Can I choose Hosted API, OnPrem or both?
Yes. Select Hosted API, OnPrem or Both when applying. Your connection preference does not grant an entitlement. One partner account shows API access and Installations & licenses as separate sections on the dashboard overview. You can change your personal connection preference there.
The Sandbox / Live selector checks access on the server. Hosted Live approval and an OnPrem production activation are separate decisions. An OnPrem evaluation remains Sandbox-only even if the same organization has Hosted Live approval. Conversely, a separately approved Hosted Live service is not disabled merely because an installation license expires. Existing accounts retain their previous access policy until partner operations makes an explicit Hosted Live decision.
| Credential | Purpose | Lifecycle |
|---|---|---|
| Sandbox API key | Synthetic calls in /api/sandbox/v1/; quotes delayed by 15 minutes | Created and rotated in the Sandbox console; cannot authorize Live calls |
| Production API key | Approved Live API calls in /api/v1/partner/ | Issued/rotated for the organization, independently suspendable and revocable; API scopes and commercial entitlements still apply |
| Installation license credential | Authorizes a particular gateway, installation identity and domain | Temporary with an admin-set expiry or permanent and revocable; retrieval, renewal, domain verification and installation proof are separate from API approval |
Partner operations uses Access & deployments in /admin/partners/{partnerId} to review Hosted Live approval independently from domain verification, installation status, license expiry and the next required action. An approval or block requires an authorized administrator, a review reason, explicit confirmation and recent sign-in. It records audit evidence and queues a customer notification. Installation production activation retains its own DNS, identity and commercial checks.
Was this page useful?
Your signal helps us tighten partner onboarding docs.
Last updated on
Key Management
Rotate and revoke MyStocks Partner API keys and manage scoped read-only data keys, including one-time credential responses and immediate suspension behavior.
SDKs and Tools
MyStocks client source previews, multi-language examples, OpenAPI specifications, API Tester, and webhook utilities.