xpay

Xona Wallet

以 npm 包 @xona-labs/xpay、xpay CLI 和 xpay_* MCP 工具的形式发布。包名和命令名保持不变。

Agentic 商务钱包。 多网络 USDC 钱包、x402 支付、AgenC 市场雇佣，以及对 20,000 多项服务的发现功能，可通过 CLI、SDK 和 MCP 服务使用。

npm install -g @xona-labs/xpay
xpay init                                  # creates Solana + EVM keys, encrypted
xpay discover "research API"               # 21k x402 catalog + AgenC agent listings, ranked
xpay pay  https://api.example.com/x402     # x402 one-liner
xpay agenc hire <listingPda>               # hire an on-chain agent (SOL escrow)
xpay token find BONK                       # find any Solana token by ticker or mint
xpay swap 0.5 SOL BONK                     # swap in your own wallet via Jupiter
xpay transfer 5 USDC 7G73PL...gC           # direct USDC transfer
xpay balance                               # unified across networks
xpay report                                # daily / weekly / monthly report via OrbitX402

// SDK - same primitives, programmatic
import { loadProfile, createXPay } from "@xona-labs/xpay";
const xpay = createXPay({ profile: await loadProfile({ passphrase }) });
const result = await xpay.do("translate this PDF to Japanese", { body: { file } });

Xona Wallet 是 Agentic 商务的钱包和支付通道层。它将 x402、USDC、RPC 和多网络路由封装在简洁的接口之后，让 Agent 构建者（Claude / Codex / OpenAI / Gemini / 你自己的 Agent）无需编写支付基础设施，就能发现并支付服务费用。

---

安装

npm install -g @xona-labs/xpay      # CLI + MCP server, system-wide
npm install     @xona-labs/xpay      # programmatic SDK in a project

快速入门

xpay init
# ✔ Profile "default" created at /Users/you/.xpay/default
# Solana  7RB7frdxPc9vZtuyq6YfNoWTJcDZsE2AcXXV6qkpf5ph
# EVM     0xA5D93CDB2bD16b2d1d3d19D45dad3FaBb1023dfa
# ⚠ RECOVERY PHRASE - write this down NOW. We cannot recover it for you.
#   1. depend   2. guess    3. mercy    4. online
#   ... (24 words)

向这些地址充值几美元的 USDC，可使用 Solana 主网、Base，或两者兼用。然后：

xpay balance
xpay discover "image generation"
xpay pay https://orbisapi.com/proxy/image-alt-text-generator-api-1c9472

CLI 命令

命令	功能
xpay init [name]	创建一个配置档案（使用同一个 BIP-39 助记词生成 Solana 和 EVM 密钥）。使用 --import 从助记词恢复，使用 --no-encrypt 创建开发钱包，使用 --workspace 将数据存储在本地。
xpay accounts list | show | use	列出配置档案、查看其中一个，或设置当前使用的配置档案。
xpay balance	查看当前配置档案在各网络上的代币余额，以及稳定币总额。涵盖 Solana、Base 和其他 EVM 链、Robinhood Chain，以及 Stable。支持 --network。
xpay discover [query]	搜索跨链的 21k+ 个 x402 服务（Solana、Base、BNB Chain 和其他 EVM 网络），以及 AgenC marketplace Agent 列表（缓存在磁盘上）。Solana 商户会显示其 ERC-8004 信任度。支持 --network、--limit、--min-trust、--no-trust、--json。
xpay trust <wallet>	查询 Solana 商户钱包的 ERC-8004 Agent 身份和声誉。只读，无需钱包。支持 --json。
xpay pay <url>	支付 x402 端点费用。适用于目录 URL 和任何返回 402 的 URL。支持 --max-usd、--body、-y。
xpay agenc hire <listingPda>	雇用一个 AgenC marketplace 列表中的 Agent——将其 SOL 价格托管在链上；提供方会异步执行任务。支持 --max-usd、--review-window、-y。
xpay agenc status <taskPda>	查看雇用任务的进度（只读，无需钱包）。支持 --json。
xpay token find <query>	按代号、名称或 mint 地址查找 Solana 代币（Jupiter）——查看价格、市值、流动性和验证状态。只读。支持 --limit、--json。
xpay token rwa [query]	列出 Solana 上可交易的 RWA 代币：代币化股票/ETF（xStocks、Ondo、Remora）和 USDY。只读。支持 --category、--limit、--json。
xpay orders add | list | run	常设股票订单：对代币化股票进行定期买入和条件式单次买入，由 cron、调度器或 Agent 执行 xpay orders run。另支持 approve、cancel、pause、resume。
xpay swap <amount> <from> <to>	通过 Jupiter 在你的钱包中兑换代币（仅限 Solana），受安全限制规则约束。支持 --slippage-bps、-y。
xpay trade <amount> <from> <to>	通过 Uniswap V3 / NOXA Fun 在 Robinhood Chain 上交易代币（ETH↔代币），受安全限制规则约束。支持 --slippage-bps、--quote-only、-y。
xpay trending	列出 Robinhood Chain 上的热门代币（只读，无需钱包）。支持 --new、--limit。
xpay x user | posts <handle>	获取 X（Twitter）账户实时数据——个人资料（约 $0.01）或近期帖子（约 $0.06），通过 x402 按成本付费。无需 X 账户。
xpay zauth reposcan <repoUrl>	通过合作方 zauth 扫描代码仓库安全性——获取 zauth 评分以及来源/漏洞报告（通过 x402 支付约 $0.05 USDC）。支持 --json、-y。
xpay zauth status <sessionToken>	查看正在运行的 zauth 扫描（免费、只读，无需钱包）。支持 --json。
xpay shop search "<query>"	通过一次查询，在 Google Shopping、Amazon 和 eBay 上进行商品发现（通过 x402 支付约 $0.02 USDC，搜索的平台越少，费用越低）。支持 --marketplaces、--price-min/max、--condition、--sort、--json、-y。
xpay shop quote "<query>"	免费预检：查看确切的搜索价格以及查询词的解析方式（无需钱包）。支持 --json。
xpay transfer <amount> USDC <to>	直接转账稳定币（USDC，或在 Stable 上使用 USDT0），受安全限制规则约束。支持 --network、-y。
xpay report	生成全面的 USDC 活动报告——总额、净流量、时间线、主要交易对手和金额最大的交易。支持 --period daily|weekly|monthly、--network、--json。
xpay guardrail show | set | clear	查看或编辑消费限额和允许的主机。
xpay biometric status | enable | disable	使用 Touch ID 解锁钱包密码短语（macOS）。
xpay sana link | unlink | status	关联 Sana API 密钥以启用 Agent 卡片（可选）。
xpay mcp	通过标准输入/输出启动 MCP 服务（供 Claude Desktop / Cursor / Codex 使用）。
所有命令都在单个配置档中运行。使用 xpay accounts use <name> 切换。

