Build the Complete Wallet Flow

Use this checklist to turn the tutorial steps into one backend workflow.

1. Initialize the integration

• Keep the Base URL, API Key, and HMAC key in a secret manager.
• Check /health and /time; synchronize the caller clock.
• Generate a fresh timestamp, nonce, and signature for every protected request.
• Discover asset and network IDs from the target environment.

2. Provision the customer wallet

• Query accounts by your stable customer uid.
• Reuse the intended active USER account or create it once.
• Persist the customer-to-account mapping.
• Issue an address for the selected asset and network and display both network and memo requirements.

3. Process deposits

• Discover external deposits with a dedicated EXTERNAL cursor.
• Upsert by deposit_id and save next_cursor transactionally.
• Poll newly discovered non-final deposits by ID.
• Use the balance as the current position and the ledger as the finalized audit record.

4. Process an external withdrawal

validate address → quote → customer confirmation
  → create with unique client_request_id
  → recover by client_request_id after response loss
  → poll withdrawal_id to a final state

• Require an external transfer quote before submission.
• Persist client_request_id before sending the create request.
• Never resubmit only because the response timed out.
• Complete the customer request only when both statuses are COMPLETED and tx_hash is valid.

5. Synchronize and reconcile

Maintain separate cursors for:

• external deposits
• account withdrawals
• account ledger

The deposit and withdrawal cursors discover records. Poll non-final records by ID because cursors do not report later state changes. The ledger is append-only and can be synchronized by cursor.

Production rules

IMPORTANT

Apply these rules before using the flow with real customer funds.

• Never expose API or HMAC keys in a mobile or browser client.
• Authorize every wallet action in your backend; an account ID alone is not authorization.
• Never reuse a client_request_id across internal or external withdrawals.
• Use integer or decimal-safe asset calculations.
• Branch on HTTP status, error.code, and error.action, not localized message text.
• Limit retries, use backoff, and recover create results before resubmitting.
• Store the API request_id for diagnostics without logging credentials.

Use the Wallet API Reference for complete schemas and status contracts.