Broker API

Getting Started with Broker API

MyStocks Partner API

Build and test a complete embedded-investing workflow in the MyStocks sandbox.

Integration guides Get a sandbox key

Explore endpoints

44 of 44

GET

/users

List sub-accounts

Full endpoint documentation

Sandbox availablelistUsers

Returns all sub-accounts for your partner key. Supports pagination and status filtering. Status filters are applied before pagination. Follow nextCursor even for an empty filtered page with hasMore=true. Invalid or foreign cursors return 400.

Parameters

statusactive | frozen | closed | ALLquery

cursorstringquery

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

limitintegerquery

Example: 100

externalIdstringquery

Exact partner-owned external identifier lookup; combined with status when supplied.

Headers

AuthorizationstringRequired

Bearer sk_sandbox_<your_key> for sandbox requests.

Response fields

accountsobject[]

accounts[].subAccountIdstring

MyStocks internal ID. Use in /users/{userId}/... paths.

Example: "usr_abc123"

accounts[].userIdstring

Compatible alias of subAccountId. Use subAccountId as the canonical stored identifier.

accounts[].externalIdstring

Your own user identifier as set at creation.

Example: "usr_8821"

accounts[].displayNamestring | null

Example: "Alice K."

accounts[].emailstring | null

Example: "alice@yourapp.com"

accounts[].kycStatusNONE | PENDING | VERIFIED | REJECTED

VERIFIED required for trading and asset subscriptions. REJECTED remains gated until re-asserted.

accounts[].kycLevelNONE | BASIC | FULL

BASIC = ID verified. FULL = enhanced due diligence.

accounts[].kycRejectionCodestring | null

Stable rejection code when kycStatus is REJECTED.

accounts[].kycRejectionReasonstring | null

Customer-safe remediation guidance when kycStatus is REJECTED.

accounts[].kycReviewedAtstring | null

Timestamp of the rejection decision.

accounts[].statusactive | frozen | closed

accounts[].walletBalancenumber

Current USD wallet balance.

Example: 1250

usersobject[]

Backward-compatible alias of accounts.

users[].subAccountIdstring

MyStocks internal ID. Use in /users/{userId}/... paths.

Example: "usr_abc123"

users[].userIdstring

Compatible alias of subAccountId. Use subAccountId as the canonical stored identifier.

users[].externalIdstring

Your own user identifier as set at creation.

Example: "usr_8821"

users[].displayNamestring | null

Example: "Alice K."

users[].emailstring | null

Example: "alice@yourapp.com"

users[].kycStatusNONE | PENDING | VERIFIED | REJECTED

VERIFIED required for trading and asset subscriptions. REJECTED remains gated until re-asserted.

users[].kycLevelNONE | BASIC | FULL

BASIC = ID verified. FULL = enhanced due diligence.

users[].kycRejectionCodestring | null

Stable rejection code when kycStatus is REJECTED.

users[].kycRejectionReasonstring | null

Customer-safe remediation guidance when kycStatus is REJECTED.

users[].kycReviewedAtstring | null

Timestamp of the rejection decision.

users[].statusactive | frozen | closed

users[].walletBalancenumber

Current USD wallet balance.

Example: 1250

countinteger

hasMoreboolean

nextCursorstring

Response codes

200Sub-account list.

Sandbox playground

Read-only sandbox request

status Optional · querycursor Optional · querylimit Optional · queryexternalId Optional · querySandbox API keyYour key stays in this page’s memory.

https://mystocks.africa/api/sandbox/v1/partner/users

Open in API Tester API Reference

Response schema

