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.

A wallet set is a container that groups your developer-controlled wallets under a single entity secret. All wallets in a set share the same entity secret, and EVM wallets in the same set share the same address. After completing this tutorial, you’ll have a wallet set and a developer-controlled wallet. The examples use an externally owned account (EOA) on Arc Testnet, but you can create a smart contract account (SCA) or use any supported blockchain.

​
Prerequisites

Before you begin, ensure you have:

​
Step 1. Set up your project

​
1.1. Create the project and install dependencies

Create a new directory and install the SDK for the path you want to use. 
# Create the project directory and initialize Node.js
mkdir dev-controlled-projects
cd dev-controlled-projects
npm init -y

# Set up module type and a start command
npm pkg set type=module
npm pkg set scripts.create-wallet="tsx --env-file=.env create-wallet.ts"

# Install runtime dependencies
npm install @circle-fin/developer-controlled-wallets

# Install dev dependencies
npm install --save-dev tsx typescript @types/node

​
1.2. Configure TypeScript (optional)

This step is optional. It helps prevent missing types in your IDE or editor.
Create a tsconfig.json file: 
npx tsc --init
Then, update the tsconfig.json file: 
cat <<'EOF' > tsconfig.json
{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "types": ["node"]
  }
}
EOF

​
1.3. Set environment variables

Create a .env file in the project directory:
.env
CIRCLE_API_KEY=YOUR_API_KEY
CIRCLE_ENTITY_SECRET=YOUR_ENTITY_SECRET
  • CIRCLE_API_KEY is your Circle Developer API key.
  • CIRCLE_ENTITY_SECRET is your registered entity secret.
Open .env in your editor rather than writing values with shell commands, and add .env to your .gitignore. This prevents credentials from leaking into your shell history or version control.

​
Step 2. Create your wallet

Write a script creates a wallet set and a developer-controlled wallet, then prints the wallet set ID, wallet ID, and wallet address.

​
2.1. Create the script

Create a create-wallet.ts (or create_wallet.py) file and add the following code. This code creates a wallet set first, and then creates a wallet within it: 
import { initiateDeveloperControlledWalletsClient } from "@circle-fin/developer-controlled-wallets";

const client = initiateDeveloperControlledWalletsClient({
  apiKey: process.env.CIRCLE_API_KEY!,
  entitySecret: process.env.CIRCLE_ENTITY_SECRET!,
});

async function main() {
  const walletSetResponse = await client.createWalletSet({
    name: "My First Dev-Controlled Wallet Set",
  });

  const walletSet = walletSetResponse.data?.walletSet;
  if (!walletSet?.id) {
    throw new Error("Wallet set creation failed: no ID returned");
  }

  const walletResponse = await client.createWallets({
    walletSetId: walletSet.id,
    blockchains: ["ARC-TESTNET"], // Can be any supported blockchain
    count: 1,
    accountType: "EOA", // Can be EOA or SCA
  });

  console.log("Wallet set response:", walletSetResponse.data);
  console.log("Wallet response:", walletResponse.data);
}

main().catch((err) => {
  console.error("Error:", err.message || err);
  process.exit(1);
});
If you are calling the API directly instead of using the SDK, you need two requests: one to create the wallet set and one to create the wallet. Replace the entity secret ciphertext and idempotency key in your request. The SDKs handle this automatically.

​
2.2. Run the script

Run the script from your project directory: 
npm run create-wallet
The output looks similar to: 
Wallet set response: {
  walletSet: {
    id: "9d4f..."
  }
}
Wallet response: {
  wallets: [
    {
      id: "1f29...",
      address: "0x1234...",
      blockchain: "ARC-TESTNET"
    }
  ]
}
Save the wallet ID and address for future wallet operations such as transferring tokens or checking balances.

​
Next steps

Now that you have a developer-controlled wallet, you can: