Quickstart: Create a dev-controlled wallet

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 that you’ve:

Obtained an API key from the Circle Console
Generated and registered an entity secret
Installed one of the following:
- Node.js v22.6 or later
- Python 3.11 or later

Step 1. Set up your project

1.1. Install additional dependencies

From the same directory where you set up your entity secret, add a run script and install the TypeScript development dependencies.

npm pkg set scripts.create-wallet="node --env-file=.env create-wallet.ts"
npm install --save-dev typescript @types/node

# The dependencies you installed in the entity secret setup are all you need.

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. Verify environment variables

Your .env file from the entity secret setup already contains both values you need. Confirm it includes:

.env

CIRCLE_API_KEY=YOUR_API_KEY
CIRCLE_ENTITY_SECRET=YOUR_ENTITY_SECRET

CIRCLE_API_KEY is your Circle API key.
CIRCLE_ENTITY_SECRET is your registered entity secret.

Step 2. Create your wallet

Write a script that 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

In your project directory, create create-wallet.ts (Node.js) or create_wallet.py (Python) and add the following code. When run, this code creates a wallet set first, and then creates a wallet in 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);
});

from circle.web3 import utils, developer_controlled_wallets
from dotenv import load_dotenv
import os
import json

load_dotenv()

client = utils.init_developer_controlled_wallets_client(
    api_key=os.getenv("CIRCLE_API_KEY"),
    entity_secret=os.getenv("CIRCLE_ENTITY_SECRET")
)

wallet_sets_api = developer_controlled_wallets.WalletSetsApi(client)
wallets_api = developer_controlled_wallets.WalletsApi(client)

try:
    wallet_set = wallet_sets_api.create_wallet_set(
        developer_controlled_wallets.CreateWalletSetRequest.from_dict({
            "name": "My First Dev-Controlled Wallet Set"
        })
    )

    wallet = wallets_api.create_wallet(
        developer_controlled_wallets.CreateWalletRequest.from_dict({
            "walletSetId": wallet_set.data.wallet_set.actual_instance.id,
            "blockchains": ["ARC-TESTNET"],
            "count": 1,
            "accountType": "EOA"
        })
    )

    print(json.dumps(json.loads(wallet_set.model_dump_json()), indent=2))
    print(json.dumps(json.loads(wallet.model_dump_json()), indent=2))
except developer_controlled_wallets.ApiException as e:
    print("Exception when calling the Circle Wallets API: %s\n" % e)

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

python create_wallet.py

The output looks similar to:

Wallet set response: {
  walletSet: {
    id: "9d4f..."
  }
}
Wallet response: {
  wallets: [
    {
      id: "1f29...",
      address: "0x1234...",
      blockchain: "ARC-TESTNET"
    }
  ]
}

{
  "data": {
    "wallet_set": {
      "id": "9d4f..."
    }
  }
}
{
  "data": {
    "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.

Step 3. Add more wallets to your set (optional)

To add more wallets to the same blockchain or to add wallets on a different blockchain, call createWallets again on the same wallet set. Pass your existing wallet set ID as walletSetId. The count parameter is the number of wallets created per blockchain. Add the following inside your main() function from Step 2:

const arcWalletResponse = await client.createWallets({
  walletSetId: "your-wallet-set-id", // wallet set ID from Step 2
  blockchains: ["ARC-TESTNET"],
  count: 1,
});

console.log("Arc wallet:", arcWalletResponse.data);

arc_wallet = wallets_api.create_wallet(
    developer_controlled_wallets.CreateWalletRequest.from_dict({
        "walletSetId": "your-wallet-set-id",  # wallet set ID from Step 2
        "blockchains": ["ARC-TESTNET"],
        "count": 1,
    })
)

print(json.dumps(json.loads(arc_wallet.model_dump_json()), indent=2))

This creates an EOA wallet by default. To create an SCA wallet instead, add accountType: "SCA" to the request. To add a wallet on a different blockchain, pass a different value for blockchains—for example, "SOL-DEVNET" for Solana Devnet. You can also pass multiple blockchains in a single call—createWallets creates count wallets per blockchain. All wallets created this way belong to the same wallet set and share the same entity secret.

Next steps

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

Fund the wallet: Get testnet USDC from the Circle Faucet.
Send tokens across wallets: Transfer USDC from one developer-controlled wallet to another.
Build payment workflows with Arc App Kit: Use the Circle Wallets adapter to add token transfers, swaps, bridging, and chain-agnostic unified balances to your app without building each integration yourself.

Wallets

Gas fees

Compliance

Contracts

Quickstart: Create a dev-controlled wallet

Prerequisites

Step 1. Set up your project

1.1. Install additional dependencies

1.2. Configure TypeScript (optional)

1.3. Verify environment variables

Step 2. Create your wallet

2.1. Create the script

2.2. Run the script

Step 3. Add more wallets to your set (optional)

Next steps

​Prerequisites

​Step 1. Set up your project

​1.1. Install additional dependencies

​1.2. Configure TypeScript (optional)

​1.3. Verify environment variables

​Step 2. Create your wallet

​2.1. Create the script

​2.2. Run the script

​Step 3. Add more wallets to your set (optional)

​Next steps

Prerequisites

Step 1. Set up your project

1.1. Install additional dependencies

1.2. Configure TypeScript (optional)

1.3. Verify environment variables

Step 2. Create your wallet

2.1. Create the script

2.2. Run the script

Step 3. Add more wallets to your set (optional)

Next steps