{
  "type": "object",
  "properties": {
    "accounts": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "subAccountId": {
            "type": "string",
            "example": "usr_abc123",
            "description": "MyStocks internal ID. Use in /users/{userId}/... paths."
          },
          "userId": {
            "type": "string",
            "description": "Compatible alias of subAccountId. Use subAccountId as the canonical stored identifier."
          },
          "externalId": {
            "type": "string",
            "example": "usr_8821",
            "description": "Your own user identifier as set at creation."
          },
          "displayName": {
            "type": [
              "string",
              "null"
            ],
            "example": "Alice K."
          },
          "email": {
            "type": [
              "string",
              "null"
            ],
            "example": "alice@yourapp.com"
          },
          "kycStatus": {
            "type": "string",
            "enum": [
              "NONE",
              "PENDING",
              "VERIFIED",
              "REJECTED"
            ],
            "description": "VERIFIED required for trading and asset subscriptions. REJECTED remains gated until re-asserted."
          },
          "kycLevel": {
            "type": "string",
            "enum": [
              "NONE",
              "BASIC",
              "FULL"
            ],
            "description": "BASIC = ID verified. FULL = enhanced due diligence."
          },
          "kycRejectionCode": {
            "type": [
              "string",
              "null"
            ],
            "description": "Stable rejection code when kycStatus is REJECTED."
          },
          "kycRejectionReason": {
            "type": [
              "string",
              "null"
            ],
            "description": "Customer-safe remediation guidance when kycStatus is REJECTED."
          },
          "kycReviewedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "Timestamp of the rejection decision."
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "frozen",
              "closed"
            ]
          },
          "walletBalance": {
            "type": "number",
            "example": 1250,
            "description": "Current USD wallet balance."
          }
        }
      }
    },
    "users": {
      "type": "array",
      "deprecated": true,
      "description": "Backward-compatible alias of accounts.",
      "items": {
        "type": "object",
        "properties": {
          "subAccountId": {
            "type": "string",
            "example": "usr_abc123",
            "description": "MyStocks internal ID. Use in /users/{userId}/... paths."
          },
          "userId": {
            "type": "string",
            "description": "Compatible alias of subAccountId. Use subAccountId as the canonical stored identifier."
          },
          "externalId": {
            "type": "string",
            "example": "usr_8821",
            "description": "Your own user identifier as set at creation."
          },
          "displayName": {
            "type": [
              "string",
              "null"
            ],
            "example": "Alice K."
          },
          "email": {
            "type": [
              "string",
              "null"
            ],
            "example": "alice@yourapp.com"
          },
          "kycStatus": {
            "type": "string",
            "enum": [
              "NONE",
              "PENDING",
              "VERIFIED",
              "REJECTED"
            ],
            "description": "VERIFIED required for trading and asset subscriptions. REJECTED remains gated until re-asserted."
          },
          "kycLevel": {
            "type": "string",
            "enum": [
              "NONE",
              "BASIC",
              "FULL"
            ],
            "description": "BASIC = ID verified. FULL = enhanced due diligence."
          },
          "kycRejectionCode": {
            "type": [
              "string",
              "null"
            ],
            "description": "Stable rejection code when kycStatus is REJECTED."
          },
          "kycRejectionReason": {
            "type": [
              "string",
              "null"
            ],
            "description": "Customer-safe remediation guidance when kycStatus is REJECTED."
          },
          "kycReviewedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "Timestamp of the rejection decision."
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "frozen",
              "closed"
            ]
          },
          "walletBalance": {
            "type": "number",
            "example": 1250,
            "description": "Current USD wallet balance."
          }
        }
      }
    },
    "count": {
      "type": "integer"
    },
    "hasMore": {
      "type": "boolean"
    },
    "nextCursor": {
      "type": "string",
      "nullable": true
    }
  }
}

curl -X GET 'https://mystocks.africa/api/sandbox/v1/partner/users' \
  -H "Authorization: Bearer $MYSTOCKS_SANDBOX_API_KEY"

This guide takes you from a sandbox credential to a testable customer-investing workflow.

Before you start

Create a partner session in the sandbox portal.
Keep the sandbox key server-side.
Review the source-preview TypeScript or Python SDK, or use curl.
Read authentication, errors, and idempotency.

Build the golden path

Create a sub-account with an idempotent POST /users request.
Deposit virtual funds with a unique Idempotency-Key.
Optionally assert KYC to test the production-style flow. Normal sandbox trading does not require KYC; production requires the applicable verification before trading.
Request a quote immediately before the trade.
Place the trade with the matching quoteId and the same idempotency key if retrying.
Consume the order, execution, wallet, and portfolio state through REST, webhooks, or SSE.
Run the reconciliation workflow before requesting production access.

The complete copyable workflow is in the Broker API quickstart. Use the API Tester to run individual operations and the API Reference for schemas.

Production transition

Sandbox success does not grant production access. Attach evidence for concurrency/idempotency, webhook retry handling, failover, reconciliation, security controls, and data governance through Going Live.

Was this page useful?

Your signal helps us tighten partner onboarding docs.

Send note

Last updated on