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:

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:

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.

Existing simulation tools and boundaries

Use POST /test-tools/trade with outcome set to PENDING, FILL, PARTIAL_FILL, REJECT, CANCEL or FAIL_SETTLEMENT. Advance existing orders with PATCH /test-tools/orders/{orderId} using the documented actions. The proposed X-Sandbox-Execution-Outcome headers are not the contract. Corporate-action cash simulations and market-session override endpoints are not currently available.

Actual currency wallets use ?walletContract=2; obtain an FX quote before confirming its quoteId with a stable idempotency key. Trades remain USD-settled. This testing flow does not prove broker settlement, FIX connectivity, hedging or regulatory compliance.

How do I test expiry and a specific rejection?

Create a pending order with the existing test tools, then PATCH its order ID. Send subAccountId with every transition and an Idempotency-Key. Use EXPIRE to close the unfilled remainder, release only unused reservations and preserve earlier fills. The event is order.cancelled, with canonicalStatus: EXPIRED, orderLifecycle: EXPIRED and cancelReason: SIMULATED_EXPIRY. Expiry is not a rejection.

curl -X PATCH "$API_BASE/test-tools/orders/$ORDER_ID" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{"subAccountId":"customer-1","action":"EXPIRE"}'

For REJECT, optionally supply rejectionCode: INSUFFICIENT_FUNDS, KYC_REQUIRED, MARKET_CLOSED, COMPLIANCE_HOLD, TECHNICAL_ISSUE or OTHER (the default). The code is saved on the order and included in order.rejected. A code on another action is rejected. Frozen accounts cannot receive any new fills, including a fill followed by simulated settlement failure. They can still cancel, expire, reject or mark existing filled orders settled. These are deterministic virtual tests, not an exchange execution or settlement guarantee.

Corporate-action and market-session simulations require a separate tenant-isolated scenario design; they are not available through these actions or arbitrary request headers.