Sub-Accounts

Each of your end-users gets an isolated sub-account with its own USD wallet, portfolio, and order history. All write operations (deposit, withdraw, trade) are scoped to a single sub-account. The master wallet is the funding source for sub-account deposits.

Create a sub-account

POST /users

Create a sub-account for one of your end-users. Returns HTTP 201. Use externalId to map MyStocks sub-account IDs back to your own user table.

curl -X POST "https://mystocks.africa/api/v1/partner/users" \
-H "Authorization: Bearer pk_live_<key>" \
-H "Content-Type: application/json" \
-d '{"externalId":"user_42","displayName":"Jane Doe","email":"jane@example.com"}'

{ "subAccountId": "usr_abc123", "externalId": "user_42", "displayName": "Jane Doe", "email": "jane@example.com", "kycStatus": "NONE", "kycLevel": "NONE", "status": "active", "walletBalance": 0 }

Auto-register

POST /auto-register

Idempotent sub-account creation — safe to call on every user login. If a sub-account already exists for the given uid it is returned unchanged (no duplicate). Same response shape as POST /users.

List & fetch

GET /users · GET /users/{userId}

List all sub-accounts (cursor-paginated, default 100/page, max 500) or fetch a single one by its subAccountId. Filter by ?externalId= to look up using your own ID.

Update / freeze

PATCH /users/{userId}

Update display name or email. Set status: "frozen" to suspend all trading, deposits, and withdrawals for the sub-account; set back to status: "active" to restore access.

curl -X PATCH "https://mystocks.africa/api/v1/partner/users/usr_abc123" \
  -H "Authorization: Bearer pk_live_<key>" \
  -H "Content-Type: application/json" \
  -d '{"status":"frozen"}'

Close / offboard

DELETE /users/{userId}

Soft-close a sub-account when your user leaves your product or asks to terminate their investing account. Closure is terminal: the sub-account is retained for audit and regulatory history, but it can no longer trade, receive deposits, or withdraw.

Closure is blocked if the account has open orders, positive holdings, or unsettled proceeds. If the USD wallet still has cash, either call /withdraw first or pass residualCashHandling: "transfer_to_partner" to move the remaining cash to your master wallet during closure.

curl -X DELETE "https://mystocks.africa/api/v1/partner/users/usr_abc123" \
  -H "Authorization: Bearer pk_live_<key>" \
  -H "Idempotency-Key: close_user42_001" \
  -H "Content-Type: application/json" \
  -d '{"residualCashHandling":"transfer_to_partner","reason":"User requested closure"}'

{ "message": "Sub-account closed.", "subAccountId": "usr_abc123", "externalId": "user_42", "status": "closed", "residualTransferUsd": 0, "currency": "USD" }

Registered webhooks receive account.closed after a successful closure.

Deposit

POST /users/{userId}/deposit

Credit a sub-account wallet. Send a USD amount, or send a supported local-currency amount with currency and MyStocks will calculate the USD ledger credit using managed FX. Always set Idempotency-Key.

curl -X POST "https://mystocks.africa/api/v1/partner/users/usr_abc123/deposit" \
-H "Authorization: Bearer pk_live_<key>" \
-H "Idempotency-Key: dep_user42_001" \
-H "Content-Type: application/json" \
-d '{"amount":65000,"currency":"KES","note":"mpesa_QHJ29SK"}'

{ "message": "Deposit successful.", "subAccountId": "usr_abc123", "amount": 500, "currency": "USD", "newSubBalance": 500, "newMasterBalance": 99500 }

Withdraw

POST /users/{userId}/withdraw

Debit a sub-account wallet and return the USD ledger amount to your master wallet. For supported non-USD requests, MyStocks converts amount in currency; your payout rail then delivers the local currency to the user. The sub-account must have sufficient uninvested balance. Always set Idempotency-Key.

{ "message": "Withdrawal successful.", "subAccountId": "usr_abc123", "amount": 200, "currency": "USD", "newSubBalance": 300, "newMasterBalance": 99700 }

Assert KYC

POST /users/{userId}/kyc

Assert the KYC result you obtained using your own provider. Set status: "VERIFIED" and level: "BASIC" to unlock trading; FULL unlocks enhanced limits and higher-value subscriptions. This is a state-changing write, so a unique Idempotency-Key header is required (returns 400 MISSING_IDEMPOTENCY_KEY without it).

You may also attach an optional structured compliance profile — all fields below are optional and additive. The two sensitive identifiers, idNumber and taxId, are stored as a sha256 fingerprint plus the last 4 characters only; they are never persisted or returned in full. The response and the kyc.updated webhook echo back idNumberLast4 / taxIdLast4.

curl -X POST "https://mystocks.africa/api/v1/partner/users/usr_abc123/kyc" \
  -H "Authorization: Bearer pk_live_<key>" \
  -H "Idempotency-Key: kyc_usr_abc123_001" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "VERIFIED",
    "level": "BASIC",
    "provider": "sumsub",
    "reference": "kyc_session_88721",
    "idDocumentType": "NATIONAL_ID",
    "idNumber": "24681012",
    "dateOfBirth": "1990-04-17",
    "nationality": "KE",
    "taxResidency": "KE",
    "sanctionsResult": "CLEAR",
    "riskRating": "LOW",
    "consentAt": "2026-07-11T09:30:00Z"
  }'

{ "message": "KYC status updated.", "subAccountId": "usr_abc123", "kycStatus": "VERIFIED", "kycLevel": "BASIC", "profile": { "idDocumentType": "NATIONAL_ID", "idNumberLast4": "1012", "nationality": "KE", "taxResidency": "KE", "sanctionsResult": "CLEAR", "riskRating": "LOW" } }

Notification devices

GET /users/{userId}/devices · POST /users/{userId}/devices · DELETE /users/{userId}/devices/{deviceId}

Register mobile/web push tokens for a sub-account so your app can fan out user-visible notifications after receiving MyStocks webhooks or SSE events. MyStocks stores only a token hash plus tokenLast4; raw APNs/FCM/Expo/Web Push tokens are never returned.

curl -X POST "https://mystocks.africa/api/v1/partner/users/usr_abc123/devices" \
  -H "Authorization: Bearer pk_live_<key>" \
  -H "Idempotency-Key: device_usr_abc123_001" \
  -H "Content-Type: application/json" \
  -d '{"token":"ExpoPushToken[xxxxxxxxxxxxxxxxxxxxxx]","platform":"ios","provider":"expo","appId":"com.afritrade.app","deviceId":"device-42"}'