probe402-check

probe402-check

在你的 Agent 为 x402 端点付款之前，查询 probe402 的公开记录，并在你自己的终端中重新检查已发布的归档头。

三个小工具，一个代码库，Apache-2.0：

• wrapFetchWithCheck — 一个 x402 客户端钩子。封装你的 x402 客户端用于付款的 fetch；每个 402 都会在付款签署前，根据你编写的策略与 probe402 的记录进行核对。它绝不会接触你的签名器，也不会更改付款。
• check_before_paying — 一个 MCP 服务和 CLI。提供你的 Agent 即将付款的 URL。它会读取该路由在 probe402.com 上的免费评级，并回答：该路由在最新一次读取时是否有报价、报价内容是什么、probe402 是否亲自向它付款以及结果评级如何、这次读取相对于该路由自身的更新周期有多旧，以及可引用的地址是什么。如果你提供了当前持有的付款请求，它还会将其与记录的请求进行比较。最终决定由你的 Agent 策略作出。
• verify-head — 从 probe402 的公开 head 表中获取某一天的封存 head，以及 probe402.com 上当天的清单，重新计算 head，并打印 LINKS 或 DOES NOT LINK 及两个摘要。

该工具只读取 probe402.com 的公开信息和一个公开 Git 代码库，不读取其他内容。它不涉及密钥、账户或任何付款。

60 秒上手

Claude Desktop — 将以下内容添加到 claude_desktop_config.json 并重启：

{
  "mcpServers": {
    "probe402-check": {
      "command": "npx",
      "args": ["-y", "probe402-check", "--mcp"]
    }
  }
}

Claude Code — 一行命令：

claude mcp add probe402-check -- npx -y probe402-check --mcp

OpenAI Agents SDK — 将 examples/openai-agents-tool.ts 复制到你的项目中（文件共 40 行；它使用 @openai/agents 中的 tool() 来构建工具，该依赖需要由你自行安装）：

import { Agent } from "@openai/agents";
import { checkTool } from "./openai-agents-tool.ts";

const agent = new Agent({
  name: "buyer",
  instructions: "Before paying any x402 endpoint, call check_before_paying and reason from its verdict.",
  tools: [checkTool],
});

然后按 URL 查询路由：付款前检查 https://datastand.dev/api/data/dev-signals。

上述 npx 命令形式要等软件包发布到 npm 后才能使用；在此之前，请克隆代码库（参见安装），并将命令指向 node /absolute/path/to/probe402-check/dist/cli/mcp.js。

付款时：x402 客户端钩子

MCP 工具会在 Agent 记得查询时给出答案。但 Agent 得先记得查询。钩子不依赖记忆：它位于 x402 客户端用于付款的 fetch 下层，因此每个 402 都会在付款签署前接受检查。

一次导入，三行代码：

import { wrapFetchWithPayment } from "@x402/fetch";
import { wrapFetchWithCheck } from "probe402-check";

const fetchWithPay = wrapFetchWithPayment(wrapFetchWithCheck(fetch), client);

它应放在付款封装的下层，因为 402 就是在那里到达的。x402-fetch（v1 软件包）的组合方式也相同。现在，Agent 发出的任何请求都会在即将产生费用时接受检查：

const response = await fetchWithPay("https://datastand.dev/api/data/dev-signals");

钩子遇到 402 时会：读取挑战内容（通过克隆响应，因此客户端仍会自行读取），就该确切 URL 向 probe402 发起一次请求，获取免费评级；将 402 提供的所有付款方式与 probe402 记录的报价逐一比较；然后应用你的策略。接着，它会原样返回 402，由客户端签署付款；或者抛出 PaymentBlocked，让客户端完全收不到该响应。

它绝不会接触你的签名器、密钥或钱包；不会添加或移除任何标头，也不会更改付款。已经带有付款标头的请求属于客户端自己的重试，会直接放行，因此一次付款只需查询一次。

策略由你决定

工具会报告事实。事实的价值由你判断，因此每次检查都会生成带名称的信号， 而你的策略会将每个名称映射到 allow、warn 或 block。优先级最高的结果生效。以下是 默认设置：