SDK

CLI 是 SDK 的轻量封装——每个命令都有对应的编程接口。

import {
  createXPay,
  initProfile,
  loadProfile,
  setProfileGuardrail,
} from "@xona-labs/xpay";

// One-time setup
const created = await initProfile({
  name: "default",
  passphrase: process.env.XPAY_PASSPHRASE!,
});
console.log(created.addresses);   // { solana, evm }
console.log(created.mnemonic);    // back this up; not persisted in plaintext

// Configure spending caps
setProfileGuardrail("default", {
  maxPerTx: 0.5,
  maxPerDay: 5,
  allowedHosts: ["api.payai.network", "*.xona-agent.com"],
});

// Use
const profile = await loadProfile({ name: "default", passphrase: process.env.XPAY_PASSPHRASE });
const xpay    = createXPay({ profile });

await xpay.discover({ query: "weather" });
await xpay.useByUrl("https://...");
await xpay.do("translate this PDF to Japanese");
await xpay.transfer({ amount: 1, to: "7G73PL...", token: "USDC" });
await xpay.report({ period: "weekly" });   // via OrbitX402 - no RPC calls from your code
await xpay.wallet.balance("solana");

Agent 运行时

Xona Wallet 为三大主流 LLM SDK 提供工具定义。处理器相同，架构形式不同。

import Anthropic from "@anthropic-ai/sdk";
import { createXPay, forClaude, loadProfile } from "@xona-labs/xpay";

const xpay = createXPay({ profile: await loadProfile({ passphrase }) });
const { tools, handlers } = forClaude(xpay);

const response = await new Anthropic().messages.create({
  model: "claude-sonnet-4-5",
  tools,
  messages: [{ role: "user", content: "find a cheap weather API and call it" }],
});

for (const block of response.content) {
  if (block.type === "tool_use") {
    const result = await handlers[block.name]!(block.input as Record<string, unknown>);
    // ... feed result back to Claude
  }
}

forOpenAI(xpay) 和 forGemini(xpay) 会将相同的处理器封装为特定厂商的架构。完整的工具调用循环请参阅 examples/claude-agent.ts。

MCP 服务（Claude Desktop / Cursor / Codex）

Xona Wallet 已收录在官方 MCP Registry 中，名称为 io.github.xona-labs/xpay——支持注册表的主机可按此名称发现并 安装。对于其他主机，只需将 Xona Wallet 添加到主机配置中——无需代码、无需密钥，也无需 xpay init。 首次启动时，Agent 会 自动获得自己的钱包：

// ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "xpay": {
      "command": "npx",
      "args": ["-y", "@xona-labs/xpay", "mcp"]
    }
  }
}

设置就这么简单。生成的钱包的 Solana 地址会在首次运行时打印到 stderr——为其充值 USDC，Agent 就能付款。钱包会保存在 ~/.xpay 下，并在后续每次启动时重复使用，因此地址保持不变。

主机可以看到核心工具：xpay_discover、xpay_use、xpay_do、xpay_transfer、xpay_balance、xpay_report、xpay_guardrail、xpay_token_find、xpay_swap、xpay_trending_tokens、xpay_trade_quote、xpay_trade、xpay_x_user、xpay_x_posts、xpay_zauth_reposcan、xpay_zauth_scan_status、xpay_shop_search、xpay_shop_quote、xpay_shop_lens、xpay_shop_lens_quote、xpay_rwa_find、xpay_trust_check、xpay_order_create、xpay_orders_list、xpay_order_cancel、xpay_orders_run、xpay_agenc_status，以及用于管理意图防火墙的 xpay_bento_status / xpay_bento_enable / xpay_bento_disable。如果你已关联 Sana 密钥（见下文），还会自动注册另外八个 sana_* 工具。

