Create wallets via 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)

import (
    dfns "github.com/dfns/dfns-sdk-go/v2"
    "github.com/dfns/dfns-sdk-go/v2/wallets"
)

// client, _ := dfns.NewClient(dfns.Options{...})

name := "My Wallet"
wallet, err := client.Wallets.CreateWallet(ctx, wallets.CreateWalletRequest{
    Network: "EthereumSepolia", // or "Ethereum", "Polygon", etc.
    Name:    &name,
})

fmt.Printf("Wallet ID: %s\n", wallet.ID)
fmt.Printf("Address: %s\n", *wallet.Address)
fmt.Printf("Network: %s\n", wallet.Network)

from dfns_sdk import DfnsClient, DfnsClientConfig

# config = DfnsClientConfig(auth_token="...", signer=signer)

with DfnsClient(config) as client:
    wallet = client.wallets.create_wallet({
        "network": "EthereumSepolia",  # or "Ethereum", "Polygon", etc.
        "name": "My Wallet"
    })

    print(f"Wallet ID: {wallet['id']}")
    print(f"Address: {wallet['address']}")
    print(f"Network: {wallet['network']}")

import co.dfns.sdk.*;
import co.dfns.sdk.wallets.model.*;

// DfnsClient client = new DfnsClient(config);

Wallet wallet = client.wallets.createWallet(new CreateWalletRequest(
    Network.EthereumSepolia, // or Network.Ethereum, Network.Polygon, etc.
    "My Wallet",             // name
    null, null, null, null, null
));

System.out.printf("Wallet ID: %s%n", wallet.id());
System.out.printf("Address: %s%n", wallet.address());
System.out.printf("Network: %s%n", 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

The example above creates an org-managed (custodial) wallet: your organization holds the signing authority. Just pass network (plus optional name/tags) and no delegateTo. Do not send a custodial field in the request body — the request body is strict and custodial is only returned in the response (as a boolean indicating the wallet type), not accepted as input. To create a non-custodial wallet owned by an end user, set delegateTo — see Implement delegated wallets.

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',
    signingKey: { id: keyId } // reuse the existing key
  }
})

Reusing a key requires the Keys:Reuse permission. Pass the key as signingKey.id; a top-level keyId is rejected by the API.

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.

Deriving wallets from a master key (HD)

The recommended pattern is independent keys (the default in Creating a wallet) or shared-key reuse (see Adding a network to an existing wallet). HD derivation is intended for cases where you need BIP-32 path semantics, for example to integrate with systems or tooling that assume hierarchical derivation. Each key share is generated independently by the MPC network, with stronger isolation than HD: compromising one key share reveals nothing about another.

Derive a child wallet from an existing master key by passing signingKey.deriveFrom with a keyId and an optional path. If path is omitted, DFNS auto-generates one.

const wallet = await dfns.wallets.createWallet({
  body: {
    network: 'Ethereum',
    name: 'Customer 0001',
    signingKey: {
      deriveFrom: {
        keyId: 'key-xxx-xxx',
        path: 'm/0/1' // optional, auto-generated if omitted
      }
    }
  }
})

signingKey := map[string]interface{}{
    "deriveFrom": map[string]interface{}{
        "keyId": "key-xxx-xxx",
        "path":  "m/0/1", // optional, auto-generated if omitted
    },
}
name := "Customer 0001"
wallet, err := client.Wallets.CreateWallet(ctx, wallets.CreateWalletRequest{
    Network:    "Ethereum",
    Name:       &name,
    SigningKey: &signingKey,
})

wallet = client.wallets.create_wallet({
    "network": "Ethereum",
    "name": "Customer 0001",
    "signingKey": {
        "deriveFrom": {
            "keyId": "key-xxx-xxx",
            "path": "m/0/1"  # optional, auto-generated if omitted
        }
    }
})

Map<String, Object> signingKey = Map.of(
    "deriveFrom", Map.of(
        "keyId", "key-xxx-xxx",
        "path", "m/0/1" // optional, auto-generated if omitted
    )
);

Wallet wallet = client.wallets.createWallet(new CreateWalletRequest(
    Network.Ethereum,
    "Customer 0001",
    signingKey,
    null, null, null, null
));

Path format

