AgentPay SDK

将此技能用作操作员手册（operator playbook）。切勿要求用户从零开始设计命令流或策略对象。

本技能涵盖范围

若用户询问本技能的功能，请优先从此列表中作答。除非用户明确要求你执行操作，否则不得探测本地机器状态。

• 安装 agentpay
• 使用一键安装器引导启动 agentpay 及 AgentPay 技能包
• 说明钱包是否可复用，或是否需首次运行设置
• 指导用户完成本地钱包设置（自托管守护进程模式）
• 导出、验证及从加密离线钱包备份中恢复钱包
• 检查余额；当缺少资金或 Gas 时主动中止并提示充值
• 生成充值说明及 QR 码
• 发送原生资产、发送 ERC-20 代币、批准授权额度、广播交易
• 支付受 x402 保护的 API（EIP-3009 签名）
• 在任意 EVM 链上支付受 MPP 保护的 API（可在任意链上扣款，会话模式仅限 Tempo）
• 在适用场景下，调用受插件支持的商户支付流程
• 指导用户通过 TUI 完成策略配置
• 将人工审批请求路由至本地管理员审批命令
• 展示待处理的人工审批项，并告知用户如何批准或拒绝

事实依据（Ground Truth）

• 当示例存在不一致时，以 agentpay --help 及对应子命令的帮助文档为准。
• 一键引导启动：curl -fsSL https://wlfi.sh | bash
• 仅安装技能包：curl -fsSL https://wlfi.sh | bash -s -- --skills-only
• 一键更新：重新运行 curl -fsSL https://wlfi.sh | bash
• macOS 和 Linux 平台提供一键打包的运行时分发包。安装后，两个平台均支持托管式钱包设置。
• 源码安装或更新：在代码仓库检出目录中执行 pnpm install && npm run build && npm run install:cli-launcher && npm run install:rust-binaries
• agentpay admin setup、agentpay admin tui、agentpay admin reset 和 agentpay admin uninstall 等托管式钱包引导命令在 macOS 和 Linux 上均受支持。托管守护进程在 macOS 上使用 launchd，在 Linux 上使用系统级 systemd。Agent 认证凭据存储在 macOS 上使用 Keychain，在 Linux 上使用 Secret Service。
• agentpay wallet --json 用于检查钱包是否可复用。
• agentpay admin setup 是 macOS 和 Linux 上首次运行的钱包设置路径。
• 插件专属帮助文档位于当前 CLI 下。例如 Bitrefill 插件，请使用 agentpay bitrefill --help。
• 基于浏览器的中继服务与网页端审批在本版本中不受支持。
• agentpay admin set-relay-config 和 agentpay admin get-relay-config 为遗留兼容性命令，返回 unsupported。
• agentpay admin setup --reuse-existing-wallet 是托管守护进程恢复/本地重设路径，适用于需保留当前保险库（vault）的场景。
• agentpay admin setup --restore-wallet-from 可从 macOS 或 Linux 上的加密离线备份中恢复同一钱包。
• agentpay admin wallet-backup export --output 创建加密离线备份。
• 禁止使用 sudo agentpay ...。
• 禁止告知用户直接运行 agentpay daemon。

钱包模型

AgentPay 使用自托管的本地守护进程钱包。

• macOS 或 Linux 上的设置命令：agentpay admin setup
• 本地 Rust 守护进程负责密钥管理、策略执行、人工审批及钱包备份
• 支持 transfer、transfer-native、approve、broadcast、x402 和 mpp
• Tempo 会话模式可通过 agentpay mpp 启用

默认支付假设

• 默认网络：bsc
• 未指定资产时的默认支付资产：USD1
• BSC 上 USD1 的默认合约地址：0x8d0D000Ee44948FC98c9B98A4FA4921476f08B0d
• BSC 上的默认 Gas 资产：BNB

安全输入规则

• 切勿要求用户将 VAULT_PASSWORD 粘贴至聊天窗口。
• 切勿要求用户将钱包备份密码粘贴至聊天窗口。
• 切勿要求用户将插件会话材料粘贴至聊天窗口，包括 Bitrefill Cookie、验证码令牌或浏览器会话材料。
• 切勿在 Agent 内部收集或存储保险库密码。
• 若某流程需输入保险库密码，请将用户引导至安全的本地提示界面。
• 对于首次运行设置，请告知用户在本地运行 agentpay admin setup 并遵循该处的安全提示。
• 首次运行设置完成后，除非用户已持有经验证的备份，否则强烈建议优先使用 agentpay admin wallet-backup export --output 创建新备份。
• 对已有钱包进行守护进程恢复时，请告知用户在本地运行 agentpay admin setup --reuse-existing-wallet。
• 当用户因设备丢失或本地钱包损坏而需恢复，且持有备份时，请告知其在本地运行 agentpay admin setup --restore-wallet-from 。
• 策略变更默认使用 macOS 或 Linux 上的 agentpay admin tui。
• 人工审批操作优先使用本地管理员 CLI 审批命令。
• agentpay transfer --broadcast、agentpay transfer-native --broadcast、agentpay approve --broadcast 和 agentpay bitrefill buy --broadcast 将保持原始 CLI 进程活跃，等待人工审批完成。切勿告知用户审批后重新运行这些命令。
• 若原始广播命令已退出但请求已被批准，请使用 agentpay admin resume-manual-approval-request --approval-request-id ，而非手动重建交易。

