How-to: Generate and register your entity secret

An entity secret is a cryptographic key. Circle uses it to authorize signing on your developer-controlled wallets. You must generate and register an entity secret before creating any developer-controlled wallets.

Prerequisites

Before you begin, ensure that you’ve:

Created an API key in the Circle Console and added it to a .env file in your project:
.env
CIRCLE_API_KEY=YOUR_API_KEY
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.
Installed one of the following:
- Node.js v22.6 or later
- Python 3.11 or later

Installed the Developer-Controlled Wallets SDK:

npm pkg set type=module
npm install @circle-fin/developer-controlled-wallets

pip install circle-developer-controlled-wallets python-dotenv

If you are not using the Circle SDK, you can generate and register your entity secret manually using standard libraries or command-line tools.

Generate and register an entity secret

Create your script file with touch register-entity-secret.ts (Node.js) or touch register_entity_secret.py (Python), then add the following script, which:

Generates a 32-byte entity secret
Registers it with Circle
Saves the recovery file to ./recovery/ with a unique filename
Adds CIRCLE_ENTITY_SECRET to your .env file for local development (use a secrets manager in production)

Store your entity secret in a secrets manager or encrypted password manager. Save the recovery file to a separate, secure location. It is the only way to reset your entity secret if it is lost. Circle does not store your entity secret and cannot recover it for you. For more on storage and rotation best practices, see How the entity secret works.

import { randomBytes } from "node:crypto";
import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
import { registerEntitySecretCiphertext } from "@circle-fin/developer-controlled-wallets";

const apiKey: string | undefined = process.env.CIRCLE_API_KEY;
if (!apiKey) {
  throw new Error("CIRCLE_API_KEY is required. Set it in .env first.");
}

// Refuse to overwrite an existing entity secret in .env.
const existingEnv: string = existsSync(".env")
  ? readFileSync(".env", "utf8")
  : "";
if (/^CIRCLE_ENTITY_SECRET=/m.test(existingEnv)) {
  throw new Error(
    "CIRCLE_ENTITY_SECRET already exists in .env. Refusing to overwrite it.",
  );
}

// Generate a 32-byte entity secret. The SDK's generateEntitySecret() helper
// prints to stdout but doesn't return the value, so use crypto directly.
const entitySecret: string = randomBytes(32).toString("hex");
const recoveryFilePath: string = "./recovery";

mkdirSync(recoveryFilePath, { recursive: true });

await registerEntitySecretCiphertext({
  apiKey,
  entitySecret,
  recoveryFileDownloadPath: recoveryFilePath,
});

// For production, prefer a secrets manager over .env.
appendFileSync(".env", `\nCIRCLE_ENTITY_SECRET=${entitySecret}\n`);

console.log("Entity secret registered.");
console.log(`Recovery file saved to a new file in: ${recoveryFilePath}`);
console.log("CIRCLE_ENTITY_SECRET added to .env");

import os
import re

from dotenv import load_dotenv
from circle.web3 import utils

load_dotenv()

api_key = os.environ.get("CIRCLE_API_KEY")
if not api_key:
    raise RuntimeError("CIRCLE_API_KEY is required. Set it in .env first.")

existing_env = ""
if os.path.exists(".env"):
    with open(".env", "r") as f:
        existing_env = f.read()

if re.search(r"^CIRCLE_ENTITY_SECRET=", existing_env, re.MULTILINE):
    raise RuntimeError(
        "CIRCLE_ENTITY_SECRET already exists in .env. Refusing to overwrite it."
    )

entity_secret = os.urandom(32).hex()
recovery_file_path = "./recovery"

os.makedirs(recovery_file_path, exist_ok=True)

utils.register_entity_secret_ciphertext(
    api_key=api_key,
    entity_secret=entity_secret,
    recoveryFileDownloadPath=recovery_file_path,
)

with open(".env", "a") as f:
    f.write(f"\nCIRCLE_ENTITY_SECRET={entity_secret}\n")

print("Entity secret registered.")
print(f"Recovery file saved to a new file in: {recovery_file_path}")
print("CIRCLE_ENTITY_SECRET added to .env")

Run the script

From the same directory, run:

node --env-file=.env register-entity-secret.ts

python register_entity_secret.py

You should see:

Entity secret registered.
Recovery file saved to a new file in: ./recovery
CIRCLE_ENTITY_SECRET added to .env

If you see Cannot find module '@circle-fin/developer-controlled-wallets', run the script from the same directory where you ran npm install (or pip install). The SDK lives in that project’s node_modules or virtualenv and isn’t visible from other folders.

Wallets

Gas fees

Compliance

Contracts

How-to: Generate and register your entity secret

Prerequisites

Generate and register an entity secret

Run the script

​Prerequisites

​Generate and register an entity secret

​Run the script

Prerequisites

Generate and register an entity secret

Run the script