Wallet adapter settings

Wallet adapter settings define how OpenPoly talks to operator wallet system.

Core decisions

• REST v1 base URL
• operator currency code
• operator-hosted callback paths
• outbound bearer token
• optional signature secret
• timeout expectation

REST v1 mode

Use for real operator-hosted wallet integration.

The dashboard saves balance_adapter_type = rest_v1. Staging simulator behavior is user-scoped through simulator-tagged users, not an operator-wide dashboard adapter mode.

Expected operator-hosted paths:

• /balance
• /debit
• /credit
• /debit-reversal

Current production trade/redemption flows do not call /credit-reversal.

Full contract: /docs/wallet-adapter/overview

Required backend behavior

• every mutation uses idempotency key
• ambiguous primary mutations stop for manual review
• compensation retries reuse the original idempotency key
• currency code must stay consistent with operator config
• mutation JSON bodies include external_user_id, but not direction; the endpoint path supplies direction

Secret handling

• configured secrets are encrypted server-side and never shown back
• dashboard responses show only has_bearer_token, has_signature_secret, and auth_mode
• store outbound auth secret in operator secret manager too
• store optional signing secret separately
• never paste live secrets into tickets or chat

Validation tests

Connection test calls GET /balance for an explicit external_user_id.

Full contract test requires confirmation and performs real wallet mutations using a small amount:

1. balance
2. debit
3. debit reversal
4. credit
5. second debit
6. final balance

The final balance must equal the initial balance.

If a compensation-sensitive step fails, the result can set requires_manual_review = true.

Use a dedicated test external_user_id. The test really debits and credits that user's operator wallet balance.

Timeout guidance

REST v1 adapter default timeout is 10000 ms.

If operator wallet may exceed timeout, reduce its synchronous processing time. A timeout leaves the primary mutation ambiguous and requires manual review.

Common misconfigurations

• wrong currency code
• non-idempotent debit or credit handling
• signature secret mismatch
• treating simulator drills as proof that the real REST v1 wallet is production-ready