改用自己的钱包——钱包来源的优先顺序是现有配置档 → 密钥环境变量 → 自动生成，因此以下任一方式都可以覆盖生成的钱包：

"env": {
  "XPAY_SOLANA_SECRET": "<base58 key>",  // use a wallet you already hold
  "XPAY_PASSPHRASE":    "<passphrase>",  // or unlock/encrypt a profile
  "XPAY_NO_AUTO_WALLET": "1"             // or disable auto-generation entirely
}

在 macOS 上，如果配置档已启用生物识别解锁，服务会在启动时显示一个 Touch ID 对话框，而不是将密码短语保存在主机配置中。

请参阅 SKILL.md，了解如何通过任何 Agent 使用这些工具的框架无关指南。

配置档

每个配置档都是 ~/.xpay/ 下的一个目录，其中包含：

~/.xpay/
├── default/                       (or any name)
│   ├── wallet.json                BIP-39 seed, AES-256-GCM encrypted by default
│   └── config.json                networks, guardrail, RPC overrides, link
└── cache/                         disk cache of catalogs (auto-managed)

使用 XPAY_HOME=/some/path 或 xpay init --workspace 为项目创建本地配置档。

生物识别解锁（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 会将 密码短语存入你的登录钥匙串，一个小型原生辅助程序（首次使用时编译到 ~/.xpay/bin/，需要 Xcode Command Line Tools）只有在通过 LocalAuthentication 检查后才会释放密码短语。生物识别不会取代密码短语——只负责控制对它的访问。

每条命令的解锁顺序为：--passphrase 标志 → $XPAY_PASSPHRASE → Touch ID → 交互式提示。密码短语在所有场景下仍可使用，也是唯一的恢复途径——如果 Touch ID 不可用（或重新加密后存储的副本过期），CLI 会改为提示你输入密码短语。

macOS 会询问是否允许辅助程序访问钥匙串——请选择 “始终允许”。软件包升级后 会再次询问，因为辅助程序会重新编译。

防护机制

防护机制会在调用任何签名器之前运行，因此行为异常的 Agent（或遭到入侵的大模型）无法绕过它。

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

• maxPerTx / maxPerDay：适用于每笔付费调用和直接转账。
• allowedHosts：仅适用于 x402 调用（转账的目标是地址，而不是主机）。
• maxPerTx / maxPerDay：适用于每笔付费调用和直接转账。
• allowedHosts：仅适用于 x402 调用（转账的目标是地址，而不是主机）。
• requireApprovalAbove：金额 ≥ 阈值的调用需要明确批准。在 CLI 中，如果启用了生物识别解锁，会提示使用 Touch ID；否则会要求输入 y/n 确认。在 MCP 服务中，只支持 Touch ID（无终端），因此 Agent 发起大额付款时会显示系统对话框，需要你亲自批准。在 SDK 中，可将 onApprovalRequired 钩子接入任意流程，例如推送通知、生物识别验证或 webhook。

安全 - Bento 意图防火墙（可选）

支出上限可以阻止 Agent 花费过多，但无法区分合法付款和遭到提示词注入的付款。可选的 Bento 层新增了AI 意图防火墙：每笔付费调用和转账都会在签名前接受恶意意图筛查（提示词注入、钱包被盗刷、意图与执行不一致）。它在防护机制内部运行，也就是本地上限检查通过后立即运行。

xpay bento enable      # prints the agent wallet address to register
xpay bento status      # whether screening is active
xpay bento disable     # turn off - falls back to local caps only

无需 API 密钥——Bento 使用钱包自身的密钥进行身份验证。唯一需要手动完成的步骤是在链上一次性注册 Agent 钱包，前往 app.bentoguard.xyz 即可（使用所有者钱包登录；在注册 Agent 钱包之前，付款会因 Agent not found 而遭到拒绝）。

每次筛查调用都会返回一个判定：

• ALLOW：已通过；Xona Wallet 会照常签名。
• BLOCKED：被标记为严重威胁；Xona Wallet 会在签名前抛出异常，不会转移资金。
• ESCALATED：情况不明确；Xona Wallet 会交由你的 onApprovalRequired 钩子处理，或采取默认拒绝策略。

Agent 也可以通过 MCP 管理该功能：xpay_bento_status、xpay_bento_enable、xpay_bento_disable（如果钱包尚未注册，可通过禁用功能脱离限制）。

Sana Agent 钱包卡（可选）

Xona Wallet 支持与 Sana 的可选集成。Sana 是一款原生面向 Agent 的卡片，可让 AI 在任何接受 Visa 的地方进行线下消费。

激活后，Xona Wallet 会提供第二种钱包形式：用于 Agent 执行 x402 付款的链上 USDC（xpay），以及用于其他消费的 Sana 卡（法币）。两者可以自然配合使用——余额不足时，Agent 可以从 Xona Wallet 钱包向卡片充值。

激活

1. 在 sana.bot 注册，并在 sana.bot/gateway/app/api-keys 生成 API 密钥（read:all 权限涵盖所有只读操作；如需充值和兑换，请添加 write:card）。
2. 将其关联到你的 Xona Wallet 配置文件：

xpay sana link sana_live_...
xpay sana status          # confirm it's stored

