Migration From V1 To V2

This walkthrough guides you step-by-step through migrating your infrastructure from OpenXSwitch v1 to OpenXSwitch v2. v2 introduces an upgraded smart account architecture delivering gasless operations, native testnet execution, auto-sweeping rules, native transaction batching, and isolated account containers.

🏗 Summary of Changes

Feature / Component	v1	v2
User Onboarding	`sub-wallet` model	`users` primitive
Address Generation	Token-specific address generation	Account & multi-chain wallets model
Testing Environment	Off-chain simulation sandbox	Native testnet execution
Batch Transactions	Not supported	Native batching support
Smart Wallets	Not supported	Built-in smart contract wallet support
Gasless Transactions	Not supported	Built-in Paymaster & Fee-Payer sponsorship
Accounts	Not supported	Container model for logical fund isolation

Account Architecture Overview

In v1, the architecture relied on a Prime Wallet and Sub-Wallet model (1:N), where a single central Prime Wallet managed liquidity and treasury operations across multiple sub-wallets. In v2, infrastructure hierarchy transitions to an Accounts container model:

Account-Based Isolation: You can create an account specifically for your application or business unit. All wallets generated can be attached directly to that account.
Fund & Access Control Segregation: This structure ensures complete separation of funds, permissions, policies, and operational controls at both the Account and Wallet levels.

Within this new architecture, accounts typically fall into two categories:

Settlement Account: Serves as the primary operational or treasury container for managing enterprise funds, sweeps, and global balances.
Users Account: Acts as an isolated container assigned to individual end-users to manage dedicated smart wallet instances and balances.

Base URL Updates

Update your base request URL across all API client configurations:

