Simulator

Simulator mode lets operator test Mini App integration without real wallet movement.

When simulator works

Simulator endpoints work only when operator is configured with balanceAdapterType = simulator.

If simulator is not enabled, simulator API returns 404 SIMULATOR_DISABLED.

Main endpoints

• GET /api/operator/simulator/wallets/{externalUserId}
• PUT /api/operator/simulator/wallets/{externalUserId}
• POST /api/operator/simulator/operations
• GET /api/operator/simulator/operations/{idempotencyKey}

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

Recommended flow

1. Create or top up simulator wallet for test user.
2. Launch Mini App for same external_user_id.
3. Run buy flow.
4. Inspect simulator operation by idempotency_key.
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 $OPERATOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "balance_minor": 500000
  }'

Example simulator mutation

curl -X POST "$BASE_URL/api/operator/simulator/operations" \
  -H "Authorization: Bearer $OPERATOR_API_KEY" \
  -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
• operation lookup resolves by exact idempotency_key
• resulting statuses match docs in /docs/reference/statuses
• webhook events arrive for completed business actions

Safe usage rules

• use dedicated staging users only
• 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