3. 重启 MCP 客户端，八个 sana_* 工具就会与标准的 xpay_* 工具一起自动显示。

已注册的工具

工具	功能
sana_card	卡片元数据，包括类型、状态、卡号末四位和有效期
sana_card_balance	卡片可用消费额度
sana_card_deposit	使用 Sana 钱包中的 USDC 为卡片充值
sana_card_transactions	卡片消费记录（分页）
sana_portfolio	Sana 钱包净资产及代币持仓，含 24 小时变动
sana_price	任意代币的实时美元价格及 24 小时变动
sana_swap	在 Sana 钱包中兑换代币
sana_notifications	Sana 钱包近期活动动态

SDK 用法

将 API 密钥传递给 forClaude / forOpenAI / forGemini，即可在 Agent 循环中加入 Sana 工具：

import { createXPay, loadProfile, forClaude } from "@xona-labs/xpay";

const xpay = createXPay({ profile: await loadProfile({ passphrase }) });
const { tools, handlers } = forClaude(xpay, {
  sanaApiKey: process.env.SANABOT_API_KEY,
});
// tools now includes both xpay_* and sana_* entries

也可以在环境中设置 SANABOT_API_KEY，MCP 服务会自动读取，无需修改代码。

取消关联

xpay sana unlink          # removes the key from the profile

下次重启后，MCP 服务中的 sana_* 工具就会消失。

AgenC 市场——雇用链上 Agent

AgenC 是一个 Solana 主网市场，已注册的 Agent 可通过链上托管交易提供服务。可雇用的列表会与 x402 服务一起显示在 xpay discover 中，但它们的执行方式不同，xpay 会自动路由：

	x402 服务	AgenC 列表
定价币种	USDC	原生 SOL
付款方式	HTTP X-Payment 标头	链上托管（程序 HJsZ…w1xK）
结果	立即返回 HTTP 响应	雇用回执——服务提供方异步工作
结算	即时	在你的审核期结束后（默认 24h）

xpay discover "research"                   # AgenC listings show as “agenc escrow”, priced in ◎SOL
xpay agenc hire <listingPda>               # confirm → escrow SOL → get a task PDA
xpay agenc status <taskPda>                # poll: open → claimed → review → settled

同样的智能路由也适用于 SDK 和 MCP——xpay.use(resource) / xpay_use 会检测 agenc-hire 支付方案并执行托管流程，将回执（task、txSig、区块浏览器链接）作为 data 返回。雇用通过 AgenC 的 无人工参与入口完成，该入口会将任务固定为 CreatorReview——未经你接受，托管资金绝不会自动释放。

注意：

• 发现功能通过 AgenC 官方 SDK 客户端读取其托管索引器，这是 AgenC 记录的集成路径；雇用时会定位跨不同种子方案版本的链上审核证明，因此即使 AgenC 频繁升级程序，xpay 也能继续正常工作。升级后尚未重新证明的列表会安全失败，并在付款前给出明确提示。
• 安全限制同样适用于雇用：SOL 价格会按实时价格（多数据源、缓存）换算为 USD，并在签名前根据 maxPerTx/maxPerDay 进行检查。如果无法访问价格数据源且设置了限额，雇用将安全失败。
• 钱包需要有 SOL（用于托管和手续费），而不只是 USDC。
• 目前需要在 agenc.ag 上审核/接受结果；计划推出 xpay agenc accept。
• 配置（可选）：在配置文件中设置 agenc: { rpcUrl, reviewWindowSecs, endpoint }，或设置 XPAY_AGENC_ENDPOINT。设置 XPAY_DISCOVERY_SOURCES=orbitx402 可选择不使用此发现来源。

代币发现与兑换（Solana）

按代币代码或铸币地址查找任意 Solana 代币，并从你自己的钱包兑换为该代币——默认无需密钥，通过 Jupiter 元聚合器完成：

xpay token find BONK                  # price, mcap, liquidity, mint, ✓ verified / ⚠ unverified
xpay swap 0.5 SOL BONK                # quote → confirm → execute (guardrail-gated)
xpay swap 1000 BONK USDC --slippage-bps 50

const tokens = await xpay.findTokens("BONK");          // ranked verified-first
const quote  = await xpay.swapQuote({ amount: 0.5, from: "SOL", to: tokens[0].mint });
const result = await xpay.swap({ amount: 0.5, from: "SOL", to: tokens[0].mint });

注意：

• 验证至关重要。 任何人都可以铸造代币并重复使用真实代币的代码。仅输入代码时，只会解析为 Jupiter 已验证代币；如果代码存在歧义，会报错并列出候选代币；未验证的代币必须通过其准确铸币地址指定。xpay token find 会显示验证标记。
• 安全限制同样适用。 输入代币会按 USD 定价（采用 Jupiter 自身的估价），并在签名前根据 maxPerTx / maxPerDay 强制检查；设置了限额时，如果无法为代币定价则会安全失败。兑换仅在你的钱包内进行（不会发送给外部收款方），因此 allowedHosts 不适用。
• 滑点默认采用 Jupiter 的动态滑点；可按调用覆盖（--slippage-bps），也可按配置文件设置（swap.slippageBps）。
• 默认无需密钥（共享限流桶约为 20 req/s）。设置 JUPITER_API_KEY（或配置文件中的 swap.apiKey）可提高限额；XPAY_JUPITER_ENDPOINT 可覆盖 API 基础地址。
• 这是在你自己的 xpay 钱包中进行的原生兑换。单独的 xpay sana swap 会在 Sana 托管的钱包内兑换，并且需要 Sana API 密钥。

