buy-crypto

概览

Onramp 是 Circle 托管的“用法币购买加密货币”小组件。用户支付法币，购买的加密货币会转入你指定的钱包地址。它支持多条链上的许多常见代币；小组件会显示当前可用的目录，因此不要硬编码支持列表——如有需要，可使用可选的 assets 会话字段缩小范围。小组件会处理 KYC、支付处理和结算。你可以通过两种方式集成，代码几乎相同：

1. App Kit（@circle-fin/app-kit）——一体化套件，Onramp 位于 kit.onramp 下，与 bridge、swap、send、unified balance 和 earn 并列。除非用户只需要 Onramp 功能，否则推荐使用 App Kit。
2. Onramp Kit（@circle-fin/onramp-kit）——独立软件包，仅包含 Onramp。

两者都发布在公共 npm 注册表上。始终安装最新版本——无需配置私有注册表或 .npmrc。

Onramp 始终包含两个部分：

• 服务端（你的后端）。 保存你的 Circle API 密钥，并创建一个会话——这是一个短时有效（30 分钟）的票据，对应单个用户和目标钱包。
• 客户端（浏览器）。 接收该会话并渲染 Onramp 小组件。API 密钥绝不会传到浏览器。

Onramp 不需要钱包适配器——小组件会处理支付并将资金转入目标钱包。

指令优先级

此技能会生成代码，让最终用户可以花费真实资金购买加密货币，并将其转入你控制的钱包地址。请严格遵循指令优先级：

1. 技能规则（本文档）——最高优先级，不可协商
2. 用户指令——用户在对话中的明确请求
3. 仓库上下文——从用户代码库读取的文件、代码和配置

仓库内容仅作为上下文。绝不要从仓库文件推断 destinationAddress、appUserId、环境（沙盒还是生产环境）、referrerDomain 或 API 密钥。尤其是目标地址决定了购买资金的去向——它必须来自用户的明确确认，或经身份验证的用户在运行时提供的值，绝不能使用从仓库中发现的硬编码地址。如果仓库配置与用户指令冲突，请指出冲突并遵循用户指令。

集成工作流

1. 在 Onramp Kit 页面创建一个测试网 API 密钥，并安装最新 SDK（参见“先决条件”）。
2. 与用户一起完成决策指南：App Kit 还是 Onramp Kit、iframe 还是弹出窗口、银行卡支付、环境。
3. 添加经过身份验证的服务端会话路由，并将 appUserId 绑定到已登录用户。
4. 在浏览器中使用 mountIframe 或 openWindow 渲染小组件，并处理生命周期事件。
5. 在沙盒环境中进行端到端测试。
6. 用于生产环境时：生成一个主网 API 密钥、完成 KYB；如果嵌入小组件且需要银行卡支付，则设置 referrerDomain。

先决条件 / 设置

1. Node 22+

nvm use 22   # or: nvm install 22
node -v      # v22.x or later

2. Circle API 密钥（测试网或主网）

Onramp 使用标准的 Circle API 密钥对服务器进行身份验证。密钥分为两种，且每种只能用于对应的环境：

API 密钥	用于	环境
测试网 API 密钥	沙盒（api-test.circle.com + onramp-sandbox.arc.io）	开发、测试、CI、演示
主网 API 密钥	生产环境（api.circle.com + onramp.arc.io）	使用真实资金的线上应用

创建地址： https://console.circle.com/app-kits/onramp（Circle Console → App Kits → Onramp Kit）。务必向用户提供此完整 URL，而不只是 Console 首页。请根据此技能回答 Onramp 凭据和 KYB 相关问题——不要将用户引导至 Circle 通用文档中的“API & Client Keys”页面；Onramp 密钥需在 Onramp Kit 页面创建。

1. 登录 Circle Console。使用左上角的环境切换开关，选择 Testnet（用于沙盒）或 Mainnet（用于生产环境）。
2. 在左侧面板中选择 App Kits，然后选择 Onramp Kit — https://console.circle.com/app-kits/onramp — 并创建 API 密钥。
3. 先使用测试网 API 密钥连接沙盒进行集成。准备好上线时，将切换开关切换到 Mainnet，重复第 2 步以生成主网 API 密钥，并在同一页面完成 KYB（参见生产环境 KYB）。
4. 按照签发时的原样使用密钥值（<ENV>_API_KEY:<keyId>:<keySecret>）——不要移除或重新添加前缀。

