callx402 MCP server

Payload — 面向 x402、Agent 支付和可编程收入的开发者基础设施。 PAYLOAD → VEYLINE（旗舰产品）→ CALLX402（操作层）→ REVRULE（独立产品）→ 开发者产品 → 免费实用工具。 本仓库：Payload 推出的 callx402 — 通往 Veyline x402 基础设施的通用操作层。

# Payload 推出的 callx402

由 Veyline 提供支持。x402 出问题时，就用 callx402。

callx402 是通往 Veyline x402 基础设施的通用操作层。用通俗语言说出你要做什么（或调用 HTTP 端点），callx402 就会将请求路由到负责实际工作的生产系统：诊断故障的 x402 支付、挽救失败的交易、将 Agent 任务路由到成本最低的可行路径、依据链上证据确认结算状态，或在明确预算和失败即关闭的安全规则下执行操作。

为什么要做它： x402 故障代价高昂，而且情况不透明。结算尝试以 settlement_pending 结束，却没人知道资金是否已转移；钱包误读了 402 响应；重试时又为同一意图签署了第二份授权，导致重复付款。callx402 正是为这些情况而生：diagnose 将故障定位到具体阶段，rescue 对事件进行分诊，resolve 根据证据给出结论，route 找出成本最低的可行路径，execute 则在硬性预算限制下运行。

立即试用（两分钟，无需设置，无需账户）：

npm install -g callx402
callx402 status
callx402 'complete this job for under $1'

status 会输出各子系统的实际连通性报告，无需凭据。 意图行会解析并规划你的请求，然后在执行任何操作之前停止：由于没有接入实时工具端点，它会报告“没有可执行的路由”，因此不会转移任何资金。（请使用单引号：如果使用双引号，shell 会处理掉 $1。）

针对实时 Payload 支付通道的免费只读检查：

curl https://payload-rail.fly.dev/v1/callx402/actions
curl 'https://payload-rail.fly.dev/v1/callx402/quote?action=diagnose'

第一条命令会返回含价格的付费操作目录；第二条会返回一项操作的免费报价。通过结账调用支付通道操作时，每项操作都需付费（参见 https://payloadhq.github.io/agents.json）；这些命令不会产生任何费用。

如果它能帮你省下一次调试，就请为仓库点个星并继续阅读。

MCP 服务：60 秒内完成连接

本仓库提供零依赖、只读的 MCP 服务（mcp/index.js，仅使用 Node 标准库，通过 stdio 传输），公开六个 x402_* 诊断工具。这里的任何内容都不会收费、执行、重试或再次付款。

git clone https://github.com/Payloadhq/callx402
# no npm install needed for the MCP server

将此配置块添加到 MCP 客户端配置中（替换路径），然后重启客户端：

客户端	配置文件
Claude Desktop	claude_desktop_config.json（macOS 上为 ~/Library/Application Support/Claude/，Windows 上为 %APPDATA%\Claude\）
Cursor	~/.cursor/mcp.json（用户范围）或 .cursor/mcp.json（项目范围）
Windsurf	~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "callx402": {
      "command": "node",
      "args": ["/absolute/path/to/callx402/mcp/index.js"]
    }
  }
}

请客户端列出其 MCP 工具：应能看到六个 x402_* 工具。各客户端的说明和原始 stdio 测试握手流程见： integrations/mcp-clients/。

注意：全新安装 npm 后，六个免费的 MCP 工具都可使用对所提供证据进行保守、本地、只读评估的方式作出响应。若没有权威来源，它们不会验证结算、访问私有账本或执行恢复操作。现有已配置的本地／远程子系统集成仍可使用。

关系

• PAYLOAD = 母公司。
• VEYLINE = x402 + MCP 的生产基础设施。旗舰品牌。
• CALLX402 BY PAYLOAD = x402 响应／操作层，由 Veyline 提供支持。 这是进入 Veyline 生产基础设施的入口操作，不是旗舰品牌名称。 这里没有任何内容会更改 Veyline 的名称。

