# Paper and Demo Trading

> Use the MyStocks sandbox and integration test tools to validate trading workflows without moving real money.

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.

| Surface | Key | Base URL | Purpose |
| --- | --- | --- | --- |
| Sandbox environment | `sk_sandbox_` | `/api/sandbox/v1/partner` | Isolated virtual accounts and accelerated trading workflows |
| Canonical deterministic test tools | `sk_sandbox_` | `/api/sandbox/v1/partner/test-tools/*` | Simulated order, wallet, holding, execution, and webhook scenarios for new integrations |
| Restricted legacy compatibility | `pk_live_` | `/api/v1/partner/test-tools/*` | Virtual-event testing against approved live webhook configuration; never production trading |

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:

```bash
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](/partners/docs/going-live) checks before requesting production access.