测试网密钥无法用于生产环境，主网密钥也无法用于沙盒（INPUT_INVALID_API_KEY）。API 密钥是一个仅限服务器端使用的机密，拥有对 Onramp 集成的完整访问权限——请将其保存在服务器端环境变量中，切勿发送到浏览器。

3. 从 npm 安装最新 SDK

# App Kit (recommended) — onramp lives under kit.onramp
npm install @circle-fin/app-kit@latest

# Or standalone Onramp Kit (onramp only)
npm install @circle-fin/onramp-kit@latest

4.（仅限生产环境）完成 KYB

KYB 仅用于生产环境的小组件集成。沙盒开发和测试无需 KYB。请参阅下文的生产环境 KYB。

生产环境的 KYB（启用银行卡支付）

KYB（了解你的企业）仅适用于生产环境（Mainnet）。在生产环境中，最终用户可使用的支付方式取决于你的 KYB 是否已获批准：

支付方式	未完成 KYB	KYB 已获批准
银行转账	是	是
借记卡、Apple Pay、Google Pay	否	是（嵌入时还需要 referrerDomain）
信用卡	否	否 — 不支持

用户实际看到的支付方式还取决于其所在地区以及所选代币／链；小组件会在运行时确定这些信息。

未完成 KYB，开发者仍可完成全部集成。 无需 KYB，即可在沙盒中构建和测试所有内容。在生产环境中，即使未完成 KYB，会话路由、小组件和生命周期事件也都能正常工作，入金流程也会提供银行转账。不要因 KYB 而阻塞集成工作——先搭建并测试，然后再为生产环境完成 KYB。

若要完成 KYB，并在生产环境中启用借记卡、Apple Pay 和 Google Pay：

1. 在 Circle Console 中，将左上角的环境切换开关切换到 Mainnet。
2. 在左侧面板中选择 App Kits，然后选择 Onramp Kit — https://console.circle.com/app-kits/onramp，这是创建 API 密钥时使用的同一页面。务必向用户提供此完整 URL。
3. 按照该页面上的 KYB 引导步骤操作。提交将嵌入小组件的网站域名——这些域名将成为你的 KYB web_url 条目。
4. 在同一页面跟踪状态。 提交后，KYB 状态会显示在 Onramp Kit 页面底部。
5. 为审核预留时间。 KYB 审核约需 48 小时。
6. 留意 Transak 发来的邮件。 Transak 是银行卡支付背后的支付提供商。虽然并不常见，但 Transak 可能会在审核期间通过邮件向你询问澄清问题——请留意这类邮件（包括垃圾邮件文件夹），并及时回复，否则审批可能会停滞。
7. 在服务端 kit 上设置 referrerDomain，以便银行卡支付在嵌入（iframe）模式下正常工作。请参见下文。

referrerDomain — 嵌入模式下银行卡支付的必需项

支付提供商的小组件会强制执行 frame-ancestors CSP，因此只有获准的父级站点才能嵌入该小组件。允许列表根据构造 服务端 kit 时传入的 referrerDomain 生成：

const server = createAppServerKit({
  onramp: {
    apiKey: process.env.CIRCLE_API_KEY!,
    referrerDomain: process.env.ONRAMP_REFERRER_DOMAIN, // e.g. "app.example.com"
  },
});

• 必须与 KYB 一致。 域名必须与 KYB 流程中提交的域名相同（即你的某个 KYB web_url 条目）。在生产环境中，如果域名未注册，借记卡、Apple Pay 和 Google Pay 将会失败并返回 403。
• 仅限纯主机名。 app.example.com 或 localhost——不带方案、端口、路径或通配符。对于子域名，请使用页面实际提供服务的主机名，而不是顶级域名。
• 仅限服务端配置。 从各环境的服务端配置中派生该值。绝不要从请求正文或浏览器提供的 Origin / Referer 标头中获取该值，否则攻击者就能扩大允许列表。这是 kit 的构造选项（而非会话参数），正是为了避免客户端影响此设置。
• 沙盒不会强制执行此设置，但仍应设置它，以便在升级到生产环境前验证配置是否正确。
• 仅当小组件嵌入你网站的 iframe 中时才需要；弹出窗口／顶层模式无需此设置（设置它也无妨）。

