> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dfns.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Create wallets via API

> Create and manage MPC wallets programmatically using the DFNS API, including delegation, tagging, multichain keys, and webhook notifications.

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](https://docs.dfns.co/core-concepts/vaults-wallets-and-keys.md)

## Creating a wallet

Create a wallet on a specific network using the SDK:

```typescript TypeScript theme={null}
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)
```

```go Go theme={null}
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)
```

```python Python theme={null}
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']}")
```

```java Java theme={null}
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](https://docs.dfns.co/networks/index.md)) |
| `name` | No | Human-readable name for the wallet |
| `tags` | No | Array of tags for organization |

> [!NOTE]
>
> 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](https://docs.dfns.co/guides/developers/delegated-wallets.md).

### Response

The response includes:

```typescript theme={null}
{
  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:

```typescript theme={null}
// 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
  }
})
```

> [!NOTE]
>
> Reusing a key requires the `Keys:Reuse` permission. Pass the key as `signingKey.id`; a top-level `keyId` is rejected by the API.

> [!NOTE]
>
> 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)

> [!NOTE]
>
> The recommended pattern is independent keys (the default in [Creating a wallet](#creating-a-wallet)) or shared-key reuse (see [Adding a network to an existing wallet](#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.

### Create the master key

The derivation root must be created with `masterKey: true`. A regular key is rejected with a `not a master key` error when you try to derive from it. Create it with the Keys API:

```typescript TypeScript theme={null}
const masterKey = await dfns.keys.createKey({
  body: { scheme: 'ECDSA', curve: 'secp256k1', masterKey: true }
})

const masterKeyId = masterKey.id
```

```go Go theme={null}
masterKeyFlag := true
masterKey, err := client.Keys.CreateKey(ctx, keys.CreateKeyRequest{
    Scheme:    "ECDSA",
    Curve:     "secp256k1",
    MasterKey: &masterKeyFlag,
})

masterKeyId := masterKey.ID
```

```python Python theme={null}
master_key = client.keys.create_key({
    "scheme": "ECDSA",
    "curve": "secp256k1",
    "masterKey": True
})

master_key_id = master_key["id"]
```

```java Java theme={null}
Key masterKey = client.keys.createKey(new CreateKeyRequest(
    KeyScheme.ECDSA,
    KeyCurve.secp256k1,
    null, // name
    true, // masterKey
    null, null, null, null
));

String masterKeyId = masterKey.id();
```

Creating a master key requires the `Keys:Create` permission. Deriving from it additionally requires `Keys:ChildKeys:Create`, and each child's `scheme` and `curve` must match the master's. Do not pass `storeId` or `delayDelegation` on a derive call; both are rejected.

### Derive a wallet

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

```typescript TypeScript theme={null}
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
      }
    }
  }
})
```

```go Go theme={null}
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,
})
```

```python Python theme={null}
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
        }
    }
})
```

```java Java theme={null}
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 wallet addresses 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 every EVM mainnet, the Ethereum, BSC, Base, Arbitrum, and Optimism testnets, Tron, Solana, and Bitcoin (native SegWit). Batch wallets are custodial — delegation is not supported.

### Start a batch

[Bulk create wallets](https://docs.dfns.co/api-reference/wallets/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`.

```json Request theme={null}
POST /wallets/bulk-create

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

```json Response theme={null}
{
  "id": "bwc-7jk0a-j19vv-4fhcj3452jceonu0",
  "status": "Pending"
}
```

| Parameter | Required | Description |
| - | - | - |
| `networks` | Yes | Networks the wallets are created on. They must share an address format: all EVM, Tron, Solana, or Bitcoin networks. Each address gets one wallet per network, all with the same address. |
| `count` | Yes | Number of addresses to create, 1 to 1,000,000. The batch holds `count` wallets per network. |
| `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](https://docs.dfns.co/api-reference/wallets/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](https://docs.dfns.co/api-reference/wallets/list-bulk-wallet-jobs) (`GET /wallets/bulk-create`).

### List the created wallets

[List bulk wallet job wallets](https://docs.dfns.co/api-reference/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:

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

## Managing wallet tags

### Adding tags

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

### Removing tags

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

## Updating wallet metadata

Update the wallet name:

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

## Listing wallets

List all wallets in your organization:

```typescript theme={null}
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:

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

## Getting wallet details

Get details for a specific wallet:

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

console.log('Wallet:', wallet)
```

## Getting wallet assets

Retrieve token balances:

```typescript theme={null}
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](https://docs.dfns.co/guides/developers/displaying-balances.md) for more details on working with balances.

## Error handling

Handle common errors:

```typescript theme={null}
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](https://docs.dfns.co/guides/developers/webhooks.md) for configuration.

## Related documentation

> [card] [Wallets API](https://docs.dfns.co/api-reference/wallets/index.md)
>
> Complete API reference

> [card] [Wallets and keys](https://docs.dfns.co/core-concepts/vaults-wallets-and-keys.md)
>
> Understand the wallet model

> [card] [Create transfers via API](https://docs.dfns.co/guides/developers/create-transfers.md)
>
> Send transfers from wallets

> [card] [Display balances](https://docs.dfns.co/guides/developers/displaying-balances.md)
>
> Query wallet assets


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.