商户信任（Solana 上的 ERC-8004）

在向陌生服务付款前，先确认对方是谁。Solana 商户钱包（x402 的 payTo）会在 8004-solana 注册表中查询。该注册表是 ERC-8004 Trustless Agents 在 Solana 上的实现：包含 Agent 身份（Metaplex Core 资产）和链上客户端反馈，以及可选的 ATOM 评分（信任等级、质量、置信度、风险）。免费、只读，无需钱包：

xpay trust 28heAMpFkeUJsL7o7apiK4oJwZWq2fUHinRwbgYYsemG   # identity, 0-100 feedback score, review count, SAID identity
xpay discover "token price" --network solana               # each Solana result shows a trust line
xpay discover "data" --min-trust 50                         # only registered merchants scoring >= 50

const trust = await lookupMerchantTrust(payTo);   // { registered, agent: { name, avgScore, feedbackCount, atom? }, summary, said? }
const results = await xpay.discover({ query: "data", minTrust: 0 });  // resource.trust on each result

说明：

• 钱包地址可以匹配 Agent 的运营 agent_wallet 或其 owner。若多个身份共用一个钱包，则返回最强的身份（依次按 ATOM 等级、评价数量、评分排序），并附带 agentCount。
• avgScore 是客户端反馈的平均分（0-100）。ATOM 的 quality 会按置信度加权，因此 Agent 积累反馈之前，该值会保持较低；不要将两者混为一谈。
• 大多数商户尚未注册，所以“无身份”是常见情况，并非警告。--min-trust / minTrust 会额外获取（50 个候选项），但仍可能返回空结果。
• 查询通过注册表的公共索引器（8004-indexer-main.qnt.sh，无需密钥，每个 IP 每分钟 100 次请求）进行，每个唯一钱包查询一次，缓存 10 分钟，包括未找到的结果。XPAY_8004_INDEXER 可覆盖该地址；--no-trust / trust: false 可跳过查询。查询失败不会导致发现失败。
• 目前仅支持 Solana。EVM 上的 ERC-8004 注册表没有链上钱包到 Agent 的反向查询功能。
• SAID Protocol 也会检查同一个钱包，并与 ERC-8004 并列报告为 trust.said（null = 无 SAID 身份）：包括 verified、tier、badges 和 0-100 的 score。该分数是 SAID 根据身份、活动和存续时间信号计算的综合分数，不是客户端反馈，因此即使没有评价，Agent 也可能得分较高；它不会与 8004 的 avgScore 合并，并且 --min-trust 仍只按 8004 评分筛选。XPAY_SAID_API 可覆盖 API 基础地址；SAID 查询失败时只会导致 said 未设置。
• MCP：xpay_trust_check（免费），而 xpay_discover 结果会包含 trust 和可选的 minTrust 筛选条件。

RWA 发现（Solana）

列出可交易的现实世界资产代币：RWA 涵盖任何代币化的链下资产；而如今在 Solana DEX 上实际交易的，是代币化股票/ETF（Backed xStocks，例如 TSLAx/SPYx；Ondo Global Markets，例如 TSLAon/GLDon；Remora；Backpack Securities）以及由国债支持的收益币 USDY。免费、只读，无需钱包：

xpay token rwa                        # full list, verified-first by liquidity
xpay token rwa tesla                  # matches TSLAx (Backed) and TSLAon (Ondo)
xpay token rwa --category treasuries  # USDY
xpay swap 10 USDC TSLAx               # swap into one (guardrail-gated)

const rwas = await xpay.findRwaTokens({ query: "nvidia" });   // NVDAx, NVDAon

说明：

• 发现功能会扫描 Jupiter 的搜索 API，并根据 Jupiter 自身的 rwa/stocks/xstocks 代币标签进行筛选（标签端点本身不接受这些标签），因此列表中的代币均经过 Jupiter 验证，并提供实时价格。结果会在进程内缓存 5 分钟。
• 代币化股票会跟踪标的资产价格，但它们是发行方的欠条（跟踪凭证），并非经纪账户中的股票：没有投票权，且需承担发行方风险。
• 不包括 Solana 上需许可的基金（BlackRock BUIDL、Ondo OUSG）：它们需要通过 KYC、未经 Jupiter 验证，也没有 DEX 流动性，因此无法进行兑换。
• MCP：xpay_rwa_find（免费）。所有返回结果都可以通过 xpay_swap / xpay swap 使用 USDC 兑换。

定期股票订单

对代币化股票（xStocks 和其他 Solana 发行方）进行定期买入和有条件的一次性买入，订单存储在钱包配置文件中，因此任何 Agent 框架都能创建订单，任何调度器都能执行订单：

xpay orders add buy 25 SPY --every weekly --budget 500              # $25 of SPYx every week, $500 total
xpay orders add buy 100 NVDA --max-premium 0.5 --market-hours       # once, when the premium is <= 0.5% during US hours
xpay orders list                                                     # status, caps used, why an order is still waiting
xpay orders run --dry-run                                            # what would fill right now, nothing signed
xpay orders run                                                      # execute due orders (cron: */15 * * * *)

