01
安装并创建一笔存款
- 1安装该包：bun add @usdctofiat/offramp（npm 和 pnpm 同样适用）。
- 2传入一个 viem WalletClient：用户钱包、服务器钱包或机器人钱包均可。
- 3调用 offramp(walletClient, { amount, platform, currency, identifier })。
- 4读取返回的 depositId 和 txHash，或用 npx create-offramp-app@latest 搭建一个项目。
02
SDK 接口
| 导出项 | 作用 |
|---|---|
| offramp(walletClient, params) | 一次调用完成卖出 USDC 流程，返回 { depositId, txHash, resumed, otcLink? } |
| deposits(address) | 无需索引协议状态即可列出某地址的存款 |
| close(walletClient, depositId) | 从现有存款中提取未成交的 USDC |
| enableOtc / disableOtc / getOtcLink | 管理存款上的私有单一买方限制 |
| useOfframp() / usePeerExtensionRegistration() | 来自 @usdctofiat/offramp/react 的 React Hooks |
| PLATFORMS, CURRENCIES | 带类型的常量映射，含标识符、校验和货币列表 |
03
天然可续传
创建一笔存款会跨越若干链上步骤。如果上一次调用留下了一笔半途中的存款，再次调用 offramp() 会从中断处继续，而不是创建一笔重复存款。当采用了一笔已存在但尚未委托的存款（而非新建）时，结果中的 resumed 标志为 true。
这让 SDK 可以安全地从服务器或机器人重试：它是一个对幂等友好的入口，会与链上状态对账，而不是假定一切从零开始。
04
错误处理
| 关注点 | SDK 如何提示 |
|---|---|
| 带类型的错误 | OfframpError 携带一个来自 OFFRAMP_ERROR_CODES 的 code |
| PayPal 或 Wise 设置 | 当账号句柄尚未注册时返回 EXTENSION_REGISTRATION_REQUIRED |
| 校验 | PLATFORMS 和 CURRENCIES 提供标识符与货币校验 |
| 不托管私钥 | SDK 用你的 WalletClient 签名，从不存储私钥 |
Keep exploring
Common questions
@usdctofiat/offramp 免费吗？
是的。该 SDK 可免费安装和集成，创建存款无需 API 密钥，因为由你的钱包签名。Peerlytics 分析、API 额度和签名 Webhook 管理可通过 Peerlytics 另行提供。
该 SDK 会托管私钥或转移法币吗？
两者都不会。它用你提供的 viem WalletClient 签名，从不持有私钥。法币在所选支付应用中直接在买卖双方之间流转；SDK 只处理链上 USDC 与存款生命周期。
我如何测试一个集成？
没有公开的沙盒环境；该 SDK 面向 Base 主网，因此一笔测试存款是真实的，并可在公开订单簿上被发现。请使用 1 USDC 的最低额度，并要么将其限定为 OTC 存款（传入 otcTaker，使只有你的钱包能成交），要么尽快 close() 它。通过链上和 deposits() 确认。