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.

Registering your entity secret with Circle enables developer-controlled wallet operations. After completing these steps, your entity secret is active and your recovery file is saved.

​
Prerequisites

Before you begin, ensure you’ve: 
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

1

Generate an entity secret

Use the generateEntitySecret function from the Node.js SDK or the generate_entity_secret function from the Python SDK:
import { generateEntitySecret } from "@circle-fin/developer-controlled-wallets";

generateEntitySecret();
Copy the printed value and store it securely as CIRCLE_ENTITY_SECRET. You need it in the next step and for all future API calls.
2

Register the entity secret

Pass your API key, entity secret, and a local directory path to the registration function. The SDK encrypts the entity secret, registers it with Circle, and saves the recovery file to the path you provide:
import { registerEntitySecretCiphertext } from "@circle-fin/developer-controlled-wallets";

const response = await registerEntitySecretCiphertext({
  apiKey: process.env.CIRCLE_API_KEY ?? "",
  entitySecret: process.env.CIRCLE_ENTITY_SECRET ?? "",
  recoveryFileDownloadPath: "./recovery",
});

console.log(response.data?.recoveryFile);
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.