发现路径：搜索 x402 的开发者找到 callx402，使用它，并了解 Veyline。Payload 与 x402 Foundation 没有关联。

功能

• 诊断 x402 或 MCP 故障
• 挽救失败的交易（需要授权）
• 路由付费 Agent 任务，选择成本最低的可行路径
• 根据链上证据解析结算状态
• 在明确的预算范围内执行，并采用失败时关闭的安全规则

行为用语（非商标声明）：

• “需要诊断 x402？用 callx402。”
• “需要挽救一笔交易？用 callx402。”
• “需要路由一项付费 Agent 任务？用 callx402。”
• “需要确定结算状态？用 callx402。”
• “需要在预算范围内执行？用 callx402。”

快速入门

1. 安装

npm install -g callx402

或者在项目中本地安装：npm install callx402（此时二进制文件位于 node_modules/.bin/callx402）。

备用方案，直接从 GitHub 安装：

npm install Payloadhq/callx402

本地开发：

git clone https://github.com/Payloadhq/callx402
cd callx402
npm install
npm link        # exposes the `callx402` command

2. 首次运行：零配置下可用的功能

callx402 status
callx402 'complete this job for under $1'

status 是坦诚的起点：它会逐个子系统报告可达性。 在全新的 npm 安装中，它会显示 0/15 subsystems reachable，这是预期结果（见第 3 步）。意图说明会用通俗语言规划操作，并在执行前停止，因此运行它始终是安全的；请使用单引号，避免 shell 吞掉 $1。

针对在线 Payload 通道的免费只读检查（无需账户或密钥）：

curl https://payload-rail.fly.dev/v1/callx402/actions
curl 'https://payload-rail.fly.dev/v1/callx402/quote?action=diagnose'

这些命令会返回带价格的付费操作目录，以及一项操作的免费报价。调用通道操作时，每项操作均需通过结账付费（机器端入口：https://payloadhq.github.io/agents.json）；这里的内容不会产生任何费用。

3. 可自托管的运行时（高级，可选）

默认情况下，所有子系统命令都会路由到托管通道，无需配置。 如果你更愿意在自己的机器上运行所有内容，请设置 CALLX402_LOCAL=1 并将 CALLX402_V2_ROOT 指向 v2.0.0 目录树（即 x402 Paid API Starter Kit，这是一个独立产品）：

export CALLX402_LOCAL=1
export CALLX402_V2_ROOT=/path/to/x402-paid-api-starter-kit/v2.0.0
callx402 status    # now: 15/15 reachable, 0/15 enabled

如果没有设置 CALLX402_LOCAL=1，这些命令会改用托管通道——这是标准路径，除 npm 包之外无需安装任何内容。

（默认情况下，x402-paid-api-starter-kit/v2.0.0 目录位于 callx402 检出目录旁边。）

子系统默认处于禁用状态；status 会列出启用各子系统所需的标志。设置标志后，运行对应命令：

export PAYLOAD_MCP_DOCTOR=1
callx402 diagnose --target 'https://api.example.com/x402/pay'

更多示例（每个示例都需要启用对应的子系统标志；运行 callx402 status 查看标志名称）：

callx402 rescue --incident inc_123
callx402 route --goal 'fetch 100 product prices for under 0.50 USD'
callx402 resolve --evidence '{"txHash":"0xabc..."}'

请注意使用单引号：目标文本包含 $ 格式的金额，shell 会在双引号内对其进行展开。

本地目录的替代方案：以远程模式连接你自己的 callx402 服务（server/index.js）运行：

export CALLX402_MODE=remote
export CALLX402_REMOTE_URL=http://127.0.0.1:8787

JavaScript SDK

const { callx402 } = require('callx402');

const result = await callx402({
  intent: 'complete this job for under $1',
  maxBudget: 1.00,
  networks: ['base'],
  assets: ['USDC'],
  approvalThreshold: 5.00,
  idempotencyKey: 'job-42',
});

Python SDK

import callx402

