Creating Wallets using API

Prerequisites

The following are examples on how commands are documented:

Service account or authenticated user with Wallets:Create permission
IBM Digital Asset Haven SDK installed and configured
Understanding of wallets and keys

Creating a wallet

Create a wallet on a specific network using SDK.

import { DfnsApiClient } from '@dfns/sdk'

const dfns = new DfnsApiClient({
  baseUrl: 'https://api.digitalassets.ibm.com/,
  // Your signer configuration
})

const wallet = await dfns.wallets.createWallet({
  body: {
    network: 'EthereumSepolia', // or 'Ethereum', 'Polygon', etc.
    name: 'My Wallet'
  }
})

console.log('Wallet ID:', wallet.id)
console.log('Address:', wallet.address)
console.log('Network:', wallet.network)

Request parameters


Parameter	Required	Description
`network`	Yes	Blockchain network
`name`	No	Human-readable wallet name
`tags`	No	Array of tags for organization

Response example

The response includes

{
  id: 'wa-xxx-xxx',
  network: 'EthereumSepolia',
  address: '0x...',
  signingKey: {
    id: 'ke-xxx-xxx',
    scheme: 'ECDSA',
    curve: 'secp256k1'
  },
  status: 'Active',
  dateCreated: '2024-01-15T10:30:00Z',
  name: 'My Wallet',
  tags: []
}

Adding a network to an existing wallet

For keys that support multiple networks (for example, EVM chains), add additional networks to an existing wallet’s key.

Acquire the key ID from an existing wallet.

const existingWallet = await dfns.wallets.getWallet({
  walletId: 'wa-xxx-xxx'
})

Create a new wallet on a different network using the same key.

const polygonWallet = await dfns.wallets.createWallet({
  body: {
    network: 'Polygon',
    name: 'My Polygon Wallet',
    keyId: keyId // Use existing key
  }
})

Note: Not all key types support all networks. EVM chains share the secp256k1 key type, so a single key can be used across Ethereum, Polygon, Arbitrum, and similar networks.

Creating wallets with tags

Use tags to organize wallets and apply policies.

const wallet = await dfns.wallets.createWallet({
  body: {
    network: 'Ethereum',
    name: 'Treasury Wallet',
    tags: ['treasury', 'cold-storage', 'eth-mainnet']
  }
})

Managing wallet tags

Adding tags

Add tags to a wallet:

await dfns.wallets.tagWallet({
  walletId: 'wa-xxx-xxx',
  body: {
    tags: ['operations', 'high-volume']
  }
})

Removing tags

Remove tags from a wallet:

await dfns.wallets.untagWallet({
  walletId: 'wa-xxx-xxx',
  body: {
    tags: ['high-volume'] // Tags to remove
  }
})

Updating wallet metadata

Update the wallet name:

await dfns.wallets.updateWallet({
  walletId: 'wa-xxx-xxx',
  body: {
    name: 'Updated Wallet Name'
  }
})

Listing wallets

List all wallets in your organization:

const wallets = await dfns.wallets.listWallets()

for (const wallet of wallets.items) {
  console.log(`${wallet.name}: ${wallet.address} (${wallet.network})`)
}

Filtering by tags

Filter wallets by tags:

const wallets = await dfns.wallets.listWallets({
  query: {
    tags: 'treasury' // Wallets with this tag
  }
})

Retrieving wallet details

Retrieve details for a specific wallet:

const wallet = await dfns.wallets.getWallet({
  walletId: 'wa-xxx-xxx'
})

console.log('Wallet:', wallet)

Retrieving wallet assets

Retrieve token balances:

const assets = await dfns.wallets.getWalletAssets({
  walletId: 'wa-xxx-xxx'
})

for (const asset of assets.assets) {
  console.log(`${asset.symbol}: ${asset.balance}`)
}

For more information on token balances, see Displaying balances.

Error handling

Handle common errors:

try {
  const wallet = await dfns.wallets.createWallet({
    body: {
      network: 'Ethereum',
      name: 'My Wallet'
    }
  })
} catch (error) {
  if (error.status === 403) {
    console.error('Permission denied - check Wallets:Create permission')
  } else if (error.status === 400) {
    console.error('Invalid request:', error.message)
  } else {
    console.error('Error creating wallet:', error)
  }
}

Webhooks

Subscribe to wallet events:

wallet.created — New wallet created
wallet.activated — Wallet activated
wallet.tags.modified — Wallet tags changed

For more information on configuring webhooks, see the Webhooks guide.