Simulator

Simulator tools let operators test launch, trade, redemption, webhook, and wallet-adjustment flows in staging without touching the real operator wallet for simulator-tagged users.

When simulator works now

Simulator is staging/local only and user-scoped.

• normal staging users still use the operator's real balance_adapter_type, usually rest_v1
• simulator users carry metadata.simulator = true
• simulator endpoints operate only on simulator-tagged users
• production returns 404 SIMULATOR_DISABLED

Main endpoints

• GET /api/operator/simulator/users
• POST /api/operator/simulator/users
• GET /api/operator/simulator/users/{id}
• PATCH /api/operator/simulator/users/{id}
• POST /api/operator/simulator/users/{id}/operations
• GET /api/operator/simulator/wallets/{externalUserId}
• PUT /api/operator/simulator/wallets/{externalUserId}
• POST /api/operator/simulator/operations

See full contract at /docs/operator-api/simulator.

Recommended flow

1. Create simulator user with metadata.simulator = true through dashboard or API.
2. Set starting simulator wallet balance.
3. Launch Mini App for same external_user_id.
4. Run buy flow.
5. Confirm trade and webhook evidence.
6. Run sell or redemption flow.

Example wallet setup

curl -X PUT "$BASE_URL/api/operator/simulator/wallets/test-user-001" \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "balance_minor": 500000
  }'

Example simulator mutation

curl -X POST "$BASE_URL/api/operator/simulator/operations" \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "external_user_id": "test-user-001",
    "direction": "debit",
    "amount_minor": 10000,
    "idempotency_key": "simulator:drill:001"
  }'

What to confirm

• idempotent repeat with same key returns same operation
• resulting statuses match docs in /docs/reference/statuses
• webhook events arrive for completed business actions

Safe usage rules

• use dedicated staging users only
• do not switch the whole operator off rest_v1 just to use simulator drills
• keep deterministic idempotency_key per drill step
• reset wallet state between drills when needed
• do not use simulator evidence as proof of real operator wallet readiness