result = callx402.callx402(
    intent="complete this job for under $1",
    max_budget=1.00,
    networks=["base"],
    assets=["USDC"],
    approval_threshold=5.00,
    idempotency_key="job-42",
)

HTTP 服务

CALLX402_PORT=8787 node server/index.js
curl -X POST http://127.0.0.1:8787/call \
  -H 'Content-Type: application/json' \
  -d '{"intent":"complete this job for under $1","maxBudget":1.00,"dryRun":true}'

完整 HTTP 接口：server/openapi.yaml（通过 GET /openapi.json 实时提供）。

命令

命令	功能
callx402 "natural language intent"	意图模式：解析、规划、预算检查、路由、执行
callx402 status [--json]	检查子系统可达性和标志状态
callx402 diagnose [--target ...]	诊断 x402 / MCP 故障
callx402 rescue --incident <id>	挽救一笔交易（需通过授权检查）
callx402 route --goal <text>	将付费任务路由到成本最低的可行路径
callx402 resolve --evidence <json|@file>	根据证据解析结算状态
callx402 doctor	运行 MCP doctor 检查
callx402 execute --intent <text> [--max-budget N] [--dry-run]	在明确预算范围内执行
callx402 monitor [--once|--watch]	监控子系统 / 事件状态
callx402 preflight	付费运行前执行预检
callx402 inspect [--query <text>]	检查能力图 / 状态
callx402 evidence <operationId> [--dir <path>]	显示某项操作的已记录证据（只读）——1.0.1 中仅限 MCP / rail，不是已发布的 CLI 命令
callx402 explain <operationId> [--dir <path>]	以通俗语言评估某项操作的状态（只读）——1.0.1 中仅限 MCP / rail，不是已发布的 CLI 命令
callx402 recover <operationId> [--identity <id> | --evidence <json>]	安全恢复决策：RECOVERABLE / SAFE_RETRY / HUMAN_REVIEW（只读）——1.0.1 中仅限 MCP / rail，不是已发布的 CLI 命令
callx402 config list | get <k> | set <k> <v>	管理本地配置

子系统命令（diagnose、rescue、route、resolve、doctor、 monitor、preflight、inspect）需要 v2.0.0 目录树和对应的 功能标志（参见上文“完整子系统命令”）；缺少这些条件时，命令会以状态码 3 退出且不执行任何操作。status、意图模式和 config 无需任何设置即可使用。

执行模式

callx402 开箱即用，有两种模式：

模式	说明	费用	设置	功能
callx402 CLI — Hosted（默认）	将 npm 包作为轻量客户端连接到托管的 Payload Rail	免费报价，之后按操作付费（例如，x402 路径上的 diagnose 为 $0.10，resolve 为 $0.25）	npm install callx402——无需设置	diagnose、resolve、recover、preflight、evidence、explain 等均在服务端执行：先获取免费报价，链上支付仅验证一次，调用经过计量和审计，然后返回结果。
callx402 Runtime — Self-hosted（高级）	CLI + v2.0.0 运行时目录树（设置 CALLX402_LOCAL=1 和 CALLX402_V2_ROOT）	免费	将 CALLX402_V2_ROOT 指向 x402 Paid API Starter Kit v2.0.0 目录树，并启用功能标志	在本机使用你提供的证据进行完整的本地执行。只读分析；绝不签名、重试或转移资金。

只需运行 npm install callx402 即可使用托管模式——无需单独的目录树、 配置或密钥。标准用法永远不需要 v2 目录树。

支付方式

托管付费操作通过 Payload 的签名兑换流程结算，而非使用通用 x402 促进器：

1. 获取该操作的免费报价：付款前即可了解确切价格。
2. 调用操作并读取 x402 v2 402 挑战：Base 上的 USDC、金额以及 payTo 地址。
3. 从你自己的钱包向 payTo 支付报价金额。
4. 使用支付交易哈希，以及来自付款钱包的 EIP-191 签名授权，兑换原始报价。仅有公开交易哈希绝不会授权执行操作。
5. rail 在链上仅验证一次支付，然后返回结果。