await createStockOrder(profile.path, { side: "buy", stock: "SPY", amount: 25, every: "weekly", limits: { maxTotalUsd: 500 }, approved: true });
const report = await runDueOrders(profile.path, xpay, { maxPerDay: 200 });

每次运行会按以下顺序判断每笔到期订单：有效期和上限；接着检查市场交易时段（如果启用了 --market-hours）；然后执行与直接股票交易相同的检查（已验证的代币、流动性下限、相对于实际股价的不利溢价／折价，默认为 2%）；最后检查配置文件的 maxPerDay。不符合条件的订单会说明原因，并等待下一次运行；定期订单保持原有周期，跳过错过的周期，而不会补单。

安全模型，因为订单通常会在无人值守时执行：

• 每笔订单都有期限。 定期订单必须设置 --budget 和／或 --max-fills；一次性订单默认在 7 天后过期。
• Agent 无法激活订单。 xpay_order_create 会将订单保存为 pending_approval；只有 xpay orders approve <id>（由人在终端操作）才能激活订单。Agent 可以列出、取消和运行订单，但运行时只会执行已批准的订单。
• 所有运行共用每日上限。 系统根据持久化的成交记录强制执行 maxPerDay，因此分开运行的 cron 调用无法各自获得一份全新的每日额度。
• 绝不重复买入。 已提交但尚未确认的成交会将订单置于 needs_review 状态；检查钱包后，运行 xpay orders resume <id>（如果已成交，则添加 --filled）。触发护栏拒绝（单笔交易上限、审批阈值）时，订单会置于 blocked 状态。一次只能有一个运行任务执行。
• 创建订单时会固定代币（SPY → SPYx mint），因此后续运行不会解析到其他发行方。

无人值守运行需要解锁钱包：在调度器的环境中设置 XPAY_PASSPHRASE（凌晨 3 点无法通过 Touch ID 发起提示）。超过 requireApprovalAbove 的买入如果没有 TTY，会被拒绝，订单也会被阻止。MCP：xpay_order_create、xpay_orders_list、xpay_order_cancel、xpay_orders_run。

Robinhood Chain 交易

直接从你自己的钱包交易 Robinhood Chain（Robinhood 的 Arbitrum L2，链 ID 为 4663）上的 NOXA Fun memecoin 生态，无需 API 密钥。NOXA Fun 代币会在以原生 ETH 报价的 Uniswap V3 池中发行，因此交易直接通过链上 V3 完成：通过 QuoterV2 获取报价，通过 SwapRouter02 执行交易。代币发现（热门／新代币、美元定价）来自 GeckoTerminal 的公共 API。

xpay trending                              # what's hot on Robinhood Chain (free, no wallet)
xpay trending --new                        # freshest launches (higher risk)
xpay trade 0.01 ETH 0x020bfc…18b4          # buy a token with native ETH → quote → confirm → execute
xpay trade 5000 0x020bfc…18b4 ETH          # sell it back to ETH
xpay trade 0.01 ETH CASHCAT --quote-only   # preview without trading (symbol resolved via trending)

const hot    = await xpay.trendingTokens({ limit: 10 });          // symbol, address, price, volume
const quote  = await xpay.tradeQuote({ amount: 0.01, from: "ETH", to: hot[0].address });
const result = await xpay.trade({ amount: 0.01, from: "ETH", to: hot[0].address }); // → { txHash, ... }

注意：

• **范围：**仅支持 ETH ⇄ 代币（用原生 ETH 买入，再卖回 ETH）。买入时会自动将 ETH 包装为 WETH；卖出时会在一笔交易中将 WETH 解包为 ETH。
• **护栏同样适用。**输入金额以美元计价（GeckoTerminal 现货价），并且在签名前根据 maxPerTx／maxPerDay 进行限制——与 xpay swap 使用相同的边界。
• **验证。**确认为 NOXA Fun 发行的代币会标记为已验证；其他代币会标记为 unverified（memecoin 代码并非唯一，建议传入准确的合约地址）。签名前会检查 NOXA 单笔交易／最大钱包转账上限：可能超限的买入会提前报错（而不是在链上回滚），报价也会标记接近上限的交易。
• **Gas：**与 x402 支付不同，交易会从你的钱包广播，因此钱包需要留有少量 Robinhood Chain 上的 ETH 用于支付 Gas。可通过 Across 或 Uniswap bridge 跨链转入。RPC 覆盖项：配置文件中的 rpcs.robinhood。
• 滑点默认为 100 bps（1%）；可按调用覆盖（--slippage-bps），也可按配置文件覆盖（trading.slippageBps）。
• 余额：xpay balance 会列出你的 Robinhood Chain ETH 和持有的所有 ERC-20 代币（通过该链的 Blockscout 浏览器查询），因此在此处买入的代币会自动显示。可通过 XPAY_ROBINHOOD_EXPLORER 覆盖浏览器。
• 这与 xpay swap（Solana／Jupiter）不同。已评估但未采用 GMGN，因为它不支持 Robinhood Chain。

实时 X（Twitter）数据

Agent 无需任何设置即可获取实时 X 账号数据——无需 X 开发者账号，也无需 API 密钥。xpay 按次向 xona 受 x402 限制的代理付款，该代理将 X 的按次付费账单按成本价（不加价）传递：

