xrpl-payments

XRPL 支付

XRP Ledger 专为快速、可靠的价值转移而打造。让它适用于机构支付的特性，同样也让它非常适合 AI Agent：3–5 秒即可确定性最终确认、费用可预测，且没有含糊不清的待处理状态——交易要么确认（tesSUCCESS），要么过期。无需重试循环。

XRPL Payments 技能是 XRP Ledger 上支付操作的领域知识层。它为 Claude 提供准确、最新的 XRPL 支付模式知识，使其能够为任何支付任务构造合适的交易对象，包括 XRP 转账、RLUSD、跨币种支付、托管等。

该技能会为任何支付任务构造合适的交易对象，包括 XRP 转账、RLUSD、跨币种支付、托管等，然后将该对象交给 XRPL Agent Wallet 技能进行签名和提交。完整的 Agent 支付工作流需要这两项技能。

此技能涵盖的内容

领域	所掌握的知识
账户注资	水龙头注资、余额检查、储备金要求
XRP 支付	直接支付、目标标签、部分支付
RLUSD 支付	信任线设置、RLUSD 发送、Testnet 和 Mainnet 的发行方地址
IOU 代币支付	通用信任线代币转账
跨币种支付	通过内置 DEX 在单笔交易中完成币种兑换
托管	基于时间和条件的托管创建、完成和取消
Agent 最佳实践	使用 SourceTag 标记 Agent 归属，使用 Memos 创建链上审计记录，通过 WebSocket 进行监控
错误处理	交易结果代码（tec*、tef*、tem*、ter*）、储备金要求、提交前模拟
安全性	密钥管理模式、支出控制、储备金注意事项

---

适用对象

技能	作用
XRPL Agent Wallet	必需——负责创建钱包、加载密钥，并为此技能构造的每笔交易签名和提交

Payments 技能是不断扩展的 XRPL 领域技能集合之一。所有领域 技能都与同一个共享 Wallet 技能配合使用。完整列表请参阅 AI 工具。

需要先创建钱包？ 如果用户还没有 XRPL 钱包，请加载 XRPL Agent Wallet 技能——它负责生成钱包，将种子安全地写入 .env，且绝不会在聊天中显示。钱包准备就绪后，请返回此处。

默认行为与技术栈决策

• 语言： Python（xrpl-py）和 TypeScript/JavaScript（xrpl.js）都是一等选择。使用开发者项目已有的语言；如果没有现有代码库，请先询问。参考资料中的代码示例涵盖这两种语言。
• 交易提交： 完全由 XRPL Agent Wallet 技能处理。此技能负责构建交易对象，不会直接调用 submit_and_wait 或 submitAndWait。
• 金额处理： 始终使用 xrpl.utils 中的 xrp_to_drops() / drops_to_xrp()。绝不要向账本传入原始 XRP 浮点数。
• 网络： 默认使用测试网（https://s.altnet.rippletest.net:51234）。切换到主网只需更改一行 URL。
• Agent 标记： SourceTag 可用于链上交易量跟踪，并将 Agent 发起的活动与人工发起的交易区分开来。不要在支付构建代码中设置它。 XRPL Agent Wallet 技能会在签名流程中，为任何未设置 SourceTag 的交易应用 SourceTag = 20260530 — 这样可确保所有领域技能的标记保持一致。只有在需要使用自定义标记时才显式设置，或设置为 0 以选择退出；Wallet 技能会保留已有的值。请注意，仅按 20260530 过滤无法涵盖 x402 支付，因为这类支付使用商家声明的标记。
• 提交前先模拟： 对于新的支付流程，该技能会在将原始交易对象交给 Wallet 技能之前调用 simulate。这可以发现格式错误的交易、缺失的信任线和储备金错误，且不会花费手续费或触发签名流程。

操作流程

1. 识别支付类型 — XRP、RLUSD、IOU 或跨货币支付。查看 payments.md。
2. 检查前提条件 — 是否已设置信任线？目标账户是否有储备金？余额是否足以支付手续费？
3. 构建 — 构造交易对象。在每笔 Agent 发起的交易上设置 Memos。不要设置 Fee、Sequence 或 LastLedgerSequence — Wallet 技能的自动填充步骤会从实时节点获取并填入这些值。
4. 模拟 — 在移交前，对原始（尚未自动填充）交易调用 simulate。这可以发现格式错误的交易、缺失的信任线和储备金错误，且不会操作账本或触发签名流程。请参阅 payments.md 中的模拟模式。
5. 移交给 Wallet 技能 — 将交易对象传递给 XRPL Agent Wallet 技能。该技能会自动填充字段、向用户展示预览、获取确认、在本地签名，并通过 submitAndWait 提交。不要在此技能中调用 submit_and_wait 或 submitAndWait。
6. 明确处理错误 — tec* 代码表示已收取手续费。tef* / tem* 表示未收取手续费。请参阅 payments.md 中的错误表格。

此技能不会执行的操作

• 创建钱包或处理密钥。 钱包生成、种子存储、密钥加载和所有密钥管理都由 XRPL Agent Wallet 技能负责。
• 签名或提交交易。 这是 Wallet 技能的职责。
• 主动构建非支付类交易。 此技能会响应开发者和用户的指令；不会在无人提示时主动提出交易。
• 保证主网 RLUSD 发行方地址始终有效。 测试网发行方（rQhWct2fv4Vc4KRjRgMrxa8xPN9Zx9iLKV）已确认。生产环境使用前，应通过 RLUSD 官方文档核实主网发行方（rMxCKbEDwqr76QuheSUMdEGf4B9xJ8m5De）。

参考文件

需要完整的交易模式和边缘情况时，请阅读以下文件：

• payments.md — XRP、RLUSD、IOU、跨货币支付、托管、支付通道、Agent 模式、错误代码、储备金