How-to: Generate and register your entity secret

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

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

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")

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

python register_entity_secret.py