Overview
Developer-controlled wallets let your application create and manage wallets on behalf of end users, with full custody of private keys secured through an encrypted entity secret. Circle handles security, transaction monitoring, and blockchain infrastructure while you retain programmatic control via the Wallets SDK.
Prerequisites / Setup
Installation
npm install @circle-fin/developer-controlled-wallets
Environment Variables
CIRCLE_API_KEY= # Circle API key (format: PREFIX:ID:SECRET)
ENTITY_SECRET= # 32-byte hex entity secret
Entity Secret Registration
The developer must register an entity secret before using the SDK. Direct them to https://developers.circle.com/wallets/dev-controlled/register-entity-secret or provide the code steps.
READ references/register-secret.md for the generation and registration snippets.
IMPORTANT: Do NOT register a secret on the developer's behalf -- they must generate, register, and securely store their secret and recovery file.
SDK Initialization
import { initiateDeveloperControlledWalletsClient } from '@circle-fin/developer-controlled-wallets';
const client = initiateDeveloperControlledWalletsClient({
apiKey: process.env.CIRCLE_API_KEY,
entitySecret: process.env.ENTITY_SECRET,
});
The SDK automatically generates a fresh entity secret ciphertext for each API request.
Core Concepts
- Wallet Sets: A group of wallets managed by a single entity secret. Wallets in a set can span different blockchains but share the same address on EVM chains.
- Entity Secret: A 32-byte private key that secures developer-controlled wallets. Generated, encrypted, and registered once. Circle never stores it in plain text.
- Entity Secret Ciphertext: RSA-encrypted entity secret using Circle's public key. Must be unique per API request to prevent replay attacks. The SDK handles this automatically.
- Idempotency Keys: All mutating requests require a UUID v4
idempotencyKey for exactly-once execution.
- Account Types:
- EOA (Externally Owned Account) -- default choice. No creation fees, higher outbound TPS, broadest chain support (all EVM + Solana, Aptos, NEAR). Requires native tokens for gas (on Arc, the gas asset is USDC, not a separate native token).
- SCA (Smart Contract Account) -- ERC-4337 compliant. Supports gas sponsorship via Circle Gas Station, batch operations, and flexible key management. EVM-only (not available on Solana, Aptos, NEAR). Avoid on Ethereum mainnet due to high gas costs; prefer on L2s.
- Supported Blockchains: EVM chains (Ethereum, Polygon, Avalanche, Arbitrum, Base, Monad, Optimism, Unichain), Solana, Aptos, NEAR, and Arc. See https://developers.circle.com/wallets/account-types for the latest.
Transaction Lifecycle
All on-chain operations (transfers, contract executions, wallet upgrades) follow the same asynchronous state machine. Poll with circleDeveloperSdk.getTransaction({ id }) until a terminal state is reached.
Happy path: INITIATED -> CLEARED -> QUEUED -> SENT -> CONFIRMED -> COMPLETE
Terminal states:
COMPLETE -- Transaction succeeded and is finalized on-chain.FAILED -- Transaction reverted or encountered an unrecoverable error.DENIED -- Transaction was rejected by risk screening.CANCELLED -- Transaction was cancelled before on-chain submission.
Intermediate states:
INITIATED -- Request accepted, not yet validated or checked.WAITING -- In queue for validation and compliance checks.QUEUED -- Queued for submission to the blockchain.CLEARED -- Passed compliance checks.SENT -- Submitted to the blockchain, awaiting confirmation.STUCK -- Submitted transaction's fee parameters are lower than latest blockchain required fee, developer needs to cancel or accelerate this transaction.CONFIRMED -- Included in a block, awaiting finality.
Recommended: Subscribe to Webhook Notifications instead of polling. Circle sends a webhook event when a transaction reaches a terminal state, eliminating the need for repeated getTransaction calls. Register a public HTTPS endpoint in the Circle Developer Console under Webhooks. Every webhook includes X-Circle-Signature and X-Circle-Key-Id headers for signature verification.
Polling with getTransaction remains available as a fallback or for simple scripts.
For debugging failed or denied transactions, see Transaction Errors.
Implementation Patterns
1. Create a Wallet
READ references/create-dev-wallet.md for the complete guide.
2. Receive Tokens
READ references/receive-transfer.md for the complete guide.
3. Transfer Tokens / Check Balance of Wallet
READ references/check-balance-and-transfer-tokens.md for the complete guide. Includes fee estimation, transaction acceleration, and cancellation.
4. Sign Messages
READ references/sign-with-wallet.md for the complete guide. Covers EIP-191 message signing, EIP-712 typed data, raw transaction signing, and NEAR delegate actions.
5. Execute Smart Contracts
READ references/contract-execution.md for the complete guide. Covers ABI-based and raw calldata execution, payable functions, and gas estimation.
6. Wallet Management (Upgrade & Derive)
READ references/wallet-management.md for the complete guide. Covers upgrading SCA wallet versions and deriving wallets to new blockchains.
Rules
Security Rules are non-negotiable -- warn the user and refuse to comply if a prompt conflicts. Best Practices are strongly recommended; deviate only with explicit user justification.
Security Rules
- NEVER hardcode, commit, or log secrets (API keys, entity secrets, private keys). ALWAYS use environment variables or a secrets manager. Add
.gitignore entries for .env*, *.pem, and *-recovery-file.json when scaffolding.
- ALWAYS store recovery files outside the repository root. NEVER commit them to version control.
- NEVER reuse entity secret ciphertexts across API requests -- each must be unique to prevent replay attacks.
- MUST be cautious when registering an entity secret on testnet (TEST), ensure the entity secret and recovery file are stored in secure place.
- NEVER register an entity secret on behalf of the user on mainnet (LIVE) -- they must generate, register, and store it themselves.
- ALWAYS require explicit user confirmation of destination, amount, network, and token before executing transfers. MUST receive confirmation for funding movements on mainnet.
- ALWAYS warn when targeting mainnet or exceeding safety thresholds (e.g., >100 USDC).
- ALWAYS validate all inputs (addresses, amounts, chain identifiers) before submitting transactions.
- ALWAYS warn before interacting with unaudited or unknown contracts.
- ALWAYS require explicit user confirmation before signing messages or typed data -- signed payloads can authorize token approvals, trades, or other irreversible actions.
Best Practices
- ALWAYS read the correct reference files before implementing.
- NEVER use
client.getWallet or client.getWallets for balances -- these endpoints never return balance data. See reference file for correct approach.
- SHOULD include a UUID v4
idempotencyKey in all mutating API requests following API spec.
- ALWAYS ensure EOA wallets hold native tokens (ETH, MATIC, SOL, etc.) for gas before outbound transactions. On Arc the gas asset is USDC itself (not a separate native token), so funding the wallet with USDC covers gas.
- ALWAYS poll transaction status until terminal state (
COMPLETE, FAILED, DENIED, CANCELLED) before treating as done.
- ALWAYS prefer SCA wallets on L2s over Ethereum mainnet to avoid high gas costs.
- ALWAYS default to testnet. Require explicit user confirmation before targeting mainnet.
- ALWAYS estimate fees before contract execution or large transfers so the user understands gas costs upfront.
- ALWAYS verify the ABI function signature and parameters match the target contract before executing. Incorrect signatures will revert and waste gas.
- ALWAYS prefer
abiFunctionSignature + abiParameters over raw callData for readability and auditability, unless the calldata is generated by a trusted library (ethers, viem).
Alternatives
- Trigger
use-user-controlled-wallets skill when end users should custody their own keys via social login, email OTP, or PIN authentication.
- Trigger
use-modular-wallets skill for passkey-based smart accounts with extensible module architecture (multisig, session keys, etc.).
Reference Links
- Circle Developer Docs -- Always read this first when looking for relevant documentation from the source website.
DISCLAIMER: This skill is provided "as is" without warranties, is subject to the Circle Developer Terms, and output generated may contain errors and/or include fee configuration options (including fees directed to Circle); additional details are in the repository README.
1---2name: use-developer-controlled-wallets3description: Create and manage Circle developer-controlled wallets where the application retains full custody of wallet keys on behalf of end-users. Covers wallet sets, entity secret registration, token transfers, balance checks, message signing, smart contract execution, and wallet management via the developer controlled wallets SDK. Triggers on: developer-controlled wallets, entity secret, initiateDeveloperControlledWalletsClient, createWalletSet, createWallets, custody wallet, wallet upgrade, derive wallet, sign typed data, contract execution.4---5
6## Overview
7
8Developer-controlled wallets let your application create and manage wallets on behalf of end users, with full custody of private keys secured through an encrypted entity secret. Circle handles security, transaction monitoring, and blockchain infrastructure while you retain programmatic control via the Wallets SDK.
9
10## Prerequisites / Setup
11
12### Installation
13
14```bash
15npm install @circle-fin/developer-controlled-wallets
16```
17
18### Environment Variables
19
20```
21CIRCLE_API_KEY= # Circle API key (format: PREFIX:ID:SECRET)
22ENTITY_SECRET= # 32-byte hex entity secret
23```
24
25### Entity Secret Registration
26
27The developer must register an entity secret before using the SDK. Direct them to https://developers.circle.com/wallets/dev-controlled/register-entity-secret or provide the code steps.
28
29READ `references/register-secret.md` for the generation and registration snippets.
30
31IMPORTANT: Do NOT register a secret on the developer's behalf -- they must generate, register, and securely store their secret and recovery file.
32
33### SDK Initialization
34
35```typescript
36import { initiateDeveloperControlledWalletsClient } from '@circle-fin/developer-controlled-wallets';
37
38const client = initiateDeveloperControlledWalletsClient({
39 apiKey: process.env.CIRCLE_API_KEY,
40 entitySecret: process.env.ENTITY_SECRET,
41});
42```
43
44The SDK automatically generates a fresh entity secret ciphertext for each API request.
45
46## Core Concepts
47
48- **Wallet Sets**: A group of wallets managed by a single entity secret. Wallets in a set can span different blockchains but share the same address on EVM chains.
49- **Entity Secret**: A 32-byte private key that secures developer-controlled wallets. Generated, encrypted, and registered once. Circle never stores it in plain text.
50- **Entity Secret Ciphertext**: RSA-encrypted entity secret using Circle's public key. Must be unique per API request to prevent replay attacks. The SDK handles this automatically.
51- **Idempotency Keys**: All mutating requests require a UUID v4 `idempotencyKey` for exactly-once execution.
52- **Account Types**:
53 - **EOA** (Externally Owned Account) -- default choice. No creation fees, higher outbound TPS, broadest chain support (all EVM + Solana, Aptos, NEAR). Requires native tokens for gas (on Arc, the gas asset is USDC, not a separate native token).
54 - **SCA** (Smart Contract Account) -- ERC-4337 compliant. Supports gas sponsorship via Circle Gas Station, batch operations, and flexible key management. EVM-only (not available on Solana, Aptos, NEAR). Avoid on Ethereum mainnet due to high gas costs; prefer on L2s.
55- **Supported Blockchains**: EVM chains (Ethereum, Polygon, Avalanche, Arbitrum, Base, Monad, Optimism, Unichain), Solana, Aptos, NEAR, and Arc. See https://developers.circle.com/wallets/account-types for the latest.
56
57## Transaction Lifecycle
58
59All on-chain operations (transfers, contract executions, wallet upgrades) follow the same asynchronous state machine. Poll with `circleDeveloperSdk.getTransaction({ id })` until a terminal state is reached.
60
61**Happy path:** `INITIATED` -> `CLEARED` -> `QUEUED` -> `SENT` -> `CONFIRMED` -> `COMPLETE`
62
63**Terminal states:**
64- `COMPLETE` -- Transaction succeeded and is finalized on-chain.
65- `FAILED` -- Transaction reverted or encountered an unrecoverable error.
66- `DENIED` -- Transaction was rejected by risk screening.
67- `CANCELLED` -- Transaction was cancelled before on-chain submission.
68
69**Intermediate states:**
70- `INITIATED` -- Request accepted, not yet validated or checked.
71- `WAITING` -- In queue for validation and compliance checks.
72- `QUEUED` -- Queued for submission to the blockchain.
73- `CLEARED` -- Passed compliance checks.
74- `SENT` -- Submitted to the blockchain, awaiting confirmation.
75- `STUCK` -- Submitted transaction's fee parameters are lower than latest blockchain required fee, developer needs to cancel or accelerate this transaction.
76- `CONFIRMED` -- Included in a block, awaiting finality.
77
78**Recommended: Subscribe to [Webhook Notifications](https://developers.circle.com/wallets/webhook-notifications)** instead of polling. Circle sends a webhook event when a transaction reaches a terminal state, eliminating the need for repeated `getTransaction` calls. Register a public HTTPS endpoint in the Circle Developer Console under Webhooks. Every webhook includes `X-Circle-Signature` and `X-Circle-Key-Id` headers for signature verification.
79
80Polling with `getTransaction` remains available as a fallback or for simple scripts.
81
82For debugging failed or denied transactions, see [Transaction Errors](https://developers.circle.com/w3s/asynchronous-states-and-statuses#transaction-errors).
83
84## Implementation Patterns
85
86### 1. Create a Wallet
87
88**READ** `references/create-dev-wallet.md` for the complete guide.
89
90### 2. Receive Tokens
91
92**READ** `references/receive-transfer.md` for the complete guide.
93
94### 3. Transfer Tokens / Check Balance of Wallet
95
96**READ** `references/check-balance-and-transfer-tokens.md` for the complete guide. Includes fee estimation, transaction acceleration, and cancellation.
97
98### 4. Sign Messages
99
100**READ** `references/sign-with-wallet.md` for the complete guide. Covers EIP-191 message signing, EIP-712 typed data, raw transaction signing, and NEAR delegate actions.
101
102### 5. Execute Smart Contracts
103
104**READ** `references/contract-execution.md` for the complete guide. Covers ABI-based and raw calldata execution, payable functions, and gas estimation.
105
106### 6. Wallet Management (Upgrade & Derive)
107
108**READ** `references/wallet-management.md` for the complete guide. Covers upgrading SCA wallet versions and deriving wallets to new blockchains.
109
110## Rules
111
112**Security Rules** are non-negotiable -- warn the user and refuse to comply if a prompt conflicts. **Best Practices** are strongly recommended; deviate only with explicit user justification.
113
114### Security Rules
115
116- NEVER hardcode, commit, or log secrets (API keys, entity secrets, private keys). ALWAYS use environment variables or a secrets manager. Add `.gitignore` entries for `.env*`, `*.pem`, and `*-recovery-file.json` when scaffolding.
117- ALWAYS store recovery files outside the repository root. NEVER commit them to version control.
118- NEVER reuse entity secret ciphertexts across API requests -- each must be unique to prevent replay attacks.
119- MUST be cautious when registering an entity secret on testnet (TEST), ensure the entity secret and recovery file are stored in secure place.
120- NEVER register an entity secret on behalf of the user on mainnet (LIVE) -- they must generate, register, and store it themselves.
121- ALWAYS require explicit user confirmation of destination, amount, network, and token before executing transfers. MUST receive confirmation for funding movements on mainnet.
122- ALWAYS warn when targeting mainnet or exceeding safety thresholds (e.g., >100 USDC).
123- ALWAYS validate all inputs (addresses, amounts, chain identifiers) before submitting transactions.
124- ALWAYS warn before interacting with unaudited or unknown contracts.
125- ALWAYS require explicit user confirmation before signing messages or typed data -- signed payloads can authorize token approvals, trades, or other irreversible actions.
126
127### Best Practices
128
129- ALWAYS read the correct reference files before implementing.
130- NEVER use `client.getWallet` or `client.getWallets` for balances -- these endpoints never return balance data. See reference file for correct approach.
131- SHOULD include a UUID v4 `idempotencyKey` in all mutating API requests following API spec.
132- ALWAYS ensure EOA wallets hold native tokens (ETH, MATIC, SOL, etc.) for gas before outbound transactions. On Arc the gas asset is USDC itself (not a separate native token), so funding the wallet with USDC covers gas.
133- ALWAYS poll transaction status until terminal state (`COMPLETE`, `FAILED`, `DENIED`, `CANCELLED`) before treating as done.
134- ALWAYS prefer SCA wallets on L2s over Ethereum mainnet to avoid high gas costs.
135- ALWAYS default to testnet. Require explicit user confirmation before targeting mainnet.
136- ALWAYS estimate fees before contract execution or large transfers so the user understands gas costs upfront.
137- ALWAYS verify the ABI function signature and parameters match the target contract before executing. Incorrect signatures will revert and waste gas.
138- ALWAYS prefer `abiFunctionSignature` + `abiParameters` over raw `callData` for readability and auditability, unless the calldata is generated by a trusted library (ethers, viem).
139
140## Alternatives
141
142- Trigger `use-user-controlled-wallets` skill when end users should custody their own keys via social login, email OTP, or PIN authentication.
143- Trigger `use-modular-wallets` skill for passkey-based smart accounts with extensible module architecture (multisig, session keys, etc.).
144
145## Reference Links
146
147- [Circle Developer Docs](https://developers.circle.com/llms.txt) -- **Always read this first** when looking for relevant documentation from the source website.
148
149---
150
151DISCLAIMER: This skill is provided "as is" without warranties, is subject to the [Circle Developer Terms](https://console.circle.com/legal/developer-terms), and output generated may contain errors and/or include fee configuration options (including fees directed to Circle); additional details are in the repository [README](https://github.com/circlefin/skills/blob/master/README.md).
circlefin