信号	默认值	含义
never-observed-delivering	block	probe402 曾为此路由付款，资金已转出，但没有收到与付款对应的回复
payment-address-differs	block	没有任何一种支付方式使用 probe402 记录的支付地址
quote-differs	warn	当前 402 报价与记录的报价在金额、资产、网络或方案上存在差异
reading-past-cadence	warn	最新读数的时间早于此路由的读取频率
newest-paid-attempt-refused	warn	probe402 最近一次付费尝试在结算前被拒绝——没有付款
settlement-not-corroborated	warn	probe402 持有的每次付费尝试都无法确认资金是否转出
paid-word-not-known	warn	probe402 使用此版本无法分类的词语评定了一笔付款
never-paid	warn	probe402 从未为此路由付款，因此没有付费交付读数
not-quoting	warn	最新读数不是付款报价
no-reading	warn	probe402 持有此路由，但在指定窗口内没有它的读数
not-on-record	warn	probe402 没有此地址的记录
host-not-route	warn	此地址指向一个主机，因此这里不会评定路由
record-unavailable	warn	无法向 probe402 发起查询

只有两种情况会触发阻止，而且都与实际转出的资金有关：probe402 已付款但从未收到回复，以及支付地址与其记录的地址不一致。其他情况只会报告。

probe402 因自身未进行检查而产生的行——never-paid、not-on-record、record-unavailable——会发出 警告，且有意不阻止操作。probe402 未进行检查是关于 probe402 的事实，绝不应成为阻止他人付款的理由。

只需一行即可更改任意行：

const fetchWithPay = wrapFetchWithPayment(
  wrapFetchWithCheck(fetch, {
    policy: { "reading-past-cadence": "block", "never-observed-delivering": "warn" },
    onDecision: (decision) => log.info(decision.line),
  }),
  client,
);

每次决策在执行前都会调用 onDecision，并传入裁定、每个带有各自日期的信号、底层事实、probe402 的完整回答，以及可供引用的地址。除非你传入自定义的 warn，否则 warn 级别的消息会输出到标准错误。

捕获阻止结果

import { PaymentBlocked } from "probe402-check";

try {
  await fetchWithPay(url);
} catch (error) {
  if (error instanceof PaymentBlocked) {
    console.error(error.decision.because);
    console.error(`the record is at ${error.decision.cite}`);
    for (const fact of error.decision.facts) console.error(`${fact.as_of ?? "no date"} ${fact.fact}`);
  }
}

probe402 衡量什么

probe402 是一份关于机器商务的测量记录。它会按固定周期发送 x402 或 MPP 端点所记录的请求，保存返回内容，并依据已发布的规则评定每次读数：是否返回了格式正确的付款报价、报价要求什么、端点是否在未付款的情况下作出回应、是否将 probe402 拒绝为客户端，或是否没有返回任何可用内容。另有一个具名工具会向已公布的一组路由付款，并评定付费请求获得的结果。记录中每个已结束的日期都会封存到一个清单中，并发布其哈希值；每天的清单都会注明前一天的清单，因此记录构成一条任何人都可以重新核验的链。有关探测方式、拒绝执行的操作，以及如何质疑读数，请参阅 probe402.com/method。

此工具返回的所有内容，都是从 probe402 的视角记录的带日期读数。读数说明 probe402 查看路由时，该路由做了什么。它绝不是对端点本身的陈述。

这项检查会询问什么，以及它能和不能告诉 Agent 什么

每次检查会发送一个请求，使用免费等级。对于某个路由，它会返回：

字段	内容
reading	最新观测：评定结果（Quoted、Answered, no quote、Blocked or challenged、Unreachable、Not probed）、观测时间、观测距今时长，以及是否已超过该路由的检查周期
quote	此次观测记录的付款报价：方案、网络、以原子单位表示的金额、资产地址、付款地址、超时时间
window	评定窗口（免费等级为 7 天）：保留的观测、probe402 为自身未检查记录的缺失项 probe402 filed、报价变更次数、各结果的观测次数
paid_delivery	该路由是否在 probe402 的付费面板上、最近一次付费时间、每次尝试的日期和评定用语，以及该记录的读取来源
held_quote	如果你传入了当前持有的 402 报价：哪些字段与记录的报价一致，哪些不同
cite	评定地址，其中包含完整观测及其方法
verdict	一行通俗表述，Agent 可以用于自己的推理