完整的兑换合约见 docs/signed-redemption.md。上文所述的免费本地层不会收费，也不会转移资金。

付费单次诊断（无需订阅）

上面的 CLI 和 MCP 工具属于免费本地版：只读诊断，绝不会收费、执行或转移资金。当免费诊断不够用时——你需要按量付费、可审计的调用，并且要求先报价再付款和严格的一次性付款语义——每项操作也可作为付费单次通道操作使用。无需订阅，无需账户：先报价，再主动付款。

付费后可获得：通道授权操作，在链上恰好验证一次付款，按你的组织计量调用，将其记录以供审计，并为订阅用户强制执行 governor／配额规则——随后在服务端执行只读诊断并返回结果。无需本地设置，无需单独的代码树，也无需密钥。通道绝不会伪造执行结果：每个结果都由诊断模块根据你提供的证据生成。

托管式先报价再付款流程：

# 1. Obtain a free quote. No money moves.
curl "https://payload-rail.fly.dev/v1/callx402/quote?action=resolve&path=x402"

# 2. Run the interactive client. Pay explicitly by card or with USDC.
#    For USDC redemption, the paying wallet must EIP-191-sign the exact
#    authorization message displayed by the CLI.
callx402 resolve --evidence '{"txHash":"0x..."}'

# 3. Agents with an external wallet-produced signature can redeem the
#    ORIGINAL canonical quote with a signed authorization file:
callx402 resolve --evidence '{"txHash":"0x..."}' \
  --tx-hash 0xYOUR_SETTLED_PAYMENT_HASH \
  --payer-auth @signed-auth.json --approve

仅有公开交易哈希，绝不能授权操作。签名授权会绑定付款钱包、操作、交易哈希、报价、收款方、网络和请求输入。请将原始 quote_inputs 与签名授权一并保留；请求新报价不会授权较早的付款。**切勿向 Payload 提供私钥、助记词或钱包恢复短语。**目前尚未启用 EIP-1271 合约钱包兑换。Stripe 额度使用单独的兑换流程。

实时费用表：GET https://payload-rail.fly.dev/v1/callx402/actions （响应 "model":"paid on-demand per action; no subscription required"）。 每项操作有两种价格，二者不可互换：银行卡价格是 Stripe 费用表中的费用；x402 通道上的 USDC 价格恰好是该费用除以 20（免费报价端点是 USDC 列的权威来源）。价格并列如下：

操作	银行卡（Stripe）	USDC（x402 通道）
diagnose	$2.00	$0.10
explain	$1.00	$0.05
evidence	$2.00	$0.10
recover	$10.00	$0.50
resolve	$5.00	$0.25
preflight	$3.00	$0.15
settlement_interpretation	$3.00	$0.15
failure_classification	$2.00	$0.10
duplicate_payment_risk	$5.00	$0.25

通道上的 evidence 和 explain 会读取先前已付费调用的结果（请求中需携带该调用的 invocation_id），因此不能在没有先前调用的情况下使用；免费的本地版本则会读取你的本地操作账本。

通道不提供：safe_retry、rescue、monitor 和 execute 仅限本地使用。它们在自托管运行时（v2.0.0 代码树）中运行，不在上方的通道目录中，通道会以 422 HOSTED_ACTION_UNAVAILABLE 拒绝这些操作——没有对应的 Stripe 或 x402 购买途径。对于“这样重试安全吗？”这个问题，可用的只读答复是免费的本地 recover 判定结果。

切勿盲目重试付款来调用付费操作：请先获取报价。

问题到操作对照表（哪些付费操作可处理哪些故障，以及对应的免费 CLI/MCP 路径）：docs/problem-map.md。

公共 RevRule 评估（0.01 USDC）

该 rail 还公开了一个 RevRule 评估端点。这是一个 RevRule 演示，而不是 callx402 诊断操作： POST https://payload-rail.fly.dev/v1/x402/public/evaluate 会根据固定且透明的公共演示图谱评估一项 经济事件（平台获得总额的 5%；创作者获得剩余金额的 70%；如果事件中指定了推荐人，则推荐人获得剩余金额的 25%）， 费用为 0.01 USDC（Base）。

