Skip to main content
In this guide, you learn how to generate, encrypt, and register an using the Circle SDK. The SDK simplifies your development process by securely handling encryption, registration, and rotation of the Entity Secret that secures your dev-controlled wallets.
Skip this guide if you already completed the Create a Dev-Controlled Wallet quickstart. You already registered an Entity Secret in your Circle Developer Account in that flow.

​
Prerequisites

  1. Create a Circle Developer Account and an API key.
  2. Install the applicable server-side SDK for your language:
    Use the following commands to install the SDK. You can view the package information on the npm site.
    npm install @circle-fin/developer-controlled-wallets --save
    For more information, visit the Node.js SDK.
If you are not using the Circle SDKs, you can generate and register your Entity Secret manually with standard libraries or CLI tools.

​
Introduction

The Entity Secret is a randomly generated 32-byte key used to secure dev-controlled wallets. After generation, it is encrypted into ciphertext for safe use in API requests. The ciphertext must be re-encrypted (rotated) whenever required by API operations.

​
1. Generate an Entity Secret

Use the SDK to generate your Entity Secret. This creates a 32-byte hex string and prints it in your terminal. 
import { generateEntitySecret } from "@circle-fin/developer-controlled-wallets";

generateEntitySecret();

​
2. Register the Entity Secret

Register your Entity Secret with Circle using the SDK. Both the encryption of the Entity Secret and its ciphertext registration is managed by the SDK automatically. 
import { registerEntitySecretCiphertext } from "@circle-fin/developer-controlled-wallets";

const response = await registerEntitySecretCiphertext({
  apiKey:
    "****_API_KEY:5bef73***************d000:89a4aa************************b09",
  entitySecret: "ecd4d5e33b8e***************************************c546",
  recoveryFileDownloadPath: "",
});
console.log(response.data?.recoveryFile);
Secure Your Entity Secret and Recovery FileYou are solely responsible for securing your Entity Secret and its recovery file. Failure to do so may result in the irreversible loss of access to your wallets and associated funds.
  • Store your Entity Secret securely: for example, in a password manager. This Entity Secret is required for future API calls.
  • Save the recovery file when registering your Entity Secret. Use the recoveryFileDownloadPath parameter in the SDK method and store the file in a safe, separate location. This file is the only way to reset your Entity Secret if it’s lost.
Note: Circle does not store your Entity Secret and cannot recover it for you.

​
Final Considerations

Keep the following points in mind when using your registered Entity Secret:
  • Each API request requires a new Entity Secret ciphertext. The SDK automatically re-encrypts the Entity Secret for each request when needed.
  • Circle’s APIs Requiring Entity Secret Ciphertext enforce one-time-use ciphertexts to prevent replay attacks.
  • Do not reuse ciphertexts across multiple API requests: reused ciphertexts will cause those requests to be rejected.
These practices ensure secure and compliant use of dev-controlled wallets.
The Entity Secret is associated with your Circle Console Account and is used to secure your dev-controlled wallets. It is not tied to individual API keys. API keys are used for authenticating your requests, while the Entity Secret is specifically for managing the security of your dev-controlled wallets.