Skip to main content
In this guide you will learn how to generate, encrypt, and register an using the Circle SDK. The SDK simplifies your development process by securely handling encryption and registration.

​
Prerequisites

  1. Create a Developer Account and acquire an API key in the Console.
  2. Install the applicable server-side SDK for your language:
    • Node.js
    • Python
    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.

​
Introduction

The Entity Secret is a randomly generated 32-byte key used to secure developer-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

Finally, 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";

registerEntitySecretCiphertext({
  apiKey: "",
  entitySecret: "",
  recoveryFileDownloadPath: "",
});

​
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 developer-controlled wallets.

​
Next Steps

You’ve successfully registered your entity secret! Continue with the following guides:
  1. Create your first developer-controlled wallet
  2. Transfer Tokens across Wallets: Learn how to rotate and reset your Entity Secret.