Overview

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

Ownership split

OpenPoly owns:

• Mini App UI
• quote and execution pipeline
• trade and redemption state
• webhook dispatch

Operator owns:

• wallet balances
• debit and credit execution
• wallet auth secret
• wallet operation observability

Required paths

• GET /balance
• POST /debit
• POST /credit
• POST /debit-reversal
• GET /operation/{idempotency_key}

Core rules

• Every mutation must be idempotent.
• Every mutation must be queryable by idempotency 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 {operator_wallet_api_secret}
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.