> ## Documentation Index
> Fetch the complete documentation index at: https://developers.circle.com/llms.txt
> Use this file to discover all available pages before exploring further.
# How-to: Pre-create wallets and assign on demand
> Create a pool of unassigned wallets in advance and assign them to new users on demand as they sign up.
Create a pool of developer-controlled wallets before users arrive so wallets are
ready to assign instantly. When a new user signs up, assign an available wallet
by updating its `name` and `refId` fields. This approach reduces sign-up latency
because wallet creation happens ahead of time rather than during registration.
**Cost consideration for Externally Owned Account (EOA) wallets**
Creating EOA wallets on mainnet incurs a minor expense per wallet. To optimize
costs, forecast user demand and batch-create wallets accordingly. For example,
prepare enough wallets to cover the expected demand for the next 30 days to
avoid unnecessary expenses.
## Prerequisites
Before you begin, ensure that you've:
* Created a
[Circle Developer Account and an API key](/w3s/circle-developer-account).
* [Registered your entity secret](/wallets/dev-controlled/register-entity-secret).
* Created a wallet set. If you haven't, complete the
[Create a dev-controlled wallet](/wallets/dev-controlled/create-your-first-wallet)
quickstart first.
* Installed [Node.js 22+](https://nodejs.org/) or
[Python 3.11+](https://www.python.org/).
* Installed the applicable server-side SDK for your language:
Use the following commands to install the SDK. You can
[view the package information on the npm site](https://www.npmjs.com/package/@circle-fin/developer-controlled-wallets).
```shell npm theme={null}
npm install @circle-fin/developer-controlled-wallets --save
```
```shell yarn theme={null}
yarn add @circle-fin/developer-controlled-wallets
```
For more information, visit the
[Node.js SDK](/sdks/developer-controlled-wallets-nodejs-sdk).
Use the following command to install the SDK with
[pip](https://pypi.org/project/pip/):
```shell theme={null}
pip install circle-developer-controlled-wallets
```
For more information, visit the
[Python SDK](/sdks/developer-controlled-wallets-python-sdk).
## Step 1. Create a pool of unassigned wallets
Call the create wallets endpoint with a `count` value but without `metadata`.
Omitting `metadata` creates wallets that have no `name` or `refId`, leaving them
available for assignment later.
You can create up to 200 wallets per request. If you need more, make additional
requests until you reach the required total.
```ts Node.js SDK theme={null}
import { initiateDeveloperControlledWalletsClient } from "@circle-fin/developer-controlled-wallets";
const client = initiateDeveloperControlledWalletsClient({
apiKey: process.env.CIRCLE_API_KEY!,
entitySecret: process.env.CIRCLE_ENTITY_SECRET!,
});
const response = await client.createWallets({
walletSetId: "your-wallet-set-id",
blockchains: ["ARC-TESTNET"],
count: 50,
accountType: "SCA",
});
console.log(response.data?.wallets);
```
```python Python SDK theme={null}
import os
from circle.web3 import developer_controlled_wallets
client = developer_controlled_wallets.DeveloperControlledWalletsClient(
api_key=os.getenv("CIRCLE_API_KEY"),
entity_secret=os.getenv("CIRCLE_ENTITY_SECRET"),
)
response = client.create_wallets(
wallet_set_id="your-wallet-set-id",
blockchains=["ARC-TESTNET"],
count=50,
account_type="SCA",
)
print(response.data.wallets)
```
The response contains the newly created wallets. The `name` and `refId` fields
are omitted because no `metadata` was provided:
```json Response theme={null}
{
"data": {
"wallets": [
{
"id": "66b67097-307e-5b46-a1d5-0b1577d67fd4",
"state": "LIVE",
"walletSetId": "018b42d2-cc38-7a1e-a47a-5927d2c97f16",
"custodyType": "DEVELOPER",
"address": "0xe55628c98f5d81daaa79b72899b38a3535d10990",
"blockchain": "ARC-TESTNET",
"accountType": "SCA",
"updateDate": "2024-01-22T22:57:20Z",
"createDate": "2024-01-22T22:57:20Z"
},
{
"id": "cda61d8d-7d46-5a39-a8a6-6b4a3d6fdac3",
"state": "LIVE",
"walletSetId": "018b42d2-cc38-7a1e-a47a-5927d2c97f16",
"custodyType": "DEVELOPER",
"address": "0x29b27e792b8b854e48e85ab4f456cf5a9f1579fb",
"blockchain": "ARC-TESTNET",
"accountType": "SCA",
"updateDate": "2024-01-22T22:57:20Z",
"createDate": "2024-01-22T22:57:20Z"
}
]
}
}
```
## Step 2. Store wallet IDs
Persist the returned wallet IDs in your system and mark each one as
**unassigned**. The storage mechanism is application-specific—you might use a
database table, a key-value store, or any other persistence layer your
application already uses.
Track each wallet's assignment status so that when a new user signs up, your
application can quickly select an unassigned wallet and avoid double-assigning
the same wallet to multiple users. A simple boolean flag or status column (for
example, `assigned: false`) works for most implementations.
## Step 3. Assign a wallet to a new user
When a user registers, select an unassigned wallet from the pool and call the
update wallet endpoint to set its `name` and `refId`. The `refId` field is
designed for linking wallets to entities in your own system, such as a user ID.
This endpoint does not require `entitySecretCiphertext`, so no entity secret
encryption is needed for this call.
```ts Node.js SDK theme={null}
const walletId: string = "66b67097-307e-5b46-a1d5-0b1577d67fd4";
const userId: string = "d4f2c8a1-9b3e-4f7d-a6e5-1c8b9d0e3f2a";
const updated = await client.updateWallet({
id: walletId,
name: "User Wallet",
refId: userId,
});
console.log(updated.data?.wallet);
```
```python Python SDK theme={null}
wallet_id = "66b67097-307e-5b46-a1d5-0b1577d67fd4"
user_id = "d4f2c8a1-9b3e-4f7d-a6e5-1c8b9d0e3f2a"
updated = client.update_wallet(
id=wallet_id,
name="User Wallet",
ref_id=user_id,
)
print(updated.data.wallet)
```
The response confirms the wallet now has the assigned `name` and `refId`:
```json Response theme={null}
{
"data": {
"wallet": {
"id": "66b67097-307e-5b46-a1d5-0b1577d67fd4",
"state": "LIVE",
"walletSetId": "018b42d2-cc38-7a1e-a47a-5927d2c97f16",
"custodyType": "DEVELOPER",
"refId": "d4f2c8a1-9b3e-4f7d-a6e5-1c8b9d0e3f2a",
"name": "User Wallet",
"address": "0xe55628c98f5d81daaa79b72899b38a3535d10990",
"blockchain": "ARC-TESTNET",
"accountType": "SCA",
"updateDate": "2024-01-22T23:15:42Z",
"createDate": "2024-01-22T22:57:20Z"
}
}
}
```
After the update succeeds, mark the wallet as **assigned** in your own system so
it is no longer available in the unassigned pool.
## Step 4. Verify the assignment
Call the list wallets endpoint filtered by `refId` to confirm the wallet is
correctly assigned to the user.
```ts Node.js SDK theme={null}
const userId: string = "d4f2c8a1-9b3e-4f7d-a6e5-1c8b9d0e3f2a";
const wallets = await client.listWallets({
refId: userId,
});
console.log(wallets.data?.wallets);
```
```python Python SDK theme={null}
user_id = "d4f2c8a1-9b3e-4f7d-a6e5-1c8b9d0e3f2a"
wallets = client.list_wallets(
ref_id=user_id,
)
print(wallets.data.wallets)
```
The response returns only wallets matching the specified `refId`:
```json Response theme={null}
{
"data": {
"wallets": [
{
"id": "66b67097-307e-5b46-a1d5-0b1577d67fd4",
"state": "LIVE",
"walletSetId": "018b42d2-cc38-7a1e-a47a-5927d2c97f16",
"custodyType": "DEVELOPER",
"refId": "d4f2c8a1-9b3e-4f7d-a6e5-1c8b9d0e3f2a",
"name": "User Wallet",
"address": "0xe55628c98f5d81daaa79b72899b38a3535d10990",
"blockchain": "ARC-TESTNET",
"accountType": "SCA",
"updateDate": "2024-01-22T23:15:42Z",
"createDate": "2024-01-22T22:57:20Z"
}
]
}
}
```