完整详情：允许你的页面嵌入小组件。

决策指南

编写代码前，请与用户逐项确认。

问题 1 — 使用哪个套件？

• 还会使用 bridge / swap / send / earn，或不确定 → App Kit（@circle-fin/app-kit，通过 kit.onramp 使用 onramp）。阅读 references/app-kit.md。
• 只使用 onramp，不使用其他任何功能 → Onramp Kit（@circle-fin/onramp-kit）。阅读 references/onramp-kit.md。

问题 2 — 内嵌小组件还是弹出窗口？

• 内嵌 iframe（mountIframe）——大多数应用的默认选择。小组件会在页面上的容器中呈现。可随时调用（无需点击）。容器必须已位于 DOM 中，且高度明确并且大于零。银行卡支付需要 referrerDomain。
• 弹出窗口（openWindow）——小组件会在单独的窗口中打开。如果页面没有足够空间容纳宽度为 720px 的内嵌小组件，或在 iOS Safari 中 iframe 内的 KYC 失败，请使用此方式。必须在点击处理程序内同步调用（不能在 await 之后调用），否则浏览器会拦截弹出窗口。请在点击前创建会话。

如果不确定，请先使用内嵌 iframe。

问题 3 — 是否需要银行卡 / Apple Pay / Google Pay？

• 是，且用于生产环境 → 将 Console 切换到 Mainnet，在 Onramp Kit 页面完成 KYB（约 48 小时；留意 Transak 发送的邮件；状态会显示在页面底部），并在服务端套件中将 referrerDomain 设置为 KYB 注册的域名。请参阅生产环境的 KYB。
• 暂时不需要 / 仍在沙盒环境 / 银行转账即可 → 现在即可集成，无需 KYB；在上线银行卡支付前完成 KYB 并设置 referrerDomain。

问题 4 — 使用哪个环境：沙盒还是生产环境？

• 沙盒（api-test.circle.com + onramp-sandbox.arc.io）——所有本地开发、测试、演示、CI 和 QA 均使用此环境。不会发生真实资金转移。生产环境小组件的 CSP 会拦截 localhost，因此本地开发必须使用沙盒环境。需要测试网 API 密钥。
• 生产环境（api.circle.com + onramp.arc.io；省略 URL 时的默认环境）——仅用于真实用户使用真实资金消费的线上应用。需要主网 API 密钥。
• 绝不可混用：api key、baseUrl 和 widgetBaseUrl 必须全部属于同一环境。完全通过环境变量控制环境选择——绝不要在源代码中硬编码生产环境 URL 或密钥。
• 在配置环境变量前，阅读 references/environments.md。

核心概念