它能告诉你：probe402 上次查看时该路由是否提供报价，以及距今多久；该路由要求支付什么，以及是否与当前向你提出的要求一致；probe402 自己向该路由发送的付费请求是否完成结算并获得答复，以及时间；报价在窗口内变更的频率；在 probe402 未进行检查时，会记录为 probe402 自身的缺失项。

它不能告诉你：此刻端点是否在线（观测带有时间戳，也会标明观测距今时长）；你的付款是否会得到答复（付费交付观测记录的是 probe402 的体验，并标有日期）；任何 probe402 未列出的路由信息，此类情况会返回 not-on-record 并明确说明；也不能告诉你关于运营方的任何信息，除非是路由在线路上的行为。

如果 URL 指向的是主机而非路由，则会返回该主机下的各个路由，每个路由都有自己的评定地址和付费状态，但不会对它们进行评定。

安装

Node 24 或更高版本。

git clone https://github.com/probe402/probe402-check.git
cd probe402-check
npm install      # builds dist/
npm test

CLI

# by the URL you are about to pay
node dist/cli/check.js https://datastand.dev/api/data/dev-signals

# by probe402 endpoint id, comparing the 402 you hold, full JSON
node dist/cli/check.js ep_67bec7d9e13ef185 --pay-to 0x470a1b647d668d3820add26d70c8371557ff4c6b --amount 20000 --network eip155:8453 --json

# a host: its routes, each with a grade address
node dist/cli/check.js https://api.myceliasignal.com

# the readings a verdict stood on, each with its date and the address that holds it
node dist/cli/check.js ep_4d864a69497e351a --explain

执行 npm link（或全局安装）后，相同命令为 probe402-check、probe402-check-mcp 和 probe402-verify-head。

MCP（Claude Desktop、Claude Code、任何 MCP 客户端）

此服务通过 stdio 使用 MCP，并注册一个工具 check_before_paying，参数为 url 和可选的 held_quote（pay_to、amount_atomic、network、asset、scheme）。

{
  "mcpServers": {
    "probe402-check": {
      "command": "npx",
      "args": ["-y", "probe402-check", "--mcp"]
    }
  }
}

如果使用克隆的仓库而非 npm，命令为 node，参数为 /absolute/path/to/probe402-check/dist/cli/mcp.js；examples/claude-mcp-config.json 中包含这种配置。 此软件包已在 MCP 注册表中登记，名称为 io.github.probe402/probe402-check（本仓库中的 server.json）。

同一配置块也见于 examples/claude-mcp-config.json。对于 Claude Code：claude mcp add probe402-check -- node /absolute/path/to/probe402-check/dist/cli/mcp.js。

OpenAI Agents SDK

可将相同的检查用作函数工具，且此软件包无需依赖该 SDK： examples/openai-agents-tool.ts 导出 checkTool，它使用 @openai/agents 中的 tool() 和 zod 构建；你需要在自己的项目中安装它们。

import { Agent, run } from "@openai/agents";
import { checkTool } from "./openai-agents-tool.ts";

const agent = new Agent({
  name: "buyer",
  instructions: "Before paying any x402 endpoint, call check_before_paying and reason from its verdict.",
  tools: [checkTool],
});
await run(agent, "Pay https://datastand.dev/api/data/dev-signals if the record supports it.");

作为库使用

import { checkBeforePaying } from "probe402-check";

const result = await checkBeforePaying({
  url: "https://datastand.dev/api/data/dev-signals",
  held_quote: { pay_to: "0x470a1b647d668d3820add26d70c8371557ff4c6b", amount_atomic: "20000" },
});
console.log(result.verdict);
// datastand.dev GET /api/data/dev-signals was quoting 20000 atomic units of 0x8335…2913 on eip155:8453
// to 0x470a…4c6b as of 2026-09-17T02:32:23.121Z (9.4 hours ago, inside its daily cadence). The quote did
// not change across 7 reading(s) in 7 days. probe402 paid this route on 2026-09-16T17:24:16.130Z and
// graded the result "Settled and answered". The payment request you hold matches the recorded quote on
// pay_to, amount_atomic. Cite https://probe402.com/grade/ep_67bec7d9e13ef185.

result.kind 的值为 route、host 或 not-on-record；字段类型定义在 dist/index.d.ts 中。

演示

一个 Agent 遇到三个 402，支付一个、对一个发出警告、拒绝一个

examples/agent-pays.ts 展示了钩子如何发挥作用。probe402 列表中的三个实时路由都返回 402；钩子会向 probe402 查询每个路由；默认策略会放行一笔付款、发出警告后放行一笔，并拦下一笔。整个过程大约十五秒。

node examples/agent-pays.ts

读取的数据是实时的，但付款不是：该文件和此软件包中都没有钱包、密钥或签名器。x402 客户端是一个十行的替代实现，按已发布客户端的组合方式构成；在真实客户端签名的地方，它会写一行说明自己已签名——因此，这次运行展示的是顺序。

这三个路由分别是：probe402 为其付款且最新一笔付款被评为 已结算并已响应 的路由，会放行；每次付款尝试都在结算前被拒绝的路由，会发出警告并放行；probe402 为其付过两次款、两次都在 Base 上得到佐证但都未收到响应的路由，则会在签名器介入前被拦下。

一个 Agent 在付款前先询问

examples/agent-decides.ts 展示了一个 Agent 即将为 probe402 列表中的三个路由付款。它会发起查询、打印 probe402 的答复，并根据文件顶部写明的策略决定 PAY、HOLD 或 REFUSE：当它持有的 402 响应所列付款地址或金额与记录的报价不同时，拒绝；当读取结果已超出更新周期、不是报价，或 probe402 从未为该路由付款时，暂缓；当路由在更新周期内提供报价、持有的请求与之匹配，且 probe402 最新一笔付款尝试被评为已结算时，付款。

node examples/agent-decides.ts

三个路由中有两个位于 probe402 的已付款面板上，结果为 PAY；第三个在列表中但不在面板上，结果为 HOLD。策略属于这个演示，并非 probe402：读取结果由工具提供，如何决策由你编写。

重新检查一个 head

node dist/cli/verify-head.js 2026-08-21
node dist/cli/verify-head.js 2026-08-21 --next     # also checks that 2026-08-22's manifest names it

2026-08-21
  head on the public copy (25 rows through 2026-09-14): f0bca18bc38e9a7d202bedc12def262cd4a17ec61136ee07f911afc775bafc65
  sha256 of https://probe402.com/chain/2026-08-21 (109954 bytes, trailing newline stripped): f0bca18bc38e9a7d202bedc12def262cd4a17ec61136ee07f911afc775bafc65
  next day 2026-08-22 links back to 2026-08-21 f0bca18b…: NAMES IT
LINKS

它所应用的规则是：probe402.com 在 /chain/<date> 提供的清单是规范 JSON，后面恰好跟一个换行字节；head 是去掉该换行后这些字节的 SHA-256 值。head 表的公开副本位于 github.com/probe402/probe402-chain-heads，每天封存后追加一行，绝不改写。退出代码为：LINKS 时为 0，DOES NOT LINK 时为 1，无法执行检查时为 2（当天尚无对应行，或未提供清单）。

它读取的内容，仅此而已

代码只构造四个地址，不会构造其他地址；每个请求都经过同一个函数，该函数会拒绝任何不在列表中的地址。此仓库中的一项测试会通过额外路径触发拒绝，并扫描源代码，检查是否在其他位置构造了地址。

• https://probe402.com/grade/<endpoint_id> — 路由的免费评级
• https://probe402.com/grade?url=<url> — 按 URL 查询路由或主机的免费评级
• https://probe402.com/chain/<date> — 某个已封存日期的清单
• https://raw.githubusercontent.com/probe402/probe402-chain-heads/main/ARCHIVE-CHAIN.md — 公开 head 表

请求携带用户代理 probe402-check/<version> (+https://github.com/probe402/probe402-check)，以便 probe402 将此工具的调用与其他调用方区分开来。免费评级有每分钟请求量限制；此工具每次检查只发起一个请求。

此仓库不包含 probe402 自身记录、列表、采集器、服务代码或付费工具的任何部分，也不包含任何类型的凭证。它返回的所有内容都已通过公开地址作出响应。

用词

probe402 不允许在其发布的内容中出现两类表述：宣称首创，以及其记录无法支持的结论。这里有一项测试会针对同一组模式检查此 README、源代码和示例中的每个字符串，以及记录答复所产生的每个判定。如果更改触发了测试，就改写措辞；不要放宽匹配模式。

许可证

Apache-2.0。请参阅 LICENSE。名称“probe402”不随代码授权。