Xenarch — X402 Mcp Server For Ai Agent Payments

Xenarch — 面向 AI Agent 支付的 x402 MCP 服务

Xenarch 是一个非托管型 x402 MCP 服务。AI Agent（Claude、Cursor、LangChain、CrewAI）使用 Base L2 上的 USDC 微支付，为受 HTTP 402 支付门控的 API 和内容付费。无需 API 密钥，无需订阅，也无需留存信用卡信息。Agent 钱包永远不需要 ETH；它持有的唯一代币是 USDC。支付直接在链上结算：Agent 钱包 → 发布者钱包。Xenarch 费率为 0%——资金流中没有 Xenarch 合约。

Xenarch 有何不同

工作原理

1. Discover    xenarch_check_gate("example.com")
               → { gated: true, accepts: [...] }

2. Pay         xenarch_pay("example.com")
               → x402-fetch signs an EIP-3009 USDC transferWithAuthorization
               → Settlement goes on-chain
               → Re-fetches the resource with proof of payment
               → { tx_hash, content }

无需 API 密钥，无需注册。Agent 钱包只需要 USDC——无需 ETH，也无需任何类型的 Gas 币。Xenarch 从不持有资金，Agent 与发布者之间也没有 Xenarch 合约。

MCP 工具

共 29 个工具，分为三组。第 1 组（发现与支付）只需钱包即可使用。第 2 组和第 3 组（控制平面 + 商户）用于管理 Xenarch 账户，需要 SIWE 会话——运行一次 xenarch agent login（参见账户工具身份验证）。

1. 发现与支付——仅需 Agent 钱包

2. Agent 控制平面 — 管理你的支出 Agent（SIWE 会话）

管理操作者 Agent 的限额、范围、紧急停止开关和 API 密钥。具有特权的 （放宽限制）操作需要 confirm: true；收紧限制无需确认。

3. 商户 — 收款（SIWE 会话）

创建和管理付款链接，查看付款和订阅者，并设置商户资料。与控制平面使用同一个 SIWE 会话。

账户工具身份验证

• 支付（第 1 组）需要有资金的 wallet（XENARCH_PRIVATE_KEY）以及控制平面链接（XENARCH_API_TOKEN）——官方 MCP 未配置该令牌时会拒绝付款（XEN-480：未关联的 Agent 没有额度）。此外，还会应用本地的单次调用上限（XENARCH_MAX_PAYMENT_USD，默认 $1），并叠加受管理的单笔／每日／每月上限。
• 控制平面 + 商户（第 2–3 组）需要 SIWE 会话。运行一次 xenarch agent login——它会将有效期为 7 天的 session_token 写入 ~/.xenarch/config.json，MCP 服务会自动读取。会话过期后重新运行，或直接从客户端调用 xenarch_agent_login。
• 设置 XENARCH_API_TOKEN（一个 xa_live_ Agent 密钥），使 xenarch_pay 受受管理的额度／范围限制，并让每笔 MCP 支付都显示在仪表板的收据动态中。仪表板免费——在 dash.xenarch.dev 使用你的 wallet 登录（只需签名，不会发生资金转移），即可设置单笔／每日／每月上限、范围规则、紧急停止开关并查看完整历史记录。未设置该令牌时，xenarch_pay 会拒绝付款（默认关闭），以免未关联的 Agent 在不受限制的情况下结算。注意：用于登录仪表板的 wallet 是你的身份凭证，与 Agent 的本地支出 wallet 分开。

示例响应

{
  "gated": true,
  "gate_id": "7f3a1b2c-9d4e-4a8b-b6f1-2c3d4e5f6a7b",
  "accepts": [
    {
      "scheme": "exact",
      "network": "base",
      "maxAmountRequired": "3000",
      "resource": "https://example.com/article",
      "payTo": "0xabc123...publisher_wallet",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "maxTimeoutSeconds": 60
    }
  ],
  "seller_wallet": "0xabc123...publisher_wallet",
  "network": "base",
  "asset": "USDC"
}

{
  "success": true,
  "gate_id": "7f3a1b2c-9d4e-4a8b-b6f1-2c3d4e5f6a7b",
  "tx_hash": "0xdef456...abc789",
  "seller_wallet": "0xabc123...publisher_wallet",
  "url": "https://example.com/article",
  "wallet": "0x123...your_wallet",
  "content": "...gated content here..."
}

{
  "payments": [
    {
      "domain": "example.com",
      "amount_usd": "0.003",
      "tx_hash": "0xdef456...abc789",
      "paid_at": "2026-04-10T14:35:00Z"
    }
  ],
  "total_spent_usd": "0.003000",
  "count": 1,
  "wallet": "0x123...your_wallet"
}

HTTP 402——终于被 x402 启用的闲置状态码

HTTP 402 Payment Required 是 HTTP 规范中自 1997 年起为机器间支付保留的状态码。数十年来它一直未被使用，因为没有开放协议规定客户端应如何支付 402 响应。

x402 就是这样的协议：服务端返回带有签名价格和支付详情的 HTTP 402，客户端在 Base L2 上签署一笔 USDC 微支付，并在重试请求时附上付款证明。Xenarch 的 MCP 服务会为 AI Agent 自动处理整个流程——读取 402 挑战，通过 x402-fetch 签署支付并重放请求，返回链上交易哈希及受限内容。

了解更多：x402 规范定义了支付握手流程；由 Xenarch 编写的配套开放标准 pay.json，用于在 /.well-known/pay.json 提供机器可读的定价——可以把它看作支付领域的 robots.txt。

