Skip to main content

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.

Use the POST /developer/wallets endpoint to batch-create dev-controlled wallets and link each one to an existing user in your system. Pass a metadata array with name and refId fields to associate each wallet with a user. You can create up to 200 wallets per request.

​
Prerequisites

Before you begin, ensure that you’ve:

​
Step 1. Prepare the metadata array

Build a metadata array where each element corresponds to one wallet you want to create. Each element accepts two fields:
  • name: A human-readable label for the wallet.
  • refId: Your internal user identifier (for example, a UUID from your database). Use this field to map the wallet back to the user in your system.
The length of the metadata array must exactly match the count value you pass in the request. If they differ, the API returns error 155503. For example, to create wallets for two users: 
const metadata = [
  { name: "Alice Wallet", refId: "user-uuid-1001" },
  { name: "Bob Wallet", refId: "user-uuid-1002" },
];

​
Step 2. Create the wallets

Call createWallets with your walletSetId, target blockchain, count, accountType, and the metadata array from Step 1. 
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: 2,
  accountType: "SCA",
  metadata: [
    { name: "Alice Wallet", refId: "user-uuid-1001" },
    { name: "Bob Wallet", refId: "user-uuid-1002" },
  ],
});
You can create up to 200 wallets per request. If you need more, make additional requests until you reach the required total.

​
Step 3. Map wallet IDs to your users

Inspect data.wallets in the response. Each wallet object includes the refId and name you provided, along with the assigned wallet id and address.
Response
{
  "data": {
    "wallets": [
      {
        "id": "66b67097-307e-5b46-a1d5-0b1577d67fd4",
        "state": "LIVE",
        "walletSetId": "018b42d2-cc38-7a1e-a47a-5927d2c97f16",
        "custodyType": "DEVELOPER",
        "refId": "user-uuid-1001",
        "name": "Alice Wallet",
        "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",
        "refId": "user-uuid-1002",
        "name": "Bob Wallet",
        "address": "0x29b27e792b8b854e48e85ab4f456cf5a9f1579fb",
        "blockchain": "ARC-TESTNET",
        "accountType": "SCA",
        "updateDate": "2024-01-22T22:57:20Z",
        "createDate": "2024-01-22T22:57:20Z"
      }
    ]
  }
}
Persist the wallet id against each user record in your database. Use the refId field to match each wallet in the response to the corresponding user in your system.