v1 Base URL: [https://api.openxswitch.com/v1]
v2 Base URL: [https://api.openxswitch.com/v2]

Step-by-Step Migration Walkthrough

Step 1: User Onboarding (`sub-wallet` ➔ `users`)

In v1, user identities were represented as sub-wallet records. In v2, this primitive is renamed to users. Existing sub-wallet IDs are maintained throughout the migration.

🔄 Action: `Create Sub-Wallet` ➔ `Create User`

v1 : POST /v1/sub-wallet/create
v2: POST /v2/users

Request Changes

Replace clientUserId with refId, rename name to displayName, and drop canTrade. v1 (POST /v1/sub-wallet/create):

{
  "email": "sam.vwede@example.com",
  "name": "Sam Vwede", 
  "clientUserId": "client_001", 
  "canTrade": true
}

{
  "id": "63e1b8c2f18e310bb11f8a9c",
  "clientUserId": "client_001",
  "email": "walletName@openxswitch.org",
  "name": "OX Wallet",
  "isActive": "true",
  "language": "en_US",
  "canTrade": false,
  "createdAt": "2025-01-17T10:00:00Z",
  "updatedAt": "2025-01-17T12:00:00Z",
  "workspaceId": "63e1b8c2f18e310bb11f8a9c"
}

v2 (POST /v2/users):

{
  "email": "sam.vwede@example.com",
  "displayName": "Sam.Vwede", 
  "refId": "client_001"
}

{
  "id": "63e1b8c2f18e310bb11f8a9c",
  "refId": "client_001",
  "email": "sam.vwede@example.com",
  "displayName": "Sam.Vwede",
  "isActive": "true",
  "createdAt": "2025-01-17T10:00:00Z",
  "updatedAt": "2025-01-17T12:00:00Z",
  "workspaceId": "63e1b8c2f18e310bb11f8a9c"
}

📘 Migration Note Existing sub-wallets maintain their original identifiers during migration. To retrieve or update migrated records, replace /v1/sub-wallet?subWalletId={id} with /v2/users?userId={id} in your endpoints.

Step 2: Blockchain Wallets & Addresses (`sub-wallet/address` ➔ `wallets`)

In v1, distinct addresses had to be generated per token and network. In v2, a single wallet address handles deposits across all supported tokens on a given network protocol.

🔄 Action: `Generate Deposit Address` ➔ `Create Smart Wallet`

v1: POST /v1/sub-wallet/address
v2: POST /v2/wallets

Request Changes

Pass userId and accountId directly in the payload, provide an idempotencyKey, and designate the specific target blockchain network string (e.g., ethereum). v1 (POST /v1/sub-wallet/address):

{
  "subWalletId": "63e1b8c2f18e310bb11f8a9c", 
  "coin": "USDT", 
  "chain": "Ethereum"
}

{
  "id": "34303043....",
  "coin": "Bitcoin",
  "chain": "Ethereum",
  "network": "Mainnet",
  "address": "0x123456789abcdef",
  "workspaceId": "60f7d4b5b4d5c909a85b8d7e",
  "createdAt": null,
  "walletId": "63e1b8c2f18e310bb11f8a9c",
  "tag": "Memo123"
}

v2 (POST /v2/wallets):

{
  "idempotencyKey": "8d5be8f5-a8e7-4e8a-b715-0e7d6f2a6d04", 
  "accountId": "123e4567-e89b-12d3-a456-426614174000", 
  "blockchain": "ethereum", 
  "name": "user_1 Wallet", 
  "refId": "ref_user_1", 
  "userId": "user_1", 
  "autoSweep": false
}

{
  "id": "8e6f5877-d71a-4017-a3eb-3d1d4464e274",
  "address": "0x1234567890123456789012345678901234567890",
  "blockchain": "ethereum",
  "protocol": "EVM",
  "network": "mainnet",
  "isEvmCompatible": true,
  "type": "smart_wallet",
  "intent": "deposit",
  "gaslessWithdraw": true,
  "autoSweep": true,
  "state": "LIVE",
  "custodyType": "DEVELOPER",
  "userId": "user_1",
  "accountId": "WALLET_ACCOUNT_ID",
  "workspaceId": "WORKSPACE_ID",
  "createdAt": "2022-01-01T00:00:00.000Z",
  "updatedAt": "2022-01-01T00:00:00.000Z",
  "decimals": 18,
  "name": "Wallet 1",
  "refId": "WALLET_REF_ID"
}

Step 3: Checking Balances (`sub-wallet/assets` ➔ `users/balances`)

🔄 Action: `Get Sub-Wallet Assets` ➔ `Get User Balances`

v1 : GET /v1/sub-wallet/assets?subWalletId={id}
v2 : GET /v2/users/balances?userId={id}

Response Comparison

v2 provides comprehensive token metadata (standards, contract addresses, raw/formatted amounts) instead of single-string outputs.

{
  "coin": "USDT",
  "balance": "1.234",
  "frozen": "0.123",
  "updatedAt": "2023-01-01T00:00:00Z"
}

{
  "token": {
    "name": "Tether USD",
    "symbol": "USDT",
    "blockchain": "ethereum",
    "isNative": true,
    "standard": "ERC-20",
    "tokenAddress": "0xdac17f958d2ee523a2206206994597c13d831ec7",
    "decimals": 6
  },
  "amount": {
    "formatted": "479000.10",
    "raw": "47900010"
  },
  "environment": "mainnet",
  "createdAt": "2025-04-02T17:20:42.160Z",
  "updatedAt": "2025-04-02T17:20:42.160Z"
}

⚠️ Deprecation Notice: Internal Off-Chain Transfers Off-chain free internal transfers available in v1 are deprecated. In v2, all asset movements are executed transparently on-chain.

Step 4: Outbound Transactions (`withdraw/create` ➔ `transactions/withdraw`)

🔄 Action: `Create Sub-Wallet Withdrawal` ➔ `Execute Withdrawal Transaction`

v1: POST /v1/withdraw/create
v2: POST /v2/transactions/withdraw

Request Changes

Pass walletId instead of subWalletId, supply toAddress instead of withdrawalAddress, and include an idempotencyKey.

{
  "subWalletId": "63e1b8c2f18e310bb11f8a9c",
  "coin": "USDT",
  "chain": "Ethereum",
  "withdrawalAddress": "0x1234567890123456789012345678901234567890",
  "amount": "0.5",
  "clientTxId": "txn_ref_123",
  "fee": "0.01",
  "memo": "Test transfer"
}

{
  "idempotencyKey": "0e472f6b-336b-4d4f-87d6-4f93e4e4e4e4",
  "walletId": "0e472f6b-336b-4d4f-87d6-4f93e4e4e4e4",
  "amount": "0.5",
  "withdrawalAddress": "0x1234567890123456789012345678901234567890",
  "token": "USDT",
  "blockchain": "ethereum-mainnet",
  "refId": "txn_ref_123",
  "note": "This is a test transaction",
  "metadata": {
    "employeeId": "EMP001"
  }
}

🔄 Action: `Fetch Transaction History`

Transaction lookup endpoints have been unified under a consolidated GET /v2/transactions resource with filtering options:

Fetch Deposits:
- v1: GET /v1/sub-wallet/deposit
- v2: GET /v2/transactions?txType=incoming
Fetch Withdrawals:
- v1: GET /v1/sub-wallet/withdraw
- v2: GET /v2/transactions?txType=outgoing

Step 5: Instant Swaps (`instant-swap` ➔ `swap`)

🔄 Action: `Execute Instant Swap` ➔ `Create Swap Transaction`

v1: POST /v1/instant-swap
v2: POST /v2/swap

Here is the revised Migration Guide tailored specifically to your exact platform updates:

🔄 What Does This Mean for Existing Integrations?

If you are migrating your existing integration to the upgraded infrastructure, use this guide to update your endpoints, identifiers, wallet provisioning, and webhook event handlers.

👤 1. Users Infrastructure (Zero-Friction User Migration)

No User Re-creation Needed: You do not need to re-create users for your existing customers.
Reused Identifiers: All existing sub-wallets created via the API have been migrated automatically. Your previous subWalletId now acts directly as the new userId.
What to Change: Update the base URL endpoint in your requests—your existing sub-wallet IDs continue to work seamlessly without additional mapping.

👛 2. Address & Wallet Management

In the updated model, a user utilizes a single wallet container across supported assets, requiring you to provision chain-specific wallet addresses using the updated wallet creation endpoint.

Provisioning Wallets: Call the new wallet creation endpoint per supported chain:

JSON

{
  "idempotencyKey": "8d5be8f5-a8e7-4e8a-b715-0e7d6f2a6d04",
  "accountId": "123e4567-e89b-12d3-a456-426614174000",
  "blockchain": "ethereum",
  "name": "user_1 Wallet",
  "refId": "ref_user_1",
  "userId": "user_1",
  "autoSweep": false
}

accountId: Retrieve your Account ID by completing the workspace setup via the Accounts & Workspace Console.
userId: Pass your existing subWalletId directly into this field.
EVM Address Consistency: To ensure a user shares the exact same blockchain address across all EVM-compatible chains, pass the same refId string for every EVM chain provisioning request.
Wallet-Level Auto-Sweep: Auto-sweep capabilities are now configured directly at the individual wallet level. Set "autoSweep": true if you want automatic fund sweeps enabled for that specific wallet.

💸 3. Transactions

Endpoint Updates: Update all payment, deposit, and withdrawal endpoints to the new transaction URL paths.
Idempotency Headers/Fields: Pass standard idempotency keys on state-changing transaction endpoints to ensure safe retry logic.

🔔 4. Webhook Event Consumption

Refer to the complete Webhook Event Documentation for the updated topic structure and full payload schema reference.

Update Event Names: Update your webhook listeners to match the new topic identifiers (e.g., replace legacy topics with wallets:deposit.success, wallets:withdraw.success, wallets:swap.success).
Update Payload Parsing: Modify your application code to handle the updated event payload schema (e.g., parsing params.amount.value, params.amount.rawValue, and structured params.wallet objects).

Developer Guides

Migration Guides

🏗 Summary of Changes

Account Architecture Overview

Base URL Updates

Step-by-Step Migration Walkthrough

Step 1: User Onboarding (`sub-wallet` ➔ `users`)

🔄 Action: `Create Sub-Wallet` ➔ `Create User`

Request Changes

Step 2: Blockchain Wallets & Addresses (`sub-wallet/address` ➔ `wallets`)

🔄 Action: `Generate Deposit Address` ➔ `Create Smart Wallet`

Request Changes

Step 3: Checking Balances (`sub-wallet/assets` ➔ `users/balances`)

🔄 Action: `Get Sub-Wallet Assets` ➔ `Get User Balances`

Response Comparison

Step 4: Outbound Transactions (`withdraw/create` ➔ `transactions/withdraw`)

🔄 Action: `Create Sub-Wallet Withdrawal` ➔ `Execute Withdrawal Transaction`

Request Changes

🔄 Action: `Fetch Transaction History`

Step 5: Instant Swaps (`instant-swap` ➔ `swap`)

🔄 Action: `Execute Instant Swap` ➔ `Create Swap Transaction`

🔄 What Does This Mean for Existing Integrations?

👤 1. Users Infrastructure (Zero-Friction User Migration)

👛 2. Address & Wallet Management

💸 3. Transactions

🔔 4. Webhook Event Consumption

​🏗 Summary of Changes

​Account Architecture Overview

​Base URL Updates

​Step-by-Step Migration Walkthrough

​Step 1: User Onboarding (sub-wallet ➔ users)

​🔄 Action: Create Sub-Wallet ➔ Create User

Request Changes

​Step 2: Blockchain Wallets & Addresses (sub-wallet/address ➔ wallets)

​🔄 Action: Generate Deposit Address ➔ Create Smart Wallet

Request Changes

​Step 3: Checking Balances (sub-wallet/assets ➔ users/balances)

​🔄 Action: Get Sub-Wallet Assets ➔ Get User Balances

Response Comparison

​Step 4: Outbound Transactions (withdraw/create ➔ transactions/withdraw)

​🔄 Action: Create Sub-Wallet Withdrawal ➔ Execute Withdrawal Transaction

Request Changes

​🔄 Action: Fetch Transaction History

​Step 5: Instant Swaps (instant-swap ➔ swap)

​🔄 Action: Execute Instant Swap ➔ Create Swap Transaction

​🔄 What Does This Mean for Existing Integrations?

​👤 1. Users Infrastructure (Zero-Friction User Migration)

​👛 2. Address & Wallet Management

​💸 3. Transactions

​🔔 4. Webhook Event Consumption

🏗 Summary of Changes

Account Architecture Overview

Base URL Updates

Step-by-Step Migration Walkthrough

Step 1: User Onboarding (`sub-wallet` ➔ `users`)

🔄 Action: `Create Sub-Wallet` ➔ `Create User`

Step 2: Blockchain Wallets & Addresses (`sub-wallet/address` ➔ `wallets`)

🔄 Action: `Generate Deposit Address` ➔ `Create Smart Wallet`

Step 3: Checking Balances (`sub-wallet/assets` ➔ `users/balances`)

🔄 Action: `Get Sub-Wallet Assets` ➔ `Get User Balances`

Step 4: Outbound Transactions (`withdraw/create` ➔ `transactions/withdraw`)

🔄 Action: `Create Sub-Wallet Withdrawal` ➔ `Execute Withdrawal Transaction`

🔄 Action: `Fetch Transaction History`

Step 5: Instant Swaps (`instant-swap` ➔ `swap`)

🔄 Action: `Execute Instant Swap` ➔ `Create Swap Transaction`

🔄 What Does This Mean for Existing Integrations?

👤 1. Users Infrastructure (Zero-Friction User Migration)

👛 2. Address & Wallet Management

💸 3. Transactions

🔔 4. Webhook Event Consumption