• 服务端创建会话，客户端渲染。 服务端路由（createSessionRouteHandler）使用你的 API 密钥创建会话；浏览器通过 fetchSession 调用该路由，然后由 mountIframe/openWindow 渲染小组件。
• 会话正文。 { appUserId, destinationAddress, assets? }。destinationAddress 是接收加密货币的用户钱包。
• appUserId 是你的应用为用户分配的 ID，不是 Circle ID。 Circle 会将其映射到该用户的内部消费者记录，因此同一用户的每个会话都必须使用相同且稳定的值。请使用不透明的内部 ID（例如数据库中的用户 ID）。Circle 不会强制执行此要求，但请避免使用电子邮件、电话号码或其他个人身份信息。切勿生成随机值或每个会话各自不同的值，也绝不要代表一个用户发送另一个用户的 appUserId。
• 会话有效期为 30 分钟。 在 onSessionExpired 时重新创建会话（连续最多创建一次——此事件也会因 INVALID_SESSION_TOKEN 而触发，否则环境不匹配时会陷入循环）；如果预取的会话即将到达 expiresAt，也要创建一个新会话。
• 默认路由无需身份验证。 向 createSessionRouteHandler 添加 authorize 回调，拒绝未经身份验证的请求，并且拒绝 appUserId 与已登录用户不匹配的请求。在 Express / Fastify 中，应在服务端根据已验证身份的用户设置 appUserId，而不是从请求正文中获取。
• 环境由 URL 和相匹配的 API 密钥共同决定。 baseUrl（服务端、API）和 widgetBaseUrl（服务端和客户端，小组件来源）用于选择环境；省略它们时，目标环境为生产环境。沙盒 URL 必须搭配测试网 API 密钥，生产环境必须搭配主网 API 密钥。请参阅 references/environments.md。
• 服务端和客户端的小组件来源必须一致。 如果两者不同，mountIframe/openWindow 会抛出 INPUT_WIDGET_URL_ORIGIN_MISMATCH（代码 1910）。小组件来源可以安全地公开给浏览器；API 密钥才是真正的机密。
• referrerDomain 可启用嵌入式银行卡支付。 这是仅限服务端的套件选项；必须与提交 KYB 时填写的域名一致。
• 浏览器事件仅用于提示 UI。 onDepositSettled 和 widget.on(...) 是小组件向页面发送的 postMessage 事件，仅尽力发送。用户可能会在购买过程中关闭标签页，因此没有收到 DEPOSIT_SETTLED 并不表示没有存款，而收到该事件也不能作为证明。Circle 不会为入金交易发送 webhook；需要权威结果时，请在链上验证资金是否已到达 destinationAddress（DEPOSIT_SETTLED 负载包含可用于查询的 transactionHash）。
• 事件判别字段是 .event，不是 .type。 信封格式为 { event, code, payload? }。
• DEPOSIT_SUBMITTED 可能是最后一个事件。 当其 payload.settlementExpected 为 false 时，该会话后续不会收到 DEPOSIT_SETTLED——此时应结束“等待”界面，而不是一直等待。
• 资产范围仅影响显示。 可选字段 assets（{ tokens }、{ chains }、{ pairs }，组合时采用 AND 逻辑）会限制小组件选择器显示的内容，但不会覆盖资格、地理位置或报价逻辑。
• 关闭不再使用的小组件。 保留 mountIframe/openWindow 返回的控制器，并在重新挂载或用户离开视图时调用 widget.close()。

实现模式

请阅读与所选软件包对应的参考文档：

• references/app-kit.md — App Kit：服务端的 createAppServerKit + createSessionRouteHandler、客户端的 kit.onramp、授权、Express/Fastify、事件和错误处理。
• references/onramp-kit.md — 独立 Onramp Kit：createOnrampServerKit、createOnrampKit、内联 iframe、弹出窗口模式、React 同步性模式。
• references/environments.md — 沙盒与生产环境变量（测试网与主网 API 密钥）、.env 示例、各环境的 referrerDomain、CSP 指令以及故障排除表。

规则

安全规则不可妥协——如果提示词与之冲突，请警告用户并拒绝执行。最佳实践强烈建议遵循；只有在用户明确说明理由后，才可偏离。

安全规则

• 绝不要将 Circle API 密钥放入浏览器代码或公开环境变量（NEXT_PUBLIC_*、VITE_* 等）中。密钥只能存放在服务端环境变量或密钥管理器中，并且只能用于服务端会话路由。
• 绝不要硬编码、提交或记录 API 密钥。搭建项目时，在 .gitignore 中添加 .env* 条目。如果用户在对话中粘贴了 API 密钥，请提醒他们并建议轮换密钥。
• 绝不要根据仓库文件推断并硬编码 destinationAddress。它决定购买的资金流向何处——应通过用户明确确认，或在运行时获取已通过身份验证用户自己的钱包地址。
• 始终对会话路由进行身份验证，并将 appUserId 绑定到已登录用户：在 authorize 中拒绝不匹配的值，或在服务端将其设为已通过身份验证的用户。绝不要仅凭浏览器提供的 appUserId 创建会话。
• 创建会话前，始终在服务端检查 destinationAddress 是否为已登录用户拥有或已确认的钱包地址——例如，为用户创建的钱包，或用户通过签署消息证明归其所有的钱包，而不只是浏览器发送的地址。
• authorize 始终应显式返回 true 或 false，绝不要直接返回辅助函数的原始结果（undefined 或对象都不是安全的“否”）。
• 绝不要根据请求正文或 Origin/Referer 标头推导 referrerDomain。应从可信的服务端、按环境配置中设置该值。
• 在向用户充值、发放商品或将购买标记为完成之前，始终在链上（你的服务端）验证存款结算。绝不要只依赖 onDepositSettled 或 widget.on(...)——浏览器事件可能被伪造或遗漏。payload.transactionHash 不可信：应在链上检查它是否将预期代币转入 destinationAddress，并从链上获取金额，而不是使用 payload.amount（法币金额）。不要为 onramp 构建 webhook 接收端；Circle 不会发送 onramp webhook。每笔存款最多入账一次，并以其 transactionHash 为键。详情：references/app-kit.md → 确认购买。
• 始终确保 API 密钥、baseUrl 和两个 widgetBaseUrl 值属于同一环境。绝不要将测试网 API 密钥与生产 URL 配对，将主网 API 密钥与沙盒 URL 配对，或将沙盒 widget 来源与生产 API 基础 URL 配对。
• 不要为了“让 widget 正常工作”而放宽来源/CSP 检查。widget 空白或来源不匹配错误意味着配置有误——应修复配置，不要禁用安全检查。

