Create and Manage Wallets

A Wallet represents an on-chain deposit and execution address provisioned under an Application Account. You can programmatically deploy wallets across supported blockchains, link them directly to end-users, query asset balances, and manage operational controls such as auto-sweeping and wallet state.

Prerequisites

Before starting this guide, ensure you have:

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

The Plan

We’ll go through: Pre-Step: Fetch supported blockchains using GET /v2/chains to retrieve target blockchain identifiers.

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

Pre-Step: Fetch Supported Blockchains & Assets

To identify valid blockchain network identifiers before provisioning a wallet, you can fetch the list of supported networks and rechargeable currencies using the endpoints below.

1. Get List of Supported Blockchains & Assets

Send a GET /v2/chains request to retrieve all supported networks, token standards, and chain configurations.

Sample Response

{
  "success": true,
  "data": [
    {
      "slug": "ethereum-sepolia",
      "name": "Ethereum",
      "symbol": "ETH",
      "decimals": 18,
      "onchain": {
        "protocol": "EVM",
        "chainId": 1
      },
      "nativeCurrency": {
        "name": "Ether",
        "symbol": "ETH",
        "decimals": 18
      },
      "isTestnet": false,
      "standards": [
        "ERC20"
      ],
      "media": {
        "url": "https://cdn.openxswitch.com/public/logos/svg/eth.svg",
        "type": "image/svg+xml"
      },
      "blockExplorer": "https://etherscan.io"
    }
  ],
  "totalPage": 123,
  "pageNo": 123,
  "pageLimit": 123
}

💡 Selecting the Right Network Value When creating a wallet in Step 1, you can pass the name (e.g., "Ethereum") in the blockchainfield. Using the name is recommended for standard network routing unless targeting a specific testnet environment.

Step 1: Create a Wallet via API

To provision a new wallet, send a POST request to the /v2/wallets endpoint.

URL: https://api.openxswitch.com/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
 }

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, polygon).
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

You can modify wallet metadata, toggle auto-sweeping, or adjust the wallet’s active status using the PATCH endpoint.

💡 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

To inspect real-time token or native cryptocurrency balances, query the balances endpoint. You must provide either the walletId or the on-chain address as a parameter.

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.
Send and Transfer Tokens: Programmatically move digital assets from a specified wallet address to an external or internal recipient address.

Developer Guides

Migration Guides

Prerequisites

The Plan

Pre-Step: Fetch Supported Blockchains & Assets

1. Get List of Supported Blockchains & Assets

Sample Response

Step 1: Create a Wallet via API

Key Request Parameters

Sample Response

Step 2: Update Wallet Settings

Field Breakdown

Step 3: Fetch Wallet Balances

Query Parameters

Sample Response

Next Steps

​Prerequisites

​The Plan

​Pre-Step: Fetch Supported Blockchains & Assets

​1. Get List of Supported Blockchains & Assets

​Sample Response

​Step 1: Create a Wallet via API

​Key Request Parameters

​Sample Response

​Step 2: Update Wallet Settings

​Field Breakdown

​Step 3: Fetch Wallet Balances

​Query Parameters

​Sample Response

​Next Steps

Prerequisites

The Plan

Pre-Step: Fetch Supported Blockchains & Assets

1. Get List of Supported Blockchains & Assets

Sample Response

Step 1: Create a Wallet via API

Key Request Parameters

Sample Response

Step 2: Update Wallet Settings

Field Breakdown

Step 3: Fetch Wallet Balances

Query Parameters

Sample Response

Next Steps