Getting Started with Broker API
Build and test a complete embedded-investing workflow in the MyStocks sandbox.
Explore endpoints
44 of 44/users
List sub-accounts
Full endpoint documentationlistUsersReturns 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 | ALLquerycursorstringqueryOpaque cursor from nextCursor of the previous response. Omit for the first page.
limitintegerqueryExample: 100
externalIdstringqueryExact partner-owned external identifier lookup; combined with status when supplied.
Headers
AuthorizationstringRequiredBearer sk_sandbox_<your_key> for sandbox requests.
Response fields
accountsobject[]accounts[].subAccountIdstringMyStocks internal ID. Use in /users/{userId}/... paths.
Example: "usr_abc123"
accounts[].userIdstringCompatible alias of subAccountId. Use subAccountId as the canonical stored identifier.
accounts[].externalIdstringYour own user identifier as set at creation.
Example: "usr_8821"
accounts[].displayNamestring | nullExample: "Alice K."
accounts[].emailstring | nullExample: "alice@yourapp.com"
accounts[].kycStatusNONE | PENDING | VERIFIED | REJECTEDVERIFIED required for trading and asset subscriptions. REJECTED remains gated until re-asserted.
accounts[].kycLevelNONE | BASIC | FULLBASIC = ID verified. FULL = enhanced due diligence.
accounts[].kycRejectionCodestring | nullStable rejection code when kycStatus is REJECTED.
accounts[].kycRejectionReasonstring | nullCustomer-safe remediation guidance when kycStatus is REJECTED.
accounts[].kycReviewedAtstring | nullTimestamp of the rejection decision.
accounts[].statusactive | frozen | closedaccounts[].walletBalancenumberCurrent USD wallet balance.
Example: 1250
usersobject[]Backward-compatible alias of accounts.
users[].subAccountIdstringMyStocks internal ID. Use in /users/{userId}/... paths.
Example: "usr_abc123"
users[].userIdstringCompatible alias of subAccountId. Use subAccountId as the canonical stored identifier.
users[].externalIdstringYour own user identifier as set at creation.
Example: "usr_8821"
users[].displayNamestring | nullExample: "Alice K."
users[].emailstring | nullExample: "alice@yourapp.com"
users[].kycStatusNONE | PENDING | VERIFIED | REJECTEDVERIFIED required for trading and asset subscriptions. REJECTED remains gated until re-asserted.
users[].kycLevelNONE | BASIC | FULLBASIC = ID verified. FULL = enhanced due diligence.
users[].kycRejectionCodestring | nullStable rejection code when kycStatus is REJECTED.
users[].kycRejectionReasonstring | nullCustomer-safe remediation guidance when kycStatus is REJECTED.
users[].kycReviewedAtstring | nullTimestamp of the rejection decision.
users[].statusactive | frozen | closedusers[].walletBalancenumberCurrent USD wallet balance.
Example: 1250
countintegerhasMorebooleannextCursorstringResponse codes
200Sub-account list.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 /usersrequest. - 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
quoteIdand 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.
Verify each handoff
Open the guided sandbox workflow. Create a synthetic customer, copy the returned identity, add virtual USD funds and read the starting wallet. Request a fresh quote and use Prepare trade to carry its identifier into the trade request. Review each request before sending it.
The deterministic simulator provides a separate lifecycle path: pending, partial fill, fill and settlement. Compare executions, available and reserved cash, holdings and transaction entries after each transition. Cancellation and rejection should release reservations; a successful submission does not prove settlement.
| Failure | Recovery |
|---|---|
| Expired quote | Request a fresh quote before creating a new trade. |
| Response lost after a write | Retry the identical request with its original idempotency key. |
| Restricted customer | Inspect eligibility and KYC status; do not bypass production policy. |
| Rate limit or maintenance | Respect Retry-After and retry with bounded backoff. |
Download the tester report for request evidence, then verify webhook/SSE delivery in your receiving service. The report does not certify real provider execution. Continue with Going Live.
Was this page useful?
Your signal helps us tighten partner onboarding docs.
Last updated on
Broker API
Build embedded investing infrastructure with MyStocks accounts, funding, KYC, trading, events, reporting, and reconciliation.
Sub-Accounts
Create and manage end-user sub-accounts — each with an isolated USD wallet, portfolio, and order history. Covers create/auto-register, list/fetch, freeze, deposit, withdraw, and the KYC assertion API with an optional structured compliance profile.