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

Opinion and Polyflight use these same four mutation paths. Current production Opinion trade/redemption flows do not call /credit-reversal; Polyflight also uses only debit, credit, and debit 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.

For a Polyflight full-contract test, select product polyflight, confirm the external user is a dedicated test user, use 1,000–10,000 IDR in 1,000-IDR steps, and choose a scenario: normal, debit-applied-then-timeout, credit-applied-then-timeout, definite rejection, duplicate-same, or duplicate-conflict. These calls use the real adapter and real test-user money; simulator results are separate.

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