The path follows BIP-32 syntax: m/<index>(/<index>)*, with non-negative integer indices (e.g., m/0, m/0/1/2). Hardened paths (with ') are not supported. Each unique path under the same master key derives a distinct wallet with its own address.

Bulk wallet creation

Create up to 1,000,000 custodial wallets in a single batch. Bulk creation is asynchronous: the request mints one master key for the batch, derives every wallet from it via HD derivation, and returns a job handle immediately. Poll the job to follow progress and, once it completes, list the wallets it produced. Supported on EVM networks (Ethereum, BSC, Base, Arbitrum, Optimism, and their testnets), Tron, and Solana. Batch wallets are custodial — delegation is not supported.

Start a batch

Bulk create wallets — POST /wallets/bulk-create Every wallet in the batch shares a name prefix: the wallet at index N is named ${name}${N}. Requires Wallets:Create and Keys:Create (each batch mints a new master key); Wallets:Tags:Add is required if you pass tags.

Request

POST /wallets/bulk-create

{
  "network": "Ethereum",
  "count": 100000,
  "name": "customer-",
  "tags": ["batch-2026-q3"]
}

Response

{
  "id": "bwc-7jk0a-j19vv-4fhcj3452jceonu0",
  "status": "Pending"
}

Parameter	Required	Description
`network`	Yes	Network the wallets are created on (an EVM network, Tron, or Solana).
`count`	Yes	Number of wallets to create, 1 to 1,000,000.
`name`	Yes	Name prefix shared by every wallet; the wallet at index N is named `${name}${N}`. Max 94 characters.
`tags`	No	Up to 10 tags applied to every wallet in the batch.
`keystoreId`	No	Key store to mint the batch master key in. Defaults to your organization’s primary store.

Track the job

Get bulk wallet job — GET /wallets/bulk-create/{jobId} Poll the job for its status, completedCount against totalCount, and the masterKeyId the wallets are derived from.

Status	Meaning
`Pending`	Accepted, not yet started
`InProgress`	Wallets are being created
`Completed`	Every wallet was created
`PartiallyCompleted`	Some wallets were created; `reason` explains why the rest were not
`Failed`	No wallets were created; see `reason`

List all of your organization’s batch jobs with List bulk wallet jobs (GET /wallets/bulk-create).

List the created wallets

List bulk wallet job wallets — GET /wallets/bulk-create/{jobId}/wallets Once the job has completed, page through the wallets it created, ordered by wallet ID.

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.

Wallets API

Complete API reference

Wallets and keys

Understand the wallet model

Create transfers via API

Send transfers from wallets

Display balances

Query wallet assets

Introduction

Core Concepts

Platform Features

Networks

Solutions

Guides

Advanced

Prerequisites

Creating a wallet

Request parameters

Response

Adding a network to an existing wallet

Deriving wallets from a master key (HD)

Path format

Bulk wallet creation

Start a batch

Track the job

List the created wallets

Creating wallets with tags

Managing wallet tags

Adding tags

Removing tags

Updating wallet metadata

Listing wallets

Filtering by tags

Getting wallet details

Getting wallet assets

Error handling

Webhooks

Wallets API

Wallets and keys

Create transfers via API

Display balances

​Prerequisites

​Creating a wallet

​Request parameters

​Response

​Adding a network to an existing wallet

​Deriving wallets from a master key (HD)

​Path format

​Bulk wallet creation

​Start a batch

​Track the job

​List the created wallets

​Creating wallets with tags

​Managing wallet tags

​Adding tags

​Removing tags

​Updating wallet metadata

​Listing wallets

​Filtering by tags

​Getting wallet details

​Getting wallet assets

​Error handling

​Webhooks

​Related documentation

Wallets API

Wallets and keys

Create transfers via API

Display balances

Prerequisites

Creating a wallet

Request parameters

Response

Adding a network to an existing wallet

Deriving wallets from a master key (HD)

Path format

Bulk wallet creation

Start a batch

Track the job

List the created wallets

Creating wallets with tags

Managing wallet tags

Adding tags

Removing tags

Updating wallet metadata

Listing wallets

Filtering by tags

Getting wallet details

Getting wallet assets

Error handling

Webhooks

Related documentation