Wallet Adapter
Idempotency
Idempotency key formats and replay expectations for wallet operations.
Idempotency
Every wallet mutation must be idempotent by idempotency_key.
idempotency_key is required on every mutation request.
Why
- network timeout may occur after wallet write
- OpenPoly and operator wallet are not one atomic transaction
- retries and manual reconciliation must not double-charge the user
Expectations
- same key + same params -> same effective result
- same key + conflicting params -> reject or return original result, never create second mutation
- keep idempotency records long enough for retry, replay, and reconciliation workflows
- key scope is per operator wallet system; include enough persisted request params to detect conflicts
Example keys
mini_app_order:1:debitmini_app_order:1:debit_reversalmini_app_order:2:creditmini_app_redemption_item:42:credit
Recovery rule
Raw REST v1 mutation responses must return succeeded, failed, or pending. The Mini App processor may record an internal unknown result after a timeout, network failure, or ambiguous HTTP response; that internal state does not allow unknown in a direct mutation response.
| Direct mutation outcome | Mini App processor behavior |
|---|---|
| Timeout or network error | Preserve internal unknown state and send the primary operation to manual review. |
HTTP 408, 429, or 5xx | Preserve internal unknown state because the mutation may already have landed. |
Other HTTP 4xx | Treat as a failed mutation; do not assume a wallet write occurred. |
pending response | Preserve retry/manual-review state; do not automatically replay the primary mutation. |
When the operation is tied to a known operator user, direct mutation responses should include external_user_id so reconciliation tools can display the affected wallet without decoding the idempotency key.