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
• dedicated simulator-user APIs set and preserve metadata.simulator = true
• launch metadata cannot set, clear, or override simulator classification
• simulator endpoints operate only on server-classified simulator 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 the simulator user through Simulator Users or the dedicated simulator-user API; it forces the server-side classification.
2. Set the starting simulator wallet balance.
3. Launch the same external_user_id; do not send metadata.simulator as a routing control.
4. Choose Opinion or enabled Polyflight and follow the real launch URL.
5. Confirm product, wallet-operation, ticket/trade, and webhook evidence.
6. Run the required payout/refund/compensation or Opinion sell/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