use-developer-controlled-wallets

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

开发者控制钱包允许你的应用代表终端用户创建和管理钱包，通过加密的实体密钥安全保管私钥。Circle负责处理安全、交易监控和区块链基础设施，而你可通过Wallets SDK保留程序化控制权。

Prerequisites / Setup

前提条件/设置

Installation

安装

bash

npm install @circle-fin/developer-controlled-wallets

bash

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

CIRCLE_API_KEY=      # Circle API密钥（格式：PREFIX:ID:SECRET）
ENTITY_SECRET=       # 32字节十六进制实体密钥

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前必须注册实体密钥。请引导用户访问https://developers.circle.com/wallets/dev-controlled/register-entity-secret 或提供代码步骤。

阅读

references/register-secret.md

获取密钥生成和注册的代码片段。

重要提示：切勿代表开发者注册密钥——他们必须自行生成、注册并安全存储密钥和恢复文件。

SDK Initialization

SDK初始化

typescript

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.

typescript

import { initiateDeveloperControlledWalletsClient } from '@circle-fin/developer-controlled-wallets';

const client = initiateDeveloperControlledWalletsClient({
  apiKey: process.env.CIRCLE_API_KEY,
  entitySecret: process.env.ENTITY_SECRET,
});

SDK会自动为每个API请求生成新的实体密钥密文。

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.
- 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 States:

INITIATED

PENDING_RISK_SCREENING

SENT

CONFIRMED

COMPLETE

. Failure states:

FAILED

DENIED

CANCELLED

钱包组（Wallet Sets）：由单个实体密钥管理的一组钱包。同一组内的钱包可跨不同区块链，但在EVM链上共享同一地址。
实体密钥（Entity Secret）：用于保护开发者控制钱包的32字节私钥。只需生成、加密并注册一次，Circle绝不会以明文形式存储它。
实体密钥密文（Entity Secret Ciphertext）：使用Circle公钥对实体密钥进行RSA加密后的内容。每个API请求必须使用唯一的密文，以防止重放攻击。SDK会自动处理此操作。
幂等键（Idempotency Keys）：所有变更类请求都需要UUID v4格式的
```
idempotencyKey
```
，以确保请求仅执行一次。
账户类型：
- EOA（外部拥有账户）：默认选择。无创建费用，对外交易吞吐量更高，支持的链最广泛（所有EVM链 + Solana、Aptos、NEAR）。需要原生代币支付Gas费。
- SCA（智能合约账户）：符合ERC-4337标准。支持通过Circle Gas Station赞助Gas费、批量操作以及灵活的密钥管理。仅支持EVM链（不支持Solana、Aptos、NEAR）。避免在以太坊主网使用，因Gas成本过高；建议在Layer2网络使用。
支持的区块链：EVM链（以太坊、Polygon、Avalanche、Arbitrum、Base、Monad、Optimism、Unichain）、Solana、Aptos、NEAR以及Arc。最新支持列表请查看https://developers.circle.com/wallets/account-types。
交易状态：
```
INITIATED
```
（已发起）→
```
PENDING_RISK_SCREENING
```
（风险筛查中）→
```
SENT
```
（已发送）→
```
CONFIRMED
```
（已确认）→
```
COMPLETE
```
（已完成）。失败状态包括：
```
FAILED
```
（失败）、
```
DENIED
```
（被拒绝）、
```
CANCELLED
```
（已取消）。

Implementation Patterns

实现模式

1. Create a Wallet

1. 创建钱包

READ

references/create-dev-wallet.md

for the complete guide.

阅读

references/create-dev-wallet.md

获取完整指南。

2. Receive Tokens

2. 接收代币

READ

references/receive-transfer.md

for the complete guide.

阅读

references/receive-transfer.md

获取完整指南。

3. Transfer Tokens / Check Balance of Wallet

3. 代币转账 / 查询钱包余额

READ

references/check-balance-and-transfer-tokens.md

for the complete guide.

阅读

references/check-balance-and-transfer-tokens.md

获取完整指南。

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.
NEVER register an entity secret on behalf of the user -- they must generate, register, and store it themselves.
ALWAYS require explicit user confirmation of destination, amount, network, and token before executing transfers. NEVER auto-execute fund 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.

切勿硬编码、提交或记录密钥（API密钥、实体密钥、私钥）。务必使用环境变量或密钥管理器。在搭建项目时，将
```
.env*
```
、
```
*.pem
```
和
```
*-recovery-file.json
```
添加到
```
.gitignore
```
中。
务必将恢复文件存储在仓库根目录之外。切勿将其提交到版本控制系统。
切勿在多个API请求中重复使用实体密钥密文——每个请求必须使用唯一密文以防止重放攻击。
切勿代表用户注册实体密钥——他们必须自行生成、注册并存储密钥。
在执行转账前，务必获取用户对目标地址、金额、网络和代币的明确确认。切勿在主网自动执行资金划转。
当目标为以太坊主网或超出安全阈值（如>100 USDC）时，务必发出警告。
在提交交易前，务必验证所有输入（地址、金额、链标识符）。
在与未审计或未知合约交互前，务必发出警告。

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.
ALWAYS include a UUID v4
```
idempotencyKey
```
in all mutating API requests.
ALWAYS ensure EOA wallets hold native tokens (ETH, MATIC, SOL, etc.) for gas before outbound transactions.
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.

在实现前务必阅读正确的参考文档。
切勿使用
```
client.getWallet
```
或
```
client.getWallets
```
查询余额——这些端点不会返回余额数据。请查看参考文档获取正确方法。
在所有变更类API请求中务必包含UUID v4格式的
```
idempotencyKey
```
。
在发起对外交易前，务必确保EOA钱包持有足够的原生代币（ETH、MATIC、SOL等）用于支付Gas费。
务必轮询交易状态直至进入最终状态（
```
COMPLETE
```
、
```
FAILED
```
、
```
DENIED
```
、
```
CANCELLED
```
），才可视为交易完成。
相比以太坊主网，务必优先在Layer2网络使用SCA钱包以避免高额Gas成本。
务必默认使用测试网。在切换到主网前，需获取用户的明确确认。

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.).

当终端用户需要通过社交登录、邮箱OTP或PIN认证自行保管密钥时，触发
```
use-user-controlled-wallets
```
技能。
如需基于Passkey的智能账户并具备可扩展的模块架构（多签、会话密钥等），触发
```
use-modular-wallets
```
技能。

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.

Circle开发者文档 —— 查找官方相关文档时，请首先阅读此链接。

免责声明：本技能按“现状”提供，不提供任何担保，受Circle开发者条款约束，生成的输出可能包含错误和/或费用配置选项（包括支付给Circle的费用）；更多详情请查看仓库README。