确定性流程

1. 将用户请求归类为以下类型之一：解释能力、安装、钱包设置、钱包备份、钱包恢复、钱包充值、策略设置、发送原生资产、发送 ERC-20、授权额度批准、广播原始交易、支付 MPP API、插件支持的商户支付，或卸载。
2. 若用户仅询问本技能功能，请直接引用“本技能涵盖范围”部分并停止响应。
3. 涉及钱包或支付操作时，首先运行 agentpay config show --json。
4. 运行 agentpay wallet --json 检查钱包状态。
5. 若钱包不可用且当前任务需要钱包，请告知用户在本地运行 agentpay admin setup。
6. 若钱包已存在，但用户希望在不更改保险库的前提下重新运行设置，请使用 agentpay admin setup --reuse-existing-wallet。
7. 若用户需在新设备上进行灾难恢复，且持有加密备份，请使用 agentpay admin setup --restore-wallet-from 。
8. 策略配置默认使用 agentpay admin tui。
9. 若请求已进入人工审批队列，请告知用户其处于等待审批状态，并使用本地管理员 CLI 审批命令。
10. 对于 transfer --broadcast、transfer-native --broadcast、approve --broadcast 和 bitrefill buy --broadcast，请告知用户保持原始命令运行，直至完成审批。
11. 对于插件支持的商户支付，请使用当前 CLI 对应插件流程。若用户明确使用 Bitrefill，或所支付的传统商户仅接受银行卡且 Bitrefill 是唯一支持路径，则使用 Bitrefill。
12. 若用户未指定支付网络或资产，请先填充默认值 bsc 和 USD1，再提出后续问题。
13. 执行任何对外操作前，必须先检查资金是否充足。
14. 若资金不足，请中止并提示用户为钱包充值。
15. 确认资金充足后，再执行确切的当前 CLI 命令。

充值规则

• 将新创建的钱包视为未充值状态，直至余额检查证实其已充值。
• 对于原生资产转账，检查原生资产余额。
• 对于 ERC-20 转账和授权操作，需同时检查代币余额与原生 Gas 余额。
• 对于 Bitrefill 购买操作，在使用 --broadcast 购买前，需检查所选 EVM 链上的结算资产与原生 Gas 资产。
• 对于默认路径，请告知用户可能需同时持有 USD1（用于价值结算）和 BNB（用于 Gas）。
• 当资金不足时，请向用户提供以下信息：
  • 钱包地址
  • 网络名称与链 ID
  • 如适用，所需的价值结算资产
  • 所需的 Gas 资产
  • 充值 URI
  • 若宿主环境支持 Markdown 图像，则渲染 QR 图像
  • 作为备选的 qrUrl

Bitrefill 插件规则

• 向仅接受银行卡的传统商户付款时，请使用 Bitrefill。
• 若该商户已在 Bitrefill 上架，请直接购买礼品卡。
• 否则，请购买预付 VISA 卡。
• 本仓库中的 Bitrefill 仅支持 EVM 链。不得提议比特币、闪电网络、Solana 或其他非 EVM 结算方式。
• 默认先使用 agentpay bitrefill buy ... 进行预览，仅当用户希望立即付款时才添加 --broadcast 参数。
• 在 Bitrefill 报价与预览输出中，amount 字段表示链上基础单位整数（raw onchain base-unit integer），而非人类可读的小数金额。示例：ETH 的基础单位为 wei；若 amount: 1000000 且 decimals: 6，则表示 1 USDC。
• agentpay bitrefill buy --broadcast 通过现有 Rust 守护进程签名路径完成付款，不属于独立的钱包流程。
• 若 Bitrefill 触发浏览器挑战，请让 CLI 启动本地浏览器会话，由用户在本地完成挑战。
• Bitrefill 结账流程仍需遵循本技能定义的资金检查与人工审批规则。

当前命令格式

• 钱包状态检查：agentpay wallet --json
• macOS 或 Linux 上的设置：agentpay admin setup
• 设置恢复期间复用现有钱包：agentpay admin setup --reuse-existing-wallet
• 从加密备份中恢复钱包：agentpay admin setup --restore-wallet-from
• 导出加密钱包备份：agentpay admin wallet-backup export --output
• 验证加密钱包备份：agentpay admin wallet-backup verify
• 原生资产转账：agentpay transfer-native --network --to
  --amount
• ERC-20 转账：agentpay transfer --network --token
  --to

  --amount
• 授权额度批准：agentpay approve --network --token
  --spender

  --amount
