Create and Manage Wallets

​

Prerequisites

• Obtained an API key from the OpenXSwitch Console.
• Configured an Application Account: An active accountId generated via the API or dashboard. See Get Started with Account Management for details.

​

The Plan

1. Creating a Wallet via API: Provisioning a chain-specific wallet address scoped to an account.
2. Updating Wallet Settings: Managing wallet activity state (isActive), display labels, and auto-sweep configurations.
3. Fetching Wallet Balances: Querying asset holdings by wallet ID or blockchain address.
4. Next Steps: Configuring treasury sweeps.

​

Step 1: Create a Wallet via API

URL: https://api.openxswitch.com/v2/wallets

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

​

Key Request Parameters

• idempotencyKey (string, required): A unique string to prevent duplicate wallet creation requests.
• accountId (string, required): The parent Application Account container.
• blockchain (string, required): Target network identifier (e.g., ethereum-mainnet, polygon-mainnet).
• name (string, optional): A human-readable display label for internal tracking.
• userId (string, optional): Pass a userId during creation to link this wallet directly to an end-user identity.
• refId (string, optional): Client reference identifier. Re-using the same refId across different EVM chains ensures deterministically identical wallet addresses.
• autoSweep (boolean, optional): Set to true to automatically route incoming deposits directly into your primary Settlement Account treasury. Defaults to false.

​

Sample Response

{
  "success": true,
  "data": {
    "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 2: Update Wallet Settings

💡 User Association If a wallet was created without a userId, you can link the wallet to a user identity during an update request by supplying the userId field.

URL: https://api.openxswitch.com/v2/wallets?walletId={walletId}
{
    "userId": "user_1",
    "name": "Primary User 1 Wallet",
    "isActive": true,
    "autoSweep": true
 }

​

Field Breakdown

• name (string, optional): Updated display name for internal tracking.
• userId (string, optional): Links or updates the owner user entity for this wallet.
• autoSweep (boolean, optional): Enables or disables automatic treasury sweeping rules for incoming funds.
• isActive (boolean, optional): Set to false to freeze wallet actions.

⚠️ Important Security Rule If isActive is set to false, the wallet is disabled. Disabled wallets cannot withdraw or swap funds.

​

Step 3: Fetch Wallet Balances

URL: https://api.openxswitch.com/v2/wallets/balances?walletId={walletId}

​

Query Parameters

• walletId (string, conditional): The unique ID of the wallet (Required if address is omitted).
• address (string, conditional): The on-chain wallet address (Required if walletId is omitted).
• blockchain (string, optional): Filter results to a specific network.
• token (string, optional): Filter by a specific asset symbol or contract address (e.g., USDT).

​

Sample Response

{
  "success": true,
  "data": [
    {
      "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"
    }
  ],
  "totalPage": 123,
  "pageNo": 123,
  "pageLimit": 123
}

​

Next Steps

• Auto Collection and Sweep Rule: Configure automated collection rules to aggregate user deposits into your central Settlement Account.