probe402-check

probe402-check

Ask probe402's public record about an x402 endpoint before your agent pays it, and re-check a published archive head from your own terminal.

Three small tools, one repository, Apache-2.0:

• `wrapFetchWithCheck` — an x402 client hook. Wrap the fetch your x402 client pays through and every 402 is checked against probe402's record before the payment is signed, against a policy you write. It never touches your signer and never changes the payment.
• `check_before_paying` — an MCP server and a CLI. Give it the URL your agent is about to pay. It reads that route's free grade on probe402.com and answers: was it quoting at the newest reading, quoting what, has probe402 itself paid it and how was the result graded, how old is that reading against the route's own cadence, and the address to cite. It compares the payment request you are holding against the recorded one if you pass it. The decision stays with your agent's policy.
• `verify-head` — fetches one sealed day's head from probe402's public head table and that day's manifest from probe402.com, recomputes the head, and prints LINKS or DOES NOT LINK with both digests.

The tool reads public surfaces of probe402.com and one public git repository, and nothing else. There is no key, no account and no payment anywhere in it.

Use it in 60 seconds

Claude Desktop — add this to claude_desktop_config.json and restart:

{

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

Claude Code — one line:

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

OpenAI Agents SDK — copy examples/openai-agents-tool.ts into your project (it is forty lines, and it builds the tool with tool() from @openai/agents, which you install yourself):

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], });

Then ask for a route by URL: *check https://datastand.dev/api/data/dev-signals before I pay it.*

The npx forms above work once the package is on npm; until then, clone (see Install) and point the command at node /absolute/path/to/probe402-check/dist/cli/mcp.js.

At the payment: the x402 client hook

The MCP tool answers when an agent remembers to ask. An agent has to remember. The hook does not depend on remembering: it sits under the fetch your x402 client pays through, so every 402 is checked before the payment is signed.

One import, three lines:

import { wrapFetchWithPayment } from "@x402/fetch";

import { wrapFetchWithCheck } from "probe402-check";

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

It goes *underneath* the payment wrapper, because that is where the 402 arrives. x402-fetch (the v1 package) composes the same way. Now any request your agent makes is checked at the moment it would cost money:

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

What the hook does on a 402: reads the challenge (through a clone, so your client still reads it itself), asks probe402 about that exact URL — one request, to the free grade — compares every way to pay the 402 offers against the quote probe402 recorded, and applies your policy. Then it hands the 402 back untouched and your client signs, or it throws PaymentBlocked and your client never sees it.

It never touches your signer, your key or your wallet; it adds no header, removes none, and changes no payment. A request that already carries a payment header is your client's own retry and is passed straight through, so one payment costs one question.

The policy is yours

The tool reports facts. What a fact is worth is your call, so each check produces named signals and your policy maps each name to allow, warn or block. The loudest wins. These are the defaults:

Two rows block, and both are about money that was actually sent: payments probe402 made that were never answered, and a payment address that is not the one it recorded. Everything else reports.

A row probe402's own absence produces — never-paid, not-on-record, record-unavailable — warns and does not block on purpose. probe402 not having looked is a fact about probe402, and it should never be the thing that stops somebody's payment.

Change any row with one line:

const fetchWithPay = wrapFetchWithPayment(

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

onDecision is called with every decision before it is acted on: the ruling, every signal with its own date, the facts underneath, probe402's whole answer, and the address to cite. warn lines go to standard error unless you pass a warn of your own.

Catching the block

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}); } }

What probe402 measures

probe402 is a measurement record for machine commerce. On a clock, it sends the request an x402 or MPP endpoint documents, keeps what came back, and grades each reading by a published rule: was a well-formed payment quote returned, what did it ask for, did the endpoint answer without one, did it refuse probe402 as a client, or did nothing usable come back. A separate, named tool pays a published panel of routes and grades what a paid request gets. Each closed day of the record is sealed into a manifest whose hash is published, and each day's manifest names the day before it, so the record forms a chain that anyone can re-check. How it probes, what it refuses to do, and how a reading can be challenged are on probe402.com/method.

Everything this tool returns is a dated reading from probe402's vantage. A reading says what a route did when probe402 looked. It is never a statement about what the endpoint is.

What the check asks, and what it can and cannot tell an agent

One request per check, to the free grade. For a route it returns:

What it can tell you: whether the route was quoting when probe402 last looked and how long ago that was; what it was asking to be paid, and whether that matches what you are being asked now; whether probe402's own paid requests to it settled and got an answer, and when; how often the quote moved in the window; that probe402 did not look, when that is the case, recorded as probe402's own absence.

What it cannot tell you: whether the endpoint is up at this second (the reading has an age, and the age is on it); whether your payment will be answered (a paid-delivery reading is probe402's experience, dated); anything about a route probe402 does not hold on its list, which comes back as not-on-record and says so; anything about the operator beyond what the route did on the wire.

A URL that names a host rather than a route answers the host's routes, each with its own grade address and paid state, and grades none of them.

Install

Node 24 or later.

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

After npm link (or a global install) the same commands are probe402-check, probe402-check-mcp and probe402-verify-head.

MCP (Claude Desktop, Claude Code, any MCP client)

The server speaks MCP over stdio and registers one tool, check_before_paying, with url and an optional held_quote (pay_to, amount_atomic, network, asset, scheme).

{

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

From a clone rather than npm, the command is node and the argument is /absolute/path/to/probe402-check/dist/cli/mcp.js; examples/claude-mcp-config.json holds that form. The package is registered with the MCP registry as io.github.probe402/probe402-check (server.json in this repository).

The same block is in examples/claude-mcp-config.json. For Claude Code: claude mcp add probe402-check -- node /absolute/path/to/probe402-check/dist/cli/mcp.js.

OpenAI Agents SDK

The same check as a function tool, without this package depending on that SDK: examples/openai-agents-tool.ts exports checkTool, built with tool() from @openai/agents and zod, which you install in your own project.

import { Agent, run