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

Deposit

POST /users/{userId}/deposit

Credit a sub-account wallet. The USD amount is deducted from your master wallet and added to the sub-account. Pass localAmount, localCurrency, and fxRate for the audit trail — they do not affect how much USD is credited. 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":500,"localAmount":655000,"localCurrency":"KES","fxRate":1310,"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 funds to your master wallet. You are responsible for paying the user in their local currency at the rate you applied. 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" } }