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

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.