xpay x user jup_ag          # profile: followers, bio, verification   (~$0.01)
xpay x posts jup_ag         # 10 recent posts + engagement metrics    (~$0.06)

MCP：xpay_x_user / xpay_x_posts——经典工作流是代币尽职调查：xpay_token_find → 检查项目的 X 账号 → 确认可靠后再交换。付款通过常规 x402 流程进行，因此适用防护上限。端点覆盖项：XPAY_XDATA_ENDPOINT。

zauth 仓库安全扫描

通过 zauth 受 x402 付费墙保护的扫描器（合作伙伴集成），扫描任意 git 仓库的代码来源和漏洞——返回 zauth 评分（0–100）以及 Markdown 分析报告。只有启动扫描需要付费（约 $0.05 USDC，使用 Solana 或 Base），且适用防护上限（如果你的配置限制了 allowedHosts，请添加 api.zauth.inc）。状态检查免费且无需钱包：

xpay zauth reposcan https://github.com/owner/repo   # paid: starts the scan (or returns a cached report)
xpay zauth status <sessionToken>                    # free: poll a still-running scan

扫描会立即返回缓存报告，或者返回 { status: "scanning", scanId, sessionToken }；xpay 会自动轮询免费的状态端点，如果扫描耗时超过等待时限，则会将 sessionToken 交给你。后续查询请使用 sessionToken（JWT，有效期约 1 小时），而不是 scanId。

MCP：xpay_zauth_reposcan（付费，轮询最长约 90 秒）/ xpay_zauth_scan_status（免费后续查询）。端点覆盖项：XPAY_ZAUTH_ENDPOINT。

xona 商店商品发现

通过 xona 受 x402 付费墙保护的 /shop/search 端点（合作伙伴集成），用一条自由文本查询即可搜索 Google Shopping、Amazon 和 eBay 上的商品。查询解析器可直接从自然语言中识别价格范围、成色和排序方式；结果会按统一架构规范化、去重并排序。价格随搜索的市场数量变化：搜索全部三个市场约需 $0.02 USDC，搜索部分市场的费用更低（最低 $0.005）。通过常规 x402 流程付款，因此适用防护上限（如果你的配置限制了 allowedHosts，列表中必须包含 api.xona-agent.com）：

xpay shop quote "used thinkpad x1 under $600"    # free: exact price + parsed intent, no wallet
xpay shop search "used thinkpad x1 under $600"   # paid: quotes first, confirms, then searches
xpay shop search "sony wh-1000xm5" --marketplaces amazon,ebay --sort price_asc

shop search 会在请求确认前自动执行免费报价；如果解析器判定查询不是商品搜索，则会拒绝付款（为此类查询付费搜索会产生费用，但返回零条结果）。

MCP：xpay_shop_search（付费）/ xpay_shop_quote（免费预检：查询含义不明确时，Agent 应先获取报价）。MCP 结果会压缩以节省上下文（图片、位置和评分字段会被移除）；xpay shop search --json 会保留完整负载。端点覆盖项：XPAY_SHOP_ENDPOINT。

商城镜头：基于图像的发现

同一个合作伙伴也能根据照片回答“这是什么？哪里能买到？”。向 /shop/lens 提供图像，Google Lens 就会识别商品及其销售零售商，并将结果规范化为与 /shop/search 相同的架构。支持两种模式：identify（默认，约 $0.02 USDC）返回视觉匹配结果及推导出的商品名称；shop（三个平台合计约 $0.04）还会将该名称提交给 Google Shopping、Amazon 和 eBay，以比较价格。

Lens 引擎本身只接受可公开访问的 http(s) URL（SerpAPI 会获取图像；不接受 data URI），因此 MCP 工具要求图像恰好通过以下三种输入之一提供：image_url（原样使用）、image_path（本地文件）或 image_base64（原始数据或 data URI）。本地文件和 base64 数据会先免费上传到 xona 的公共图像托管服务（支持 JPEG/PNG/GIF/WebP，根据魔数识别类型，限制为 25MB），并将托管 URL 作为 hosted_image_url 返回，以便重复使用。这让可上传附件的聊天客户端（Hermes 等）中的图像也能正常使用：传入字节数据，自动转换为公共 URL。

MCP：xpay_shop_lens（付费）/ xpay_shop_lens_quote（免费预检：验证图像 URL 是否可公开访问，并报告准确价格，无需钱包）。传入 image_url 时，Agent 应先询价，因为即使该 URL 最终无法使用，付费接口也会收费。上传图像无需预检，因为托管 URL 始终可访问。如果响应标记图像并非商品照片，重试 mode=shop 也无济于事。

多网络

init 默认配置 Solana 和 Base。可通过 ~/.xpay/<name>/config.json 添加或更改：

{
  "version": 1,
  "networks": ["solana", "base", "arbitrum", "stable"],
  "defaultNetwork": "solana",
  "rpcs": {
    "solana": "https://your-helius-endpoint",
    "base":   "https://your-alchemy-endpoint",
    "stable": "https://rpc.stable.xyz"
  }
}

公共 RPC 适用于开发，但会严格限流。生产部署应配置专用 RPC 端点。

Stable 链

