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.

Developer-controlled wallets depend on a single developer-held cryptographic key: the entity secret. Because Circle never stores it, you retain exclusive control over your wallets and bear sole responsibility for its security.

​
The entity secret and ciphertext

These two terms are distinct but inseparable: the entity secret is the key itself, and the ciphertext is the encrypted form you send in API requests.

​
Entity secret

The entity secret is a randomly generated 32-byte private key that authorizes sensitive wallet operations under your Circle account. What to know:
  • Scoped to your Circle account, not to individual API keys. API keys authenticate requests; the entity secret authorizes the wallet operations those requests perform.
  • Circle never stores a copy. Only you can authorize operations on your developer-controlled wallets.
  • Losing it without a recovery file means permanent loss of access to your wallets and funds.

​
Entity secret ciphertext

The entity secret ciphertext is the encrypted form of the entity secret, passed as entitySecretCiphertext in API request bodies. What to know:
  • Produced by encrypting the entity secret with Circle’s public RSA key before each request. Circle decrypts it server-side to verify authenticity and authorize the operation. For the encryption implementation, see the entity secret sample code on GitHub.
  • Each ciphertext is single-use. Reusing one causes the request to be rejected, which prevents replay attacks.
  • When you use the Circle Node.js SDK or Python SDK, re-encryption happens automatically before every call. If you make direct API calls without an SDK, you are responsible for re-encrypting for each request.

​
The recovery file

When you register your entity secret, Circle generates a recovery file tied to that secret. The recovery file is the only mechanism for resetting your entity secret through Circle Console if it is ever lost. What to know:
  • Without the recovery file, there is no path to recover access to your developer-controlled wallets or the funds they hold.
  • The recovery file is invalidated each time you rotate your entity secret. Each rotation produces a new one. Storing an old recovery file after rotation provides no protection.

​
Best practices

  • Store the entity secret securely. Use a secrets manager, hardware security module (HSM), or encrypted password manager. Never commit the entity secret to version control, include it in application configuration files, or allow it to appear in logs.
  • Save the recovery file immediately after registration. The recovery file can only be downloaded once, during the registration flow. If you skip this step, you must rotate your entity secret to generate a new one. Store it in a separate, secure location from the entity secret itself.
  • Rotate periodically. Rotating the entity secret limits exposure if it is ever silently compromised. Rotate on a regular schedule, such as every 180 days. Rotation takes effect immediately. Any in-flight API requests using the old entity secret will fail. Plan rotations during low-traffic periods and reinitialize pending requests afterward. Rotate in Circle Console.
  • Reset if compromised or lost. If your entity secret is lost or you suspect it has been compromised, use your recovery file to reset it in Circle Console. After a reset, the old entity secret is invalidated immediately and a new recovery file is generated.
If both the entity secret and the recovery file are lost, you cannot create new developer-controlled wallets or initiate transactions from existing wallets. There is no recovery path. Store both in separate, secure locations.