完整且正确的请求体为：

{
  "event": {
    "eventId": "my-event-001",
    "type": "SALE_COMPLETED",
    "rail": "stripe",
    "amountMicros": 100000000,
    "currency": "USD",
    "occurredAt": "2026-10-13T00:00:00.000Z"
  },
  "txHash": "0x<your settled 0.01 USDC payment on Base>"
}

• event.eventId（任意唯一的非空字符串）和 event.rail 都是 必填项，尽管 402 公告中的 bazaar 架构遗漏了这两项。 有效的 rail 值：stripe、ach、x402、manual、stablecoin。
• event.type 必须是以下值之一：SALE_COMPLETED、API_PAYMENT、 LICENSE_PAID、SUBSCRIPTION_PAYMENT、REFERRAL_CONVERTED、 ROYALTY_RECEIVED、CAMPAIGN_MILESTONE、MARKETPLACE_TRANSACTION、 TOUCH。
• 事件会在付款前进行验证：格式错误的请求体会返回 400 INVALID_EVENT，而不是 402（已通过线上验证：上方请求体中 删除 txHash 后会返回 402）。端点会自行填充其余字段—— graphId 固定为公共演示图谱；省略 currency 时默认为 "USD"，省略 occurredAt 时默认为当前时间。
• 省略 txHash 以接收 x402 v2 402 挑战；支付 0.01 USDC， 然后携带哈希重试相同的请求体。每个 txHash 只能使用一次。

集成

适用于 Agent 框架、自动化、MCP 客户端和 x402 促成方的可用接入点—— 均位于 integrations/ 中，并已通过线上 rail 测试：

• LangChain — 9 个工具（integrations/langchain/）：诊断、恢复、 解决、证据、解释、安全重试、重复付款风险、预检， 以及免费的实时费用表
• CrewAI — 以 CrewAI Tools 形式提供相同的操作（integrations/crewai/）
• n8n — 可导入的事件防护工作流（integrations/n8n/）：将事件 映射到 callx402 操作，获取免费的实时报价，有凭证时调用，否则输出付款说明——绝不自动付款
• MCP 客户端 — 为免费的只读 MCP 服务设置 Claude Desktop / Cursor / Windsurf （integrations/mcp-clients/）
• x402 促成方 — settle-guard.js（integrations/facilitator/）： 在重新广播付款前，先根据证据解析结算状态

问题 → 操作映射：docs/problem-map.md。 面向 Agent 的机器入口：https://payloadhq.github.io/agents.json。

资金安全规则

• 结算状态 UNKNOWN 时，绝不自动重试，也绝不再次付款。
• 超出预算的意图将被拒绝，且不会产生任何副作用。
• 审批阈值采用默认拒绝策略。
• 幂等键会去重 — 重复请求会返回原始结果，绝不重新执行。
• 已禁用或无法访问的子系统采用默认拒绝策略 — 绝不伪造成功状态。
• 非托管式 — callx402 负责调度工作；绝不持有资金或私钥。

callx402 不是什么

• 不是旗舰产品名称。产品名称是 Veyline。
• 不是经纪商、谈判方或托管方。它负责调度；绝不持有资金。
• 上述表述是使用说明，并非排他性声明。

链接

• 规范文档：https://payloadhq.github.io/
• Payload 组织资料：https://github.com/Payloadhq/Payloadhq
• Payload 推出的 RevRule（独立产品）：https://github.com/Payloadhq/revrule-console

完整的子系统参考文档：docs/README.md。行为说明：docs/ACTION_LANGUAGE.md。 设计规范：SPEC.md。

许可证

MIT。请参阅 LICENSE。

---

更多 Payload 内容 · payloadhq.github.io · 所有 Payload 仓库

相关项目：x402-manifest-check · x402-observatory · flow-agentic-demo