Xona WalletXona Wallet
zh
@xona-labs/xpay

文档

面向智能体商业的钱包:支持多网络 USDC、x402 支付,以及在 21,000+ 个服务中进行发现。以 CLI、SDK 和 MCP 服务器三种形态提供。

安装

CLI 和 MCP 服务器全局安装;SDK 安装到项目中。它们共享同一核心,因此可以混合使用。

# CLI + MCP server, system-wide
npm install -g @xona-labs/xpay

# SDK, in a project
npm install @xona-labs/xpay

快速开始

创建 profile,在 Solana 或 Base 上向这些地址充值少量 USDC,然后发现并付款。

bash
$ npm install -g @xona-labs/xpay
$ xpay init
✔ Solana 7RB7frd…6qkpf5ph
✔ EVM 0xA5D9…1023dfa
$ xpay discover "short video"
$0.5000 solana api.xona-agent.com
$ xpay pay api.xona-agent.com/video/…
✔ Paid $0.5000 on solana · 1.2s
bash@xona-labs/xpay
请备份你的助记词。 init 只会打印一次 24 个单词的种子,并用口令加密你的密钥。一旦丢失将无法恢复。

CLI 命令

xpay init [name]创建 profile,由同一个种子生成 Solana + EVM。参数:--import、--no-encrypt、--workspace。
xpay accountslist · show · use,管理和切换 profile。
xpay balance当前 profile 在各网络上的 USDC 余额。
xpay discover [query]搜索 21k+ 个 x402 服务。参数:--network、--limit、--json。
xpay pay <url>为 x402 端点付款(目录中的或实时 402)。参数:--max-usd、--body、-y。
xpay transfer <amt> USDC <to>直接转账 USDC,受防护规则约束。参数:--network、-y。
xpay report全面的 USDC 报告(每日 / 每周 / 每月),包括总额、净流量、时间线和主要交易对手。参数:--period、--network、--json。
xpay guardrailshow · set · clear,管理支出上限和允许的主机。
xpay biometricstatus · enable · disable,使用 Touch ID 解锁钱包口令(macOS)。
xpay mcp在 stdio 上启动 MCP 服务器。

SDK

CLI 是对 SDK 的一层轻量封装,每条命令都有对应的编程接口。单一入口,完整类型。

agent.ts
import { createXPay, loadProfile } from "@xona-labs/xpay"
const xpay = createXPay({
profile: await loadProfile({ passphrase }),
});
// pay any x402 endpoint, get the result
const video = await xpay.useByUrl(
"https://api.xona-agent.com/video/short-generation",
{ body: { prompt: "a cat astronaut" } }
);
typescript@xona-labs/xpay

其他常用接口:

await xpay.discover({ query: "weather" });
await xpay.do("translate this PDF to Japanese");
await xpay.transfer({ amount: 1, to, token: "USDC" });
await xpay.report({ period: "weekly" }); // daily | weekly | monthly
await xpay.wallet.balance("solana");

智能体运行时可获得一流的工具定义:forClaude(xpay)、forOpenAI(xpay) 和 forGemini(xpay),处理逻辑相同,schema 适配各厂商格式。

活动报告

xpay report 取代了旧的直连 RPC 历史命令。链上数据由 OrbitX402 在服务端获取,你这边无需 RPC URL,不受速率限制,也不会出现 429 错误。

# CLI
xpay report                      # weekly (default)
xpay report --period daily
xpay report --period monthly --json

# SDK
const report = await xpay.report({ period: "weekly" });
// report.summary   → { totalSent, totalReceived, netFlow, txCount }
// report.timeline  → daily buckets with sent / received / txCount
// report.topCounterparties → sorted by volume
// report.topTransactions   → biggest individual payments

对应的 MCP 工具是 xpay_report,智能体无需任何额外设置即可请求支出摘要。

MCP 服务器

将 Xona Wallet 接入任何 MCP 主机(Claude Desktop、Cursor、Codex),无需代码,无需密钥。首次运行时,智能体会获得自己的钱包;地址会打印在服务器日志中,为其充值 USDC 后智能体即可付款。钱包会持久保存,因此重启后地址保持不变。

claude_desktop_config.json
// claude_desktop_config.json - no keys, no setup
{
"mcpServers": {
"xpay": {
"command": "npx",
"args": ["-y", "@xona-labs/xpay", "mcp"]
}
}
}
// first run → the agent gets its own wallet; fund the printed address
› "pay api.xona-agent.com to make a short video"
json@xona-labs/xpay

已经有钱包了?在配置的 env 中设置 XPAY_SOLANA_SECRET,或者通过 XPAY_PROFILE + XPAY_PASSPHRASE 指向一个 xpay init profile。两者都优先于自动生成的钱包。

随后主机会提供七个工具:xpay_discover、xpay_use、xpay_do、xpay_transfer、xpay_balance、xpay_report、xpay_guardrail。

智能网络路由。 当某个服务接受多个网络时,Xona Wallet 会从有余额的钱包付款。余额为 $0 的 Base 钱包会自动切换到已充值的 Solana 钱包。如果没有任何钱包能支付费用,调用会快速失败,并给出清晰的各网络余额信息,而不是原始错误。

防护规则

防护规则在触及任何签名器之前运行,因此行为异常的智能体无法绕过它们。金额上限同时适用于付费调用和转账;允许的主机仅适用于 x402 调用。

xpay guardrail set \
  --max-per-tx 0.5 \
  --max-per-day 5 \
  --require-approval-above 1 \
  --allowed-hosts 'api.payai.network,*.xona.xyz'

金额达到或超过 requireApprovalAbove 的调用需要明确审批:启用生物识别解锁时为 Touch ID 提示,否则为终端中的 y/n 确认。在 MCP 服务器中仅支持 Touch ID,智能体发起的大额付款会以系统对话框的形式出现,需要你亲自批准。在 SDK 中,可以将 onApprovalRequired 钩子接入任何你喜欢的方式:推送通知、生物识别提示或 webhook。

生物识别解锁(macOS)

不必在每条命令中输入口令,改用 Touch ID 解锁。

xpay biometric enable     # verifies your passphrase, then stores it Touch ID-gated
xpay balance              # → Touch ID prompt instead of a passphrase prompt
xpay biometric status     # availability + current state
xpay biometric disable    # removes the keychain entry

钱包的 scrypt + AES-256-GCM 加密保持不变。enable 会将口令存入你的登录钥匙串,一个小型原生辅助程序仅在 LocalAuthentication 检查通过后才会释放它(首次使用时编译,需要 Xcode Command Line Tools)。解锁顺序:--passphrase → $XPAY_PASSPHRASE → Touch ID → 交互式提示。

生物识别只是为口令加一道门,绝不会取代口令。 你的口令在任何地方都依然有效,并且仍是唯一的恢复途径。如果 Touch ID 不可用,CLI 会回退为要求输入口令。额外好处:启用生物识别解锁后,MCP 服务器不再需要在主机配置中以明文保存 XPAY_PASSPHRASE。它只会在启动时弹出一次 Touch ID 对话框。

Profile

每个 profile 都是 ~/.xpay/ 下的一个目录:

~/.xpay/
└── default/
    ├── wallet.json    # BIP-39 seed, AES-256-GCM encrypted
    └── config.json    # networks, guardrail, RPC overrides

同一个助记词可派生 Solana(m/44'/501',兼容 Phantom)和 EVM(m/44'/60',兼容 MetaMask)。可以用 XPAY_HOME 覆盖根目录,或使用 xpay init --workspace 创建项目本地的 profile。

文档:Xona Wallet