Wirex Baas Onboarding

Wirex BaaS Onboarding Skill

Overview

Wirex BaaS onboarding is a three-step process that takes a user from zero state to a fully verified participant with access to crypto, card, and banking services.

Step 1: Smart Wallet Deployment

The wallet is an ERC-4337 Account Abstraction smart wallet built on Kernel v3.1. Deployment installs two modules:

• FundsManagement Executor -- manages on-chain fund operations for card debits, transfers, and banking flows.
• ExecutionDelayPolicy -- enforces a configurable time delay on sensitive operations.

Three SDK options are available:

After deployment, a webhook fires to POST /v2/webhooks/wallets confirming the wallet status.

See WALLET-DEPLOYMENT.md for the full deployment guide.

Step 2: User Registration

WARNING: wallet_address must be the user's EOA address (signer), NOT the Smart Wallet address.

Standard Registration (S2S)

POST /api/v2/user

Required headers: Authorization: Bearer {s2s_token}, Content-Type: application/json, X-Chain-Id: {chainId}

IMPORTANT: sharing_data and initial_data are mutually exclusive — do not provide both in the same request.

Hosted KYC Request

{
  "wallet_address": "0xAbC123...EOA",
  "initial_data": {
    "profile": {
      "email": "user@example.com"
    },
    "residence_address": {
      "country": "GB"
    }
  }
}

SumSub Shared KYC Request

Requires prior approval from Wirex (3-sided data sharing agreement with SumSub).

{
  "wallet_address": "0xAbC123...EOA",
  "sharing_data": {
    "sharing_token": "eyJhbGciOi...",
    "email": "user@example.com"
  }
}

Phone number from SumSub verification is automatically confirmed (no manual phone confirmation needed).

Reliance KYC Request

Requires prior Wirex approval after detailed audit.

{
  "wallet_address": "0xAbC123...EOA",
  "initial_data": {
    "profile": {
      "first_name": "Jane",
      "last_name": "Doe",
      "date_of_birth": "1990-01-15",
      "nationality": "GB",
      "email": "user@example.com",
      "phone_number": "+447700900123"
    },
    "residence_address": {
      "line1": "10 Downing Street",
      "line2": "",
      "city": "London",
      "state": "England",
      "post_code": "SW1A 2AA",
      "country": "GB"
    }
  }
}

Phone number (E.164 with + prefix) provided during reliance onboarding is automatically confirmed.

Response

{
  "id": "user-uuid"
}

Privy Registration

For partners using Privy authentication (headers carry Privy tokens):

POST /api/v1/user/retail

{
  "country": "GB"
}

Step 3: KYC Verification

Three KYC flows are available, each suited to different integration depths.

KYC Flow Comparison

Verification Statuses

KYC Completion Endpoints

After registration, direct the user to complete KYC:

See KYC-FLOWS.md for detailed flow walkthroughs with code examples.

Post-Onboarding Access

User Profile

After registration, retrieve the full user profile:

GET /api/v2/user

The response includes profile status, verification level, residence address, external provider info, and a capabilities array that governs which features the user can access.

See USER-PROFILE.md for the complete profile schema and capabilities system.

Webhooks

Wallet Webhook

POST /v2/webhooks/wallets

Fires when a wallet is deployed or its status changes. Expects 2xx within 10 seconds. Failed deliveries are NOT retried.

{
  "wallet_address": "0xA7E41d5680dE394EaA2ed417169DFf56840Fb3EE",
  "wallet_name": "Main Wallet",
  "wallet_status": "Confirmed",
  "wallet_type": "Primary",
  "balances": []
}

Wallet status values: Confirmed (properly configured), Rejected (invalid configuration), Unknown (indeterminate). Wallet type values: Primary, Secondary, Global, Card.

User Webhook (Legacy)

Note: This is a legacy webhook format that will be replaced with a v2 model in a future release.

POST /webhook/users

Fires when a user profile or verification status changes.

---

## Quick Start Checklist

1. Deploy smart wallet using one of three SDKs (see [WALLET-DEPLOYMENT.md](references/WALLET-DEPLOYMENT.md)).
2. Register user via `POST /api/v2/user` with the **EOA address** (not the smart wallet address).
3. Choose a KYC flow and complete verification (see [KYC-FLOWS.md](references/KYC-FLOWS.md)).
4. Poll `GET /api/v2/user` or listen for the user webhook to confirm `verification.status == "Approved"`.
5. Check capabilities to gate feature access (see [USER-PROFILE.md](references/USER-PROFILE.md)).
6. User is fully onboarded -- proceed to cards, transfers, or crypto operations.