Stable（链 ID 988，Tether/Bitfinex 的支付 L1）作为一等钱包网络受支持。它结算的是 USDT0（位于 0x779Ded0c9e1022225f8E0630b35a9b54bE713736 的 LayerZero OFT，作为 ERC-20 有 6 位小数），而不是 USDC。

同一个派生出的 EVM 密钥也适用于该链，因此无论 networks 中是否包含 stable，每个配置文件都会注册 Stable 签名者。无需重新运行 xpay init 即可使用：

xpay balance                               # includes a stable row: USDT0 + native USDT gas
xpay balance --network stable
xpay discover "image generation" --network stable
xpay transfer 1.5 0xRecipient --network stable          # sends USDT0

注意：

• 支付无需 Gas。 Stable 上的 x402 调用会签署 EIP-3009 transferWithAuthorization，并由 facilitator 广播，因此钱包只需持有 USDT0——无需原生 Gas。直接执行 xpay transfer 时，交易会从你的钱包广播，因此该路径需要少量原生 USDT 支付 Gas。
• EIP-712 域为 USDT0 / 1，而非默认的 USDC。 xpay 不会将其硬编码：域信息会从实时 402 挑战的 extra 中读取，这是唯一可靠的来源（该合约上的 version() 和 eip712Domain() 都会回滚）。
• 两种代币名称相同。 原生 Gas 币是精度为 18 位的 USDT；x402 结算使用的 ERC-20 是精度为 6 位的 USDT0。xpay balance 会分别列出它们。
• 路由会自动处理。 报价为 eip155:988 的 402 会解析到 Stable 签名者；若提供多个链，use() 会将 USDT0 余额与价格进行比较。
• RPC 覆盖：配置文件中的 rpcs.stable（默认值为 https://rpc.stable.xyz）。区块浏览器：stablescan.xyz。

工作原理

• 密钥：每个配置文件使用一个 BIP-39 助记词派生 Solana（m/44'/501'/0'/0'，兼容 Phantom）和 EVM（m/44'/60'/0'/0/0，兼容 MetaMask）密钥对。静态数据使用 scrypt + AES-256-GCM 加密。
• 发现：目录涵盖多个链上的 21k+ x402 端点（Solana、Base、BNB Chain 和其他 EVM 网络），以及 AgenC 市场列表，并从多个独立来源合并而来（使用 Promise.allSettled，因此一个来源故障不会导致发现流程中断）。获取器会遍历每个 API 的分页，根据 Zod schema 验证每个条目，并将数据持久化到 ~/.xpay/cache/，以便重复查找时跳过冷启动获取的开销。（使用 --network / discover({ networks }) 筛选；使用 discover({ sources }) 或 XPAY_DISCOVERY_SOURCES 选择来源。）
• 支付：use() 和 useByUrl() 都会依次执行：护栏检查 → 在正确的网络上调用 signer.pay(USDC) → 添加 X-Payment 标头 → 重试。签名器抽象意味着 Solana SPL 转账和 EVM ERC-20 转账可以使用同一代码路径。AgenC 资源会通过其 agenc-hire 支付方案识别，并改用链上托管流程；调用的仍是同一个 use()，只是支付通道不同。
• 报告：通过 OrbitX402 API 获取全面的 USDC 活动数据（日 / 周 / 月）。链上数据由服务器端解析；xpay 不会发起 RPC 调用，也不会受到速率限制，无需 RPC 密钥。

项目状态

v0.2.14（当前）：

• ✅ CLI：init、accounts、balance、discover、pay、agenc、token、swap、x、zauth、shop、transfer、report、guardrail、mcp
• ✅ SDK：与 CLI 完全一致；提供适用于 Claude / OpenAI / Gemini 的工具导出器
• ✅ 基于 stdio 的 MCP 服务，提供 23 个工具（包括 Bento 意图防火墙）
• ✅ Solana 代币发现 + 原生 Jupiter 兑换（xpay token find、xpay swap）
• ✅ 通过 x402 获取实时 X（Twitter）数据，按成本付费（xpay x user|posts）
• ✅ 通过 x402 扫描 zauth 仓库安全（xpay zauth reposcan）
• ✅ 通过 x402 发现 xona shop 商品（xpay shop search），免费报价预检
• ✅ 定期库存订单（xpay orders）：周期性买入 + 条件式单次订单，由人工批准，支持幂等运行
• ✅ Solana 上的 ERC-8004 商家信任（xpay trust、xpay discover 中的信任线）
• ✅ Solana 上的 RWA 发现（xpay token rwa）：代币化股票 / ETF + USDY，可通过 xpay swap 兑换
• ✅ 支持 Solana + Base 主网，并提供磁盘缓存
• ✅ 可选的 Sana Agent 名片集成（xpay sana link）——额外提供 8 个 sana_* 工具
• ✅ AgenC 市场作为发现来源 + 智能路由的 SOL 托管雇佣（xpay agenc hire|status）

计划中：

• bridge，通过 CCTP（Circle 原生销毁 / 铸造）在 EVM ↔ SVM 之间转移 USDC
• link / unlink，选择加入云同步（审计日志、仪表板）
• 将 Pay 目录 + xona-labs 目录作为额外的发现来源
• xpay agenc accept|rate——无需离开 CLI 即可审核 AgenC 雇佣结果

许可证

MIT——请参阅 LICENSE。