Wallet adapter

Manage the REST v1 wallet adapter configuration used by Mini App balance reads and wallet mutations.

Paths

GET /api/operator/wallet-adapter
PUT /api/operator/wallet-adapter
POST /api/operator/wallet-adapter/test

Required scopes

• wallet_adapter:read for GET
• wallet_adapter:write for PUT and POST /test

GET response

The response is masked. Secrets are never returned.

GET has no query parameters or body; only the bearer header and wallet_adapter:read scope are required.

Fields:

• balance_adapter_type
• auth_mode: env_var, encrypted, or none
• base_url
• timeout_ms
• balance_path
• debit_path
• credit_path
• debit_reversal_path
• has_bearer_token
• has_signature_secret
• currency_code
• updated_at

PUT body

Typical body:

{
  "base_url": "https://wallet.operator.example",
  "bearer_token": "operator-wallet-token",
  "signature_secret": "optional-signing-secret",
  "timeout_ms": 10000,
  "balance_path": "/balance",
  "debit_path": "/debit",
  "credit_path": "/credit",
  "debit_reversal_path": "/debit-reversal"
}

A configured secret may be omitted when updating non-secret fields. Sending a new secret replaces the stored encrypted value.

Current dashboard-managed production paths are balance, debit, credit, and debit reversal. The backend config parser also accepts credit_reversal_path for compatibility with the shared direction enum, but the current trade/redemption processor does not call credit reversal in production flows and the masked GET response does not expose that field.

The current API supports REST v1 only for IDR operators. Unsupported currency returns 400 REST_V1_UNSUPPORTED_CURRENCY.

Test body

Common and mode-specific fields:

Connection test:

{
  "mode": "connection",
  "external_user_id": "operator-user-123",
  "base_url": "https://wallet.operator.example",
  "bearer_token": "operator-wallet-token"
}

Full contract test:

{
  "mode": "full_contract",
  "external_user_id": "operator-user-123",
  "amount_minor": 1000,
  "confirmation": true
}

The full contract test performs real wallet mutations against the configured or submitted adapter config. Use a dedicated test user and a small amount.

The full contract sequence is: balance, debit, debit reversal, credit, second debit, final balance. The final balance must equal the initial balance; a mismatch requires manual review.

All mutation test requests include external_user_id, amount_minor, currency_code, idempotency_key, reason, and metadata. They do not include direction; the path selected for the step is the direction.

If mutation responses include external_user_id, the contract test surfaces it in the step output and fails the step when it does not match the requested test user.

Test response

{
  "mode": "connection",
  "success": true,
  "requires_manual_review": false,
  "steps": [
    {
      "step": "balance",
      "method": "GET",
      "path": "/balance",
      "status": "success",
      "latency_ms": 42,
      "remote_status": "succeeded",
      "external_user_id": "operator-user-123"
    }
  ]
}

Step status can be success, failed, or unknown.

requires_manual_review = true means a mutation or compensation step reached a state that needs operator follow-up before the test user should be reused.