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.
const wallet = await dfns.wallets.createWallet({
body: {
network: 'Ethereum',
name: 'Treasury Wallet',
tags: ['treasury', 'cold-storage', 'eth-mainnet']
}
})
await dfns.wallets.tagWallet({
walletId: 'wa-xxx-xxx',
body: {
tags: ['operations', 'high-volume']
}
})
await dfns.wallets.untagWallet({
walletId: 'wa-xxx-xxx',
body: {
tags: ['high-volume'] // Tags to remove
}
})
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})`)
}
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}`)
}
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 createdwallet.activated - Wallet activatedwallet.tags.modified - Wallet tags changed
See webhooks guide for configuration.