使用 HTTP 402 实现 API 变现

Xenarch 是一种基于 HTTP 402 规范构建的 API 变现原语。与需要订阅、仪表板和 API 密钥的 API 网关变现平台（Apigee、Kong、AWS API Gateway）不同，Xenarch 让任何 API 都能按请求收费，无需创建账户或配置密钥——调用方在 Base L2 上支付 USDC，API 验证链上交易后即可授予访问权限。

对于发布方，这意味着：

• 无需集成 Stripe／银行卡处理商
• 无需订阅方案、定价层级或配额仪表板
• 平台不托管余额
• 按请求定价，对人类用户、机器人和 AI Agent 一视同仁
• API 变现实时在链上结算

Python SDK 包含一个只需添加一个装饰器的 FastAPI 中间件；发布方集成请参阅 xenarch-sdks/python。

设置

1. 配置你的 wallet：

mkdir -p ~/.xenarch
cat > ~/.xenarch/wallet.json << 'EOF'
{
  "privateKey": "0xYOUR_PRIVATE_KEY"
}
EOF
chmod 600 ~/.xenarch/wallet.json

2. 添加到 Claude Code：

claude mcp add xenarch -- npx @xenarch/agent-mcp

或者将相同的 JSON 添加到任意 MCP 客户端的配置文件中：

• Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）/ %APPDATA%\Claude\claude_desktop_config.json（Windows）
• Cursor — ~/.cursor/mcp.json（全局）或 .cursor/mcp.json（每个项目）
• Cline（VS Code）— MCP Servers 面板 →“Configure MCP Servers”，或 cline_mcp_settings.json

{
  "mcpServers": {
    "xenarch": {
      "command": "npx",
      "args": ["@xenarch/agent-mcp"],
      "env": {
        "XENARCH_PRIVATE_KEY": "0xYOUR_PRIVATE_KEY",
        "XENARCH_API_TOKEN": "xa_live_…optional, enforces caps/scope"
      }
    }
  }
}

3. 为 wallet 充值 Base 上的 USDC。就这样——不需要 ETH 或其他代币。

4. （可选）若要使用控制平面 + 商户工具，请运行一次 xenarch agent login 来创建 SIWE 会话。

环境变量

控制平面和商家工具不使用环境变量进行身份验证 — 它们会读取 xenarch agent login 写入 ~/.xenarch/config.json 的 SIWE session_token。

示例

请参阅 xenarch-examples，了解可运行的集成示例 — Python Agent、LangChain、CrewAI、Claude Desktop 设置和发布者中间件。

开发

npm install
npm run build

结构

packages/
  shared/    — Payment logic, types, config (reused across servers)
  agent/     — MCP server for AI agents

常见问题

Claude 如何通过 Xenarch 支付 API 费用？ 安装 Xenarch MCP 服务（claude mcp add xenarch -- npx @xenarch/agent-mcp），为其提供钱包，Claude 就能自动通过在 Base L2 上进行 USDC 微支付来处理任何 HTTP 402 响应。

Xenarch 能与 Cursor、LangChain 或 CrewAI 配合使用吗？ 可以。Xenarch 提供 MCP 服务，任何兼容 MCP 的客户端都可以使用 — Claude Code、Claude Desktop、Cursor、Cline、LangChain、CrewAI，以及任何其他支持 Model Context Protocol 的客户端。

发布者可以使用 FastAPI 吗？ 可以，通过 Python SDK（pip install xenarch[fastapi]）实现 — 只需一个装饰器的中间件即可返回包含价格的 HTTP 402，并验证链上付款。请参阅 xenarch-sdks/python。

Xenarch 是托管式服务吗？ 不是。付款通过链上结算，由 Agent 钱包直接向发布者钱包转账 USDC。资金不会经过 Xenarch 基础设施，资金流中也没有 Xenarch 合约。

Agent 需要 ETH 支付 Gas 吗？ 不需要。Agent 钱包只需要 USDC。为其充值 USDC 即可 — 无需 ETH，也无需其他 Gas 币。

手续费是多少？ 从架构上来说，费率为 0%。Xenarch 从不介入资金流 — 没有可收取手续费的 Xenarch 合约。

每次调用的最高付款金额是多少？ 1 美元。

什么是 x402？ x402 是一种用于 HTTP 402 Payment Required 的开放协议。服务端返回带有价格的 402 响应，客户端在 Base L2（或其他受支持的链）上签署 USDC 微支付，然后携带付款证明重试请求。

什么是 HTTP 402？ HTTP 402 Payment Required 是 HTTP 规范中自 1997 年起预留用于机器间付款的状态码。x402 是最终让它得到实际应用的开放协议。

Xenarch 与 Cloudflare Pay-Per-Crawl 相比如何？ Cloudflare Pay-Per-Crawl 仅适用于由 Cloudflare 托管的网站，且采用托管式模式。Xenarch 适用于任何主机，且为非托管式 — 发布者会直接收到链上付款。

Xenarch 与 TollBit 相比如何？ TollBit 专注于企业许可。Xenarch 可自助使用、采用非托管式模式，适用于长尾发布者和任何 AI Agent，无需企业合同。

链接

• 网站：https://xenarch.com
• npm：https://www.npmjs.com/package/@xenarch/agent-mcp
• PyPI：https://pypi.org/project/xenarch/
• Smithery：https://smithery.ai/servers/xenarch/xenarch-mcp
• GitHub：https://github.com/xenarch-ai/xenarch-mcp

许可证

MIT