AgentXPay Skill
让 AI Agent 具备在 Monad 区块链上自主发现 AI 服务、链上付费、管理钱包的能力。
核心机制：通过 x402 协议（HTTP 402 Payment Required），Agent 发送请求 → 收到 402 → 自动链上支付 → 携带交易哈希重试 → 获取 AI 服务响应，全程无需人工介入。
前置条件
在使用本 Skill 前，需要确保以下配置可用：
| 变量 | 必填 | 说明 |
|---|
RPC_URL | 是 | Monad RPC 节点地址 |
PRIVATE_KEY | 是 | Agent 钱包私钥 |
SERVICE_REGISTRY_ADDRESS | 是 | ServiceRegistry 合约地址 |
PAYMENT_MANAGER_ADDRESS | 是 | PaymentManager 合约地址 |
SUBSCRIPTION_MANAGER_ADDRESS | 否 | SubscriptionManager 合约地址 |
ESCROW_ADDRESS | 否 | Escrow 合约地址 |
AGENT_WALLET_FACTORY_ADDRESS | 否 | AgentWalletFactory 合约地址 |
- 依赖：
@agentxpay/sdk、ethers v6
可用 Tool 清单
本 Skill 提供以下 7 个 Tool，AI 可根据任务需要选择调用：
Tool 1: agentxpay_discover_services
用途：在 Monad 链上发现已注册的 AI 服务。
参数：
| 参数 | 类型 | 必填 | 说明 |
|---|
| category | string | 否 | 服务类别过滤，如 "LLM"、"Image"、"Code" |
| maxPrice | string | 否 | 最大单价（ETH），如 "0.05" |
返回：{ services: [...], totalCount: number }
使用场景：用户问"有哪些 AI 服务可用"、"找一个图像生成服务"时调用。
执行方式：运行 scripts/run-tool.ts discover_services '{"category":"LLM"}'
Tool 2: agentxpay_pay_and_call （核心 Tool）
用途：通过 x402 协议自动付费调用 AI 服务端点。
参数：
| 参数 | 类型 | 必填 | 说明 |
|---|
| url | string | 是 | AI 服务端点 URL |
| method | string | 否 | HTTP 方法，默认 "POST" |
| body | object | 否 | 请求体（会被 JSON 序列化） |
| headers | object | 否 | 额外 HTTP 请求头 |
返回：{ status, data, payment: { txHash, amount, serviceId }, latencyMs }
工作流程：
- 向目标 URL 发送 HTTP 请求
- 若收到 HTTP 402 响应，解析
X-Payment-* 响应头
- 自动调用 PaymentManager 合约完成链上支付
- 携带
X-Payment-TxHash 重新发送请求
- 返回 AI 服务响应 + 支付凭证
使用场景：用户说"帮我调用这个 AI 接口"、"用 GPT-4 回答问题"时调用。
执行方式：运行 scripts/run-tool.ts pay_and_call '{"url":"http://...","method":"POST","body":{"prompt":"hello"}}'
Tool 3: agentxpay_smart_call （推荐：一步到位）
用途：智能发现 → 选择最优服务 → 自动付费调用，一步完成。
参数：
| 参数 | 类型 | 必填 | 说明 |
|---|
| task | string | 是 | 任务描述，如 "生成一张赛博朋克猫图片" |
| category | string | 否 | 偏好的服务类别 |
| maxBudget | string | 否 | 最大预算（ETH） |
| preferCheapest | boolean | 否 | 是否优先选最便宜的 |
返回：{ selectedService: {...}, response, payment, latencyMs }
使用场景：用户描述一个需要外部 AI 服务的任务，但没有指定具体服务端点时。这是最常用的 Tool。
执行方式：运行 scripts/run-tool.ts smart_call '{"task":"生成赛博朋克猫图片","category":"Image"}'
Tool 4: agentxpay_manage_wallet
用途：创建和管理 Agent 智能合约钱包。
参数：
| 参数 | 类型 | 必填 | 说明 |
|---|
| action | string | 是 | "create" / "fund" / "get_info" / "set_limit" |
| dailyLimit | string | 条件 | 每日限额（ETH），create/set_limit 时需要 |
| amount | string | 条件 | 金额（ETH），fund 时需要 |
| walletAddress | string | 条件 | 钱包地址，fund/get_info/set_limit 时需要 |
返回：{ walletAddress, balance, dailyLimit, dailySpent, remainingAllowance, txHash }
使用场景：用户说"创建一个 Agent 钱包"、"查看钱包余额"、"设置每日限额"时调用。
Tool 5: agentxpay_subscribe
用途：订阅链上 AI 服务的周期性计划。
参数：
| 参数 | 类型 | 必填 | 说明 |
|---|
| serviceId | number | 是 | 链上服务 ID |
| planId | number | 否 | 订阅计划 ID（不传则自动选第一个） |
返回：{ subscriptionId, planName, price, txHash, hasAccess }
使用场景：用户说"订阅这个服务"、"我想包月使用"时调用。
Tool 6: agentxpay_create_escrow
用途：为定制 AI 任务创建链上资金托管。
参数：
| 参数 | 类型 | 必填 | 说明 |
|---|
| serviceId | number | 是 | 链上服务 ID |
| amount | string | 是 | 托管金额（ETH） |
| deadlineDays | number | 是 | 截止天数 |
| description | string | 是 | 任务描述 |
返回：{ escrowId, amount, deadline, txHash }
使用场景：用户说"我有一个定制任务需要先锁定资金"时调用。
Tool 7: agentxpay_get_agent_info
用途：查询当前 Agent 的钱包地址、余额和网络信息。
参数：无
返回：{ address, balance, network }
使用场景：用户问"我的钱包地址是什么"、"余额还有多少"时调用。
标准操作流程 (SOP)
场景 A：用户需要调用外部 AI 服务
步骤 1: 调用 agentxpay_discover_services 查看可用服务和价格
步骤 2: 向用户展示服务列表和价格，确认是否继续
步骤 3: 用户确认后，调用 agentxpay_pay_and_call 或 agentxpay_smart_call
步骤 4: 返回 AI 服务响应 + 支付交易哈希
场景 B：用户直接描述任务（推荐）
步骤 1: 调用 agentxpay_smart_call，传入任务描述和可选的类别/预算
步骤 2: Skill 自动发现服务 → 选择最优 → 付费调用
步骤 3: 返回结果给用户，附带所选服务信息和支付凭证
场景 C：用户要管理 Agent 钱包
步骤 1: 调用 agentxpay_manage_wallet action="get_info" 查看当前状态
步骤 2: 根据需要执行 create/fund/set_limit
场景 D：用户要订阅服务
步骤 1: 调用 agentxpay_discover_services 找到目标服务
步骤 2: 调用 agentxpay_subscribe 订阅
步骤 3: 确认访问权限已激活
错误处理
| 错误 | 原因 | 处理方式 |
|---|
| "No matching services found" | 链上无匹配服务 | 建议用户放宽过滤条件或检查合约部署 |
| "insufficient funds" | Agent 余额不足 | 提示用户充值或使用 agentxpay_manage_wallet fund |
| HTTP 402 retry 失败 | 支付验证未通过 | 检查合约地址和网络配置 |
| "daily limit exceeded" | 超出每日限额 | 提示用户调整限额或等待次日重置 |
安全注意事项
- 私钥保护：PRIVATE_KEY 通过
openclaw.json 安全注入，不要硬编码
- 每日限额：建议使用 Agent Wallet 的 dailySpendingLimit 限制支出
- 用户确认：在执行付费操作前，应向用户展示价格并获得确认
- 交易验证：所有支付都有链上 txHash，可在区块浏览器验证
引用资源
- CLI 工具执行脚本：参考
scripts/run-tool.ts（可直接 npx tsx 执行）
- TypeScript 类型定义：参考
src/types.ts
- Tool JSON Schema 定义：参考
src/schemas.ts
- 核心运行时实现：参考
src/runtime.ts
- 集成入口和适配器（OpenAI/MCP）：参考
src/index.ts
- x402 协议参考：参考
references/x402-protocol.md
- AgentXPay SDK API 文档：参考
references/sdk-api.md
