Paper and Demo Trading

MyStocks calls its non-production environment Sandbox. It is the equivalent of a paper/demo environment for partner integration testing, but it has its own key prefix and base URL.

The production-base compatibility surface is not the isolated sandbox. Deprecated /sandbox/* aliases remain only for existing integrations and must not be used in new examples.

What to test

• account creation and auto-registration;
• deposits, withdrawals, and idempotent retries;
• KYC-required and frozen-account behavior;
• quote expiry and mismatched quote rejection;
• market, limit, stop, and cancellation lifecycles;
• insufficient funds and holdings errors;
• webhook signatures, duplicates, ordering, and retry leases;
• SSE reconnect and Last-Event-ID replay;
• daily reconciliation and statement generation.

Sandbox parity boundaries

The sandbox mirrors the partner-facing treasury and revenue workflows needed for product design: GET/PATCH/POST /float, GET/PATCH /pricing, and master or sub-account GET /tax-lots and GET /gains. Pricing and treasury updates are virtual and never alter production settings. Tax lots and gains are derived from sandbox instant-fill orders using the same FIFO reporting model as production.

The following controls remain production-only and appear as non-executable reference entries in the API Tester: OAuth client credentials, enterprise security policy, go-live certification, reconciliation packs, OMS execution reports, SSE streaming, and resting-order replacement. OpenAPI operations declare this boundary with x-sandbox: false, and CI fails if the route, specification, and tester disagree.

Deterministic execution certification

List a customer's simulated orders with their actual sub-account ID:

curl "https://mystocks.africa/api/sandbox/v1/partner/test-tools/orders?subAccountId=usr_abc123&status=FILLED" \
  -H "Authorization: Bearer sk_sandbox_KEY"

Replace usr_abc123 with the ID returned by POST /users. Omitting subAccountId in sandbox returns 400 MISSING_PARAM; the production compatibility route treats it as an optional filter.

Expected restrictions and test outcomes

Exclude production-only operations from sandbox happy-path coverage. Test expected restrictions separately, asserting the response status and error payload. A correct rejection is a passing negative test, not a successful trade or payout. Unknown paths also use the sandbox fallback, so a 404 alone does not establish that the requested operation exists in production.

For replay tests, use a supported mutation, the same idempotency key and identical body (including clientOrderId), and verify that the wallet/order changes only once. Test changed-body rejection separately.

Advancing a deterministic scenario

Use POST /test-tools/trade on the sandbox base URL to create an isolated lifecycle scenario. Set outcome to PENDING, FILL, PARTIAL_FILL, REJECT, CANCEL, or FAIL_SETTLEMENT and provide a deterministic unitPriceUsd. The simulator updates virtual wallet reservations, holdings, execution records, and the same signed order webhooks used by production.

Advance pending and partially filled scenarios without MyStocks staff:

curl -X PATCH "$BASE/test-tools/orders/$ORDER_ID" \
  -H "Authorization: Bearer $MYSTOCKS_API_KEY" \
  -H "Idempotency-Key: scenario-step-2" \
  -H "Content-Type: application/json" \
  -d '{"subAccountId":"usr_abc123","action":"PARTIAL_FILL","quantity":5,"unitPriceUsd":10}'

Repeat with FILL for the remainder, then SETTLE. Use REJECT, CANCEL, or FAIL_SETTLEMENT to certify terminal failure handling. Every instruction requires an idempotency key so retries cannot apply the same wallet or holding movement twice.

Sandbox trades may settle instantly and do not reproduce every production timing characteristic. Always run the go-live certification checks before requesting production access.