How the entity secret works

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.

​

Wallet set

A wallet set is a hierarchical deterministic (HD) wallet. Every wallet in the set is derived from the same cryptographic root, the entity secret. What to know:

• One entity secret backs every wallet set in your Circle account. Each wallet set backs the wallets you create inside it.
• You can create up to 1,000 wallet sets per account, with up to 10 million wallets in each set. For most use cases, one wallet set is enough.
• Multiple wallet sets are useful for scaling (for example, one set per tenant or product line), but they aren’t a security boundary. The same entity secret authorizes operations on every set.
• On EVM blockchains, wallets in the same set can share the same address across blockchains. See Unified wallet addressing on EVM blockchains for how to create and derive wallets that share an address.

​

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 itself is the credential. There is no separate password or passphrase protecting it.
• A recovery file covers every wallet backed by its entity secret, including wallets you create after the file was issued.
• A successful entity secret rotation or reset invalidates the current recovery file and issues a new one.

​

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.
• Overwrite your stored recovery file after any rotation or reset. Circle issues a new recovery file each time, and your old one becomes invalid.
• Group wallets into shared wallet sets, not one per user. Wallet sets are organizational boundaries for scaling (for example, one set per tenant or product line), not per-user containers. Creating one wallet set per user will exhaust the 1,000-set account limit. Group users into shared sets and identify each user with a refId on the wallet.