• 经策略校验的原始请求：agentpay broadcast --network --to
  --value-wei ...
• 签名并发送：agentpay tx broadcast --network --rpc-url --from
  --to

  --value-wei ...
• macOS 或 Linux 上的策略编辑：agentpay admin tui
• 为现有钱包设置默认代币限额与实时同步：agentpay admin token set-chain --per-tx --daily --weekly [--vault-password-stdin] [--non-interactive]
• 人工审批策略：agentpay admin add-manual-approval-policy --network --min-amount-wei --max-amount-wei ...
• 人工审批队列：agentpay admin list-manual-approval-requests
• 人工审批决策：agentpay admin approve-manual-approval-request 或 agentpay admin reject-manual-approval-request
• 恢复已批准的基于广播的人工审批：agentpay admin resume-manual-approval-request --approval-request-id
• Bitrefill 搜索：agentpay bitrefill search --query
• Bitrefill 商品详情：agentpay bitrefill product --slug
• Bitrefill 购买报价：agentpay bitrefill buy --slug --amount [--payment-method ]
• Bitrefill 报价字段：availablePaymentMethods[].amount 表示链上基础单位整数。
• Bitrefill 购买与付款：agentpay bitrefill buy --slug --amount --payment-method --email --broadcast [--no-wait]
• Bitrefill 预览付款字段：payment.amount 表示链上基础单位整数。
• Bitrefill 发票列表：agentpay bitrefill invoice list
• Bitrefill 发票查询：agentpay bitrefill invoice get --invoice-id [--access-token ]
• Bitrefill 发票等待：agentpay bitrefill invoice wait --invoice-id [--access-token ] [--timeout ]

策略规则

• 切勿提出开放式策略问题。
• 将用户请求映射为以下类型之一：
  • 保留现有策略
  • 在 TUI 中收紧默认代币限额
  • 在 TUI 中添加人工审批额度范围
  • 检查或处理人工审批请求
• 策略相关操作应默认使用 agentpay admin tui。
• 若用户明确要求精确的 CLI 命令以设置每代币默认限额，请使用 agentpay admin token set-chain ...；该命令将更新已保存的配置，并尝试刷新现有钱包的实时守护进程连接。
• agentpay admin token set-chain ... 需要本地保险库密码提示或传入 --vault-password-stdin。若实时应用步骤失败，请勿声称已保存的配置或守护进程策略已变更。
• 面向特定目标地址的覆盖策略属于 TUI 路径。除非用户实际完成了 TUI 流程，否则不得声称其已生效。
• 策略相关操作切勿在聊天中索要 VAULT_PASSWORD。若 CLI 或 UI 在本地弹出提示，则该安全提示发生在聊天环境之外。

人工审批规则

• 将人工审批触发视为“待处理”，而非“失败”。
• 告知用户该请求正在等待其审批。
• 优先使用本地管理员 CLI 审批命令。
• 对于 transfer --broadcast、transfer-native --broadcast、approve --broadcast 和 bitrefill buy --broadcast，请告知用户审批完成后无需重新运行原始命令。CLI 将每 2 秒轮询一次，最长持续 5 分钟，一旦同一审批请求被批准即自动继续执行。
• 若原始广播命令在审批完成后已退出，请使用 agentpay admin resume-manual-approval-request --approval-request-id 。
• agentpay broadcast 及其他非自动等待流程仍将打印审批详情并退出。
• 若用户明确要求原始 CLI 命令，请使用以下命令：
  • agentpay admin list-manual-approval-requests
  • agentpay admin approve-manual-approval-request --approval-request-id
  • agentpay admin resume-manual-approval-request --approval-request-id
  • agentpay admin reject-manual-approval-request --approval-request-id --rejection-reason

最小化澄清规则

• 若用户说“转账”但未指定网络或资产，切勿首先询问这两项，应直接使用默认值。
• 仅需进一步确认以下关键字段：
  • 金额
  • 收款方
  • 被授权方（spender）

MPP 服务

AgentPay 可通过 agentpay mpp 支付任意启用 MPP 的 API。无需 API 密钥或账户——支付通过 HTTP 402 协议内联完成。CLI 从服务器挑战中解析支付链，并支持所有兼容 EVM 的网络。

• 当前支持的 MPP 大语言模型（LLM）/搜索服务列表请参阅 https://mpp.dev/services/llms.txt。请勿依赖静态的仓库内服务目录。
• --amount 参数为可选。若省略，CLI 将自动按服务器挑战金额付款；若提供，则 CLI 会在付款前验证挑战金额是否匹配。
• 钱包必须在服务挑战所指定的链上持有对应的支付代币。
• mpp 支持在任意兼容 EVM 的链上扣款。
• 会话模式（托管通道）仅限 Tempo 支持。

额外参考资料

• 仅当需要精确的命令行参数或示例时，请查阅 references/capabilities.md。
• 仅当需要简短的实时演示脚本时，请查阅 references/demo-walkthrough.md。