Creating wallets via API

Create and manage wallets programmatically using the Dfns API.

This guide covers how to create wallets, add networks, and manage wallet metadata using the Dfns API and SDK.

Prerequisites

• Service account or authenticated user with Wallets:Create permission
• Dfns SDK installed and configured
• Understanding of wallets and keys

Creating a wallet

Create a wallet on a specific network using the SDK:

import { DfnsApiClient } from '@dfns/sdk'

const dfns = new DfnsApiClient({
  baseUrl: 'https://api.dfns.io',
  // 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	The blockchain network (see supported networks)
name	No	Human-readable name for the wallet
tags	No	Array of tags for organization

Response

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 (e.g., EVM chains), add additional networks to an existing wallet’s key:

// First, get the key ID from an existing wallet
const existingWallet = await dfns.wallets.getWallet({
  walletId: 'wa-xxx-xxx'
})

const keyId = existingWallet.signingKey.id

// 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
  }
})

Not all key types support all networks. EVM chains share the same key type (secp256k1), so a single key can be used across Ethereum, Polygon, Arbitrum, etc.

Creating wallets with tags

Use tags to organize wallets and target them with policies:

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

Managing wallet tags

Adding tags

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

Removing tags

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
  }
})

Getting wallet details

Get details for a specific wallet:

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

console.log('Wallet:', wallet)

Getting 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}`)
}

See displaying balances for more details on working with 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

See webhooks guide for configuration.

Related documentation

Wallets API

Complete API reference

Wallets and keys

Understand the wallet model

Creating transfers

Send transfers from wallets

Displaying balances

Query wallet assets