零资金跑通完整支付闭环:ixrail AgentPay沙箱演示x402支付流程手把手教学
零资金跑通完整支付闭环:ixrail AgentPay沙箱演示x402支付流程手把手教学
想让 AI Agent 自己"掏钱"调用 API、买数据、租算力,又不想拿真金白银冒险?ixrail AgentPay 的沙箱演示(Sandbox Demo)帮你零资金跑通 x402 支付流程:从创建 Agent 钱包、设置消费策略,到支付一个本地 mock 接口并拿回带签名的收据,整条支付闭环都在 VS Code 里一次做完。本文带你手把手走一遍。
ixrail AgentPay 是什么?AI 的"钱包 + 预算 + 支付通道"
先说痛点:Agent 框架和 MCP 服务器越来越需要为消耗的资源付费——API 调用、数据、算力——但不可能每笔都人工确认。ixrail AgentPay 把这些能力直接搬进编辑器:
- 🔐 钱包:通过 VS Code
SecretStorage创建并安全存储 - 📊 消费策略:单笔 / 每日 / 每月上限、审批阈值、白名单 / 黑名单
- 🌐 本地认证 broker:本地 Agent 可经 HTTP 调用 AgentPay 工具
- 🧾 带签名、防重放收据:每笔结算都留痕
- 🧪 沙箱演示:mock 商家 + 模拟结算,零资金也能走完"支付 → 收据"
5 分钟安装:两种方式任选
方式一:从 Marketplace 一键安装(推荐)
code --install-extension ixrail.ixrail
或在扩展面板(Ctrl+Shift+X / Cmd+Shift+X)搜索 ixrail AgentPay。要求 VS Code ≥ 1.85。
方式二:从源码构建
git clone https://gitcode.com/gh_mirrors/by/ixrail
cd ixrail
npm install && npm run build
⚠️ 该仓库快照默认附带打包好的
out/产物,完整构建流程与目录结构见 src/README.md 和 package.json。
零资金跑通沙箱演示:4 步启动支付闭环
这是全文核心。全程不需要任何资金,因为默认开启 ixrail.simulateSettlement 模拟结算。
第 1 步:一键搭建沙箱
打开活动栏的 ixrail AgentPay 侧边栏,选择 Set Up Sandbox Demo。它会自动完成:
- 创建名为
sandbox-demo的 Base Sepolia 钱包(不存在才建) - 套用"仅 localhost"的消费策略
- 启动认证 broker 与内置 mock 商家
- 把 broker 的 bearer token 复制到剪贴板
第 2 步:发起一次 x402 支付
选择 Pay endpoint,选中 sandbox-demo,目标地址填:
http://127.0.0.1:4021/v1/weather
内置 mock 商家(out/mock-merchant/server.js)会收取 0.05 USDC,并拒绝重复使用同一张收据凭证(防重放)。
第 3 步:查看签名收据
在 Agent 卡片里查看最近支付,或打开 All receipts 浏览带签名的收据账本。
第 4 步:随时刹车
需要立即停止某个 Agent 时,用 Revoke access 一键吊销;Restore access 会重新套用其已保存的策略。
💡 想跑真实的 Base Sepolia USDC 转账?关闭
ixrail.simulateSettlement,先给钱包充值 USDC 和少量 ETH(gas),再重复支付即可。
x402 支付流程在幕后做了什么?6 步拆解
看懂闭环,比只会点按钮更省心。一次 x402 支付的完整链路(详见 docs/ARCHITECTURE.md):
- Agent 调用
pay_x402_endpoint,传入目标 URL - AgentPay 先正常请求该资源;若不是
402,直接原样返回 - 遇到
402,校验支付要求:正数金额、资产必须是USDC、合法 EVM 收款地址、链为base-sepolia/base、钱包在同一链、符合调用方上限与 Agent 策略 - 通过后预留额度并签名;模拟模式生成合成结算,真实模式广播链上 USDC 转账
- 签一张规范化收据,再带
X-Payment-Proof与X-Ixrail-Receipt头重试原请求 - 把花费记入每日 / 每月上限,释放预留
消费策略:给 Agent 花钱上三道锁
Agent 自主付款最怕"超支"。策略引擎在签名前评估每一笔结算:
| 控制项 | 作用 |
|---|---|
| 单笔上限 | 一笔支付的最大值 |
| 每日 / 每月上限 | 当前 UTC 日 / 月已记花费 + 活跃预留 |
| 审批阈值 | ≥ 该金额需开发者在 VS Code 显式确认 |
| 白名单 / 黑名单 | 允许的商家域名或收款地址;黑名单优先 |
| 额度预留 | 批准的花费预留 10 分钟,防并发请求绕过上限 |
| 吊销 | 拒绝该 Agent 全部支付并清空预留 |
从沙箱走向真实 USDC:注意事项
模拟结算不移动任何代币,返回的是合成哈希与本地签名收据,只用于打通链路。切到链上真实转账前请留意(完整清单见 README.md):
- 金额以 JavaScript 数字表示,按 6 位小数舍入;面向受控开发场景,而非高价值资金操作
get_balance当前报告的是 gas 用的原生 ETH,而非 USDC 余额- 主网默认禁用;需
IXRAIL_ALLOW_MAINNET_PAYMENTS=1才会允许真实、不可逆的转账 - 提交交易不等确认,请独立核验后再视为最终
常见问题:30 秒排错
- 端口 4021 / 4022 被占用:为商家设
IXRAIL_MOCK_MERCHANT_PORT,或为 broker 设IXRAIL_HTTP_PORT/ixrail.brokerPort,并同步改支付地址 /tools/*返回 401:请求头带上Authorization: Bearer <token>;不带IXRAIL_HTTP_TOKEN重启会生成新 token- 策略拒绝支付:依次检查吊销状态、白 / 黑名单、单笔上限、UTC 累计花费、活跃预留、调用方
maxAmountUsd - 支付需要审批:金额 ≥ 阈值;独立进程默认拒绝"需审批"的结算
- MCP 与 VS Code 看到不同钱包:两者默认用不同存储,让独立进程指向同一个
IXRAIL_AGENTPAY_STORE即可
写在最后
ixrail AgentPay 把"钱包、预算、支付通道、收据"四件套装进 VS Code,而沙箱演示让这一切零资金即可体验。先跑通 sandbox-demo,理解 402 的完整闭环,再逐步接入真实 USDC——这是最稳的上手路径。更多组件图与数据流参考 docs/ARCHITECTURE.md,版本演进见 CHANGELOG.md。