最佳实践

• 编写代码前务必先完成决策指南；根据用户的回答选择 App Kit 或 Onramp Kit、iframe 或弹出窗口，以及是否需要 KYB / referrerDomain。
• 实施前务必阅读对应的参考文件。
• 从 npm 安装最新版本的 @circle-fin/app-kit 或 @circle-fin/onramp-kit。不要配置私有注册表。
• 先使用测试网 API 密钥连接沙盒；只有在部署到生产环境时才生成主网 API 密钥。
• 告知用户，KYB 仅用于生产环境：用户需要将 Console 切换到 Mainnet，并在 Onramp Kit 页面完成 KYB，状态会显示在页面底部。请尽早开始（审核约需 48 小时），并留意 Transak 发送的补充说明邮件。沙盒集成无需 KYB；与此同时，生产环境可使用银行转账。
• 嵌入小组件时，务必在服务端 kit 中设置 referrerDomain，使用提交 KYB 时填写的准确主机名。
• 为 iframe 容器指定明确的高度（例如 #onramp-root { height: 720px; }）——未设置高度时，iframe 会收缩至 0px。在 React 中，应从 useEffect 挂载，而不是在渲染期间挂载。
• 使用弹出窗口模式时，在用户点击前生成会话，并在点击处理程序中同步调用 openWindow；根据 result.status（opened 或 blocked）分支处理，并在 in_app_browser / pwa_standalone 环境下回退到 mountIframe。
• 在 onSessionExpired 中重新生成会话，最多重试一次；重新挂载前调用 widget.close()。
• 当宿主应用设置 CSP 时，针对目标环境，将小组件源站加入 frame-src，并将小组件和 API 源站加入 connect-src。
• 优先使用导出的 SDK 类型（例如 OnrampSession、KitError），而不是手写接口。

参考链接

• App Kit：Onramp · 快速入门：嵌入 Onramp 小组件
• 自定义会话生成（身份验证、Express/Fastify、assets、referrerDomain）
• 选择 iframe 或弹出窗口模式 · 处理生命周期事件
• 托管要求 · 错误处理
• 在线演示
• Circle Console — 创建 Onramp API 密钥 · API 密钥参考 · KYB：将 Console 切换到 Mainnet 后，在同一 Onramp Kit 页面完成
• Arc 文档索引 · Circle 开发者文档 — 查找源文档时，请先阅读这些内容。

替代方案

• 使用 swap-tokens 技能将一种代币兑换为另一种代币（不适用于法币 → 加密货币）。
• 使用 bridge-tokens 技能，在不同链之间转移 USDC 或其他受支持的代币。
• 使用 fund-agent-wallet 技能为 Circle Agent 钱包注资（基于 CLI 的法币入金、加密货币二维码、Gateway 存款），而不是在 Web 应用中嵌入托管式入金小组件。

---

免责声明：此技能按“原样”提供，不附带任何保证，并受 Circle 开发者条款约束。生成的内容可能包含错误和/或包含费用配置选项（包括支付给 Circle 的费用）；更多详情请参阅仓库的 README。