Quick Start

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.

curl -X POST https://mystocks.africa/api/sandbox/v1/register \
  -H "Authorization: Bearer <firebase-id-token>"

{ "apiKey": "sk_sandbox_xxxxxxxxxxxxxxxx", "walletBalance": 100000, "currency": "USD" }

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 }
}

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" }'

{ "message": "Deposit successful.", "subAccountId": "usr_xxxxxxxxxxxx", "amount": 500, "currency": "USD", "fxRate": 130, "fxSource": "MYSTOCKS_MANAGED_FX", "newSubBalance": 500, "newMasterBalance": 99500 }

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" }

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>"

{
  "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.0126,
  "gross": 12.6,
  "fee": 0.09,
  "totalCost": 12.69,
  "sufficientFunds": true
}

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": 12.69,
  "newSubBalance": 487.31,
  "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

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 does not affect wallet balances in the API. 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).

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.

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.

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.