Overview

Wallet adapter is operator-owned server-to-server API used by OpenPoly to read balances and execute wallet mutations.

Ownership split

OpenPoly owns:

• Opinion quote, order, and redemption pipeline
• Polyflight native-IDR ticket and payment state
• signed webhook dispatch Operator owns:
• wallet balances
• debit and credit execution
• wallet auth secret
• wallet operation observability

Required contract paths

• GET /balance
• POST /debit
• POST /credit
• POST /debit-reversal

REST v1 has path-based mutation direction. OpenPoly selects the endpoint from the operation type; the JSON request body does not include a direction field.

The shared adapter config also has a credit_reversal_path field for compatibility with the internal direction enum, but the current Mini App trade/redemption processor does not call POST /credit-reversal in production flows.

Mutation request body

All mutation endpoints use the same JSON body shape:

{
  "external_user_id": "operator-user-123",
  "amount_minor": 10000,
  "currency_code": "IDR",
  "idempotency_key": "mini_app_order:1:debit",
  "reason": "mini_app_buy_order",
  "metadata": {}
}

OpenPoly sends every field below on every mutation request.

external_user_id is required for debit, credit, and reversal paths. OpenPoly resolves it from the Mini App launch/session user and sends it again on each wallet mutation.

Required metadata by flow

Metadata is part of the production contract. Operators must accept additional fields without rejecting the request.

The Opinion full-contract adapter test uses mini_app_wallet_adapter_test with test-only metadata. Polyflight full-contract checks use its native production reasons and metadata plus test context; their cleanup debit uses mini_app_wallet_adapter_test_cleanup. Neither creates a real product order or ticket. See Native wallet contract for exact Polyflight keys, amounts, and metadata names. Polyflight purchase and payout amounts are already native IDR and do not use an Opinion FX snapshot.

The zero-amount loss credit durably acknowledges a losing result without changing the balance or creating monetary accounting entries. It uses the existing credit/idempotency/reconciliation lifecycle, not a separate endpoint or webhook event. Only this narrowly defined Polyflight loss contract accepts zero; generic wallet mutations and user-entered adapter-test amounts remain positive. Historical losses are not backfilled, and existing planned/dispatched requests keep their original evidence.

Core rules

• Every mutation must be idempotent.
• Direct mutation response status is required and must be succeeded, failed, or pending. Other response fields are optional unless an endpoint page says otherwise.
• Optional receipt echoes are still checked: non-null external_user_id, idempotency_key, currency_code, and amount_minor must identify the dispatched operation. A mismatch produces REST_V1_MUTATION_IDENTITY_MISMATCH and an internal unknown, not a successful or safely rejected payment.
• Timeout, network failure, or an invalid HTTP 2xx response makes the primary mutation ambiguous. Without a valid REST v1 response body, HTTP 408, 429, or 5xx is also ambiguous; another HTTP 4xx is a failed mutation.
• A valid response body with status = succeeded, failed, or pending is honored even on non-2xx. pending remains ambiguous.
• Do not retry an ambiguous primary debit or credit automatically. An operator may already have applied it. Reconciliation may authorize a retry only with the original key.
• Unknown wallet state must not be reported as success.
• OpenPoly order state and wallet state are not one atomic transaction.
• Manual review may be required when remote wallet result is unknown.

Recommended headers

Authorization: Bearer {opera...ken}
X-Polynion-Request-Id: req_...
X-Polynion-Timestamp: 2026-06-18T00:00:00.000Z

Optional request signing may also be enabled with X-Polynion-Signature.

Dashboard setup

Operator admins configure the adapter in Operator Dashboard → Integrations → Wallet Adapter.

The dashboard stores:

• base URL;
• bearer token;
• optional signing secret;
• timeout and path overrides.

Bearer and signing secrets are encrypted before storage. After saving, OpenPoly only shows whether a secret is configured; plaintext and encrypted payloads are never returned by the API.

Validation tests

The API exposes two modes through POST /api/operator/wallet-adapter/test, both requiring wallet_adapter:write:

1. Connection — calls only GET /balance for a supplied external user ID. Integration UAT (/integrations/uat) exposes this as Run safe UAT checks, using saved settings.
2. Full contract — performs real wallet mutations through the API or API Playground with explicit confirmation. Opinion checks balance, debit, debit reversal, credit, second debit, then final balance. Polyflight has separate normal and failure/idempotency scenarios, including a zero-amount loss acknowledgement and duplicate in its normal sequence.

Wallet Settings saves configuration; it is not a full-contract test form. See Wallet adapter API for inputs and scenario outcomes. Stop and reconcile a test user whenever requires_manual_review is true; an expected failure scenario can meet its contract expectation while still needing manual review.