How-to: Generate and Register Your Entity Secret

Generate an entity secret and register it with Circle.

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

• Created an API key in the Circle Console.
• Installed Node.js 22+ or Python 3.11+.
• Installed the developer-controlled wallets SDK:

Node.js

npm install @circle-fin/developer-controlled-wallets

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/recovery-file.dat
• Adds CIRCLE_ENTITY_SECRET to your .env file for local development (use a secrets manager in production)

It expects CIRCLE_API_KEY in your environment.

Node.js

import * as crypto from "node:crypto";
import * as fs 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 = fs.existsSync(".env")
  ? fs.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 = crypto.randomBytes(32).toString("hex");
const recoveryFilePath: string = "./recovery/recovery-file.dat";

fs.mkdirSync("./recovery", { recursive: true });

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

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

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

Secure your entity secret and recovery file.

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.

Run the script

From the same directory, run:

Node.js

npx tsx register-entity-secret.ts

You should see:

Entity secret registered.
Recovery file saved to: ./recovery/recovery-file.dat
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.