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:

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

**Claude Code** — one line:

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

**OpenAI Agents SDK** — copy [`examples/openai-agents-tool.ts`](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):

```ts
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](#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:

```ts
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:

```ts
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:

| Signal | Default | What it means |
|---|---|---|
| `never-observed-delivering` | **block** | probe402 paid this route, money moved, and no payment of its own came back with an answer |
| `payment-address-differs` | **block** | no way to pay this 402 names the payment address probe402 recorded |
| `quote-differs` | warn | the live 402 differs from the recorded quote on amount, asset, network or scheme |
| `reading-past-cadence` | warn | the newest reading is older than the cadence this route is read on |
| `newest-paid-attempt-refused` | warn | probe402's newest paid attempt was refused before settlement — nothing was paid |
| `settlement-not-corroborated` | warn | every paid attempt probe402 holds leaves it unable to say whether money moved |
| `paid-word-not-known` | warn | probe402 graded a payment with a word this version does not classify |
| `never-paid` | warn | probe402 has not paid this route, so it holds no paid-delivery reading |
| `not-quoting` | warn | the newest reading was not a payment quote |
| `no-reading` | warn | probe402 holds the route and has no reading of it in the window |
| `not-on-record` | warn | probe402 holds no record of this address |
| `host-not-route` | warn | the address names a host, so nothing here grades a route |
| `record-unavailable` | warn | probe402 could not be asked |

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:

```ts
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

```ts
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](https://probe402.com) 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](https://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:

| Field | What it holds |
|---|---|
| `reading` | The newest observation: the graded outcome (`Quoted`, `Answered, no quote`, `Blocked or challenged`, `Unreachable`, `Not probed`), when it was taken, its age, and whether that age is past the cadence the route is read on |
| `quote` | The recorded payment quote at that reading: scheme, network, amount in atomic units, asset address, payment address, timeout |
| `window` | The graded window (seven days on the free grade): readings held, absences probe402 filed for its own misses, how many times the quote changed, readings by outcome |
| `paid_delivery` | Whether the route is on probe402's paid panel, when it was last paid, every attempt with its date and graded word, and where that record was read from |
| `held_quote` | If you passed the 402 you are holding: which fields match the recorded quote and which differ |
| `cite` | The grade address, which carries the whole reading and its method |
| `verdict` | One line in plain words your agent can put in its own reasoning |

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.