Agent Receipt Verify

agent-receipt-verify

Independent verification of payment- and outcome-proof receipts used by AI agents.

Run it, one line

npx -y agent-receipt-verify https://api.bitrefill.com/x402/gift-cards/search

No account, no key, no payment. It tells you whether that endpoint asks for money the way x402 says, and says NOT MEASURED for the levels that need a real settlement instead of failing them.

What it does NOT do: it judges the SHAPE of a receipt, not the honesty of the party that issued it. See CONFORMANCE.md for what is deliberately left unmeasured.

npx -y agent-receipt-verify attempt-identity   # 72 vectors for x402 spec section 5.5

npx -y agent-receipt-verify link-vectors # 14 vectors (13 offline), receipt to settlement npx -y agent-receipt-verify kanon # cross-check against iamonuwa/kanon

What this is

An agent economy has two kinds of receipt. One says who was allowed to act (delegation: UCAN, Authproof, Agent Passport). The other says what was paid for and whether the output matches (settlement and outcome: x402 offer-receipt, INAM countersigned receipts, and the proofs ERC-8004 consumers count).

receipt-commons/receipt-interop covers the first kind. This covers the second.

Use it from an agent: the MCP server

Both checks are also a Model Context Protocol server, so an agent can run them itself instead of a person running a command. It speaks MCP over stdio, protocol version 2025-11-25. The framing, initialize, tools/list and tools/call are implemented directly in src/mcp-server.mjs, with no MCP SDK and no required dependency at all.

Two tools, for the two moments where an agent actually needs an answer.

check_x402_endpoint, before paying. Sends one request and reports which levels of the ladder in CONFORMANCE.md the endpoint reaches. Levels that need a real settlement come back as not measured, never as failed.

link_receipt_to_settlement, after paying. Takes the receipt, the authorization salt and the asset that was paid, resolves the salted commitment against live chain state, and answers linked, not linked, or could not check. Those are three different answers and it never collapses them into two.

Add it to a client:

{

"mcpServers": { "agent-receipt-verify": { "command": "npx", "args": ["-y", "github:holistis/agent-receipt-verify", "mcp"] } } }

No account, no API key, nothing published to npm. If you would rather not run Node from a git ref, there is a Dockerfile:

docker build -t agent-receipt-verify . && docker run -i --rm agent-receipt-verify

The server opens no port and writes nothing to disk. Anything that is not a protocol frame goes to stderr, because stdout belongs to the client. npm test drives the server over real frames in 21 cases, including an unknown tool name, a notification that must not get a reply, and a network it does not know, which has to answer could not check rather than not linked.

ethers is an optional dependency, used for one signature check inside check_x402_endpoint. Without it that single check reports not measured instead of passing, and everything else works unchanged.

Why independent implementations matter

A receipt signed by a seller is a statement by an interested party. It only becomes evidence when someone who was not the signer can recompute it and reach the same conclusion. So every verifier here is written against the published specification, never against the reference implementation's source, and is tested against the vector files published by the protocol's own authors.

If two implementations that have not seen each other's code agree on the same vectors, that is interop. One implementation agreeing with itself proves nothing.

Who has independently taken this up

These are other people stating something about this project, not claims made here. Every line is a link you can open.

• INAM names it in their own verifier documentation as an independent implementation, written from SPEC.md and not from their source, and adds that they have not audited the code and that you should run the vectors yourself: docs/VERIFIER.md
• goun7 carries two measurements from this project in the honest-limits section of his own vector document, with the wording kept as ours: TEST-VEKTOR-KOK-COMPUTE-WORK.md
• iamonuwa decided to link this project's receipt-to-settlement corpus from Kanon as a complementary set with no endorsement, and to keep the two formats compatible: kanon#32
• babyblueviper1 deployed a refusal reported here, where a producer carrying a display name and no key id is rejected before payment settles: erc-8004#99

Two of these carry a caveat worth repeating. The Kanon README link is stated in the issue and is not live yet, and INAM says plainly that they have not audited this code. Both are written that way on purpose. A list of people who looked is worth more when it also says what they did not do.

Status

npm test      # all of the above. No account, no key, and nobody else's server

Node built-ins only, apart from keccak256. Two honest footnotes, because "no network" was not quite true and is the kind of claim this package should not make loosely:

• One case dials a closed port on localhost on purpose, to prove that a dead address reports not-measured instead of crashing the tool. That is a socket, but it leaves the machine alone and reaches no third party.
• Until recently the suite also fetched a live discovery index belonging to someone else, roughly twenty thousand entries, because one test handed an unknown flag to census and census ignored unknown flags and went to work. That flag is now refused, so the suite finishes in about eleven seconds and contacts nobody. A single index round alone used to take over thirty.

Only the settlement link below reaches a real network, and then only a public, read-only RPC.

Confirmed from the other side, which matters more than the table: the author of the x402 specification ran their own implementation, which shares no code with this one, against all three live receipts below and reached the same three settlements, starting from the receipt, the salt and the asset as §5.6.4 requires. Their result and ours are in x402#3827.

Recompute it yourself, without an account

Two of the cross-checks run offline from a single command, so nothing here has to be taken on trust:

npx -y agent-receipt-verify kanon

npx -y agent-receipt-verify beleid npx -y agent-receipt-verify link-vectors

The first checks our EIP-3009 verifier against the ten published vectors of iamonuwa/kanon. The second exists because agreement can hide a question: all ten of those vectors cover underpayment only, so they say nothing about overpayment, or about one nonce reused across two payers. Those are the two open questions in x402#2725, and the command prints exactly where the two possible answers diverge and where they do not.

Five commands read a vector folder (attempt-identity, kanon, beleid, link-vectors and ground --vectors) and check the folder itself first. Each folder has a SHA256SUMS in the sha256sum format. A folder that no longer matches its list (a vector removed, added or changed), a missing or unreadable list, an empty or missing folder, or a vector that cannot be run makes the run exit 1 with a PROBLEM line and a closing FAIL line, instead of printing a count of whatever is left. The hash is taken over the bytes with CRLF line ends turned into LF, and .gitattributes keeps these files LF, so a plain sha256sum -c agrees with this command on a fresh checkout, also on Windows with core.autocrlf=true.

A hash list that sits next to the vectors is not a signature: someone who changes a vector and its line together passes. To rule that out, compare with the published npm package or the git history. A vector you add yourself is reported on purpose; copy the folder elsewhere to experiment. After a deliberate change, node scripts/seal-vectors.mjs rewrites the lists and says what was added, removed or changed. That script is in the repository and not in the npm package.

One scope to know about. The high-s rule and the signer recovery apply to a payer WITHOUT code. USDC picks the check by the payer's code: no code, ecrecover (and a high-s signature reverts); code, ERC-1271 isValidSignature on the payer's contract. So a smart wallet, or an ordinary address with an EIP-7702 delegation, must not be rejected for the shape of its signature. Pass payerHasCode: true in the context and the verifier skips both rules, still applies the window, the amount and the nonce, and never answers VALID: it answers ongemeten, because the signature itself is only checked by a call to the chain. Every answer now carries payerScope (code, no-code or unknown; unknown behaves as no-code and says so). Pointed out on x402#3925 by robertolocatelli81-dev, and it applied to our first version too.

The third runs fourteen vectors for the half AFTER paying: does this receipt belong to that one settlement. Thirteen of them need no network at all; the fourteenth reads the chain and is marked and skipped rather than reported as a failure, because a check that could not run says nothing about the receipt. The same twelve also exist in the field layout of the Kanon vectors, in vectors/settlement-link-kanon, so the two corpora can sit side by side.

Two more commands, both of which measure other people's endpoints rather than our own, and both read-only:

npx -y agent-receipt-verify census [out.json]

npx -y agent-receipt-verify liveness [out.json]

census counts a discovery index per HOST rather than per resource, so a party with three hundred paths does not outweigh three hundred parties with one. liveness takes that census and asks each host whether it still answers 402 today, because a registration in an index is not a promise that the endpoint is alive. Both are slow by design: they pause between requests, because the hosts in that list did not ask to be measured.

Linking a receipt to its settlement

A receipt with an empty transaction field can be matched to a payment only by payer, payee, amount and time. Two payments with the same terms in the same block cannot be told apart at all. Section 5.6 of the x402 offer-receipt extension fixes that with a salted commitment to the ERC-3009 nonce: whoever holds the salt can recompute the link to exactly one settlement, and everyone else learns nothing.

Where section 5.6 lives, because it is not where a reader would assume. Sections 5.6 through 5.6.5 do not exist in the version of the offer-receipt extension on main. They exist only in pull request 3827, which is open. Everything here that cites 5.6 is therefore measured against a proposal, pinned to commit 0e492d6 on that pull request, which is four commits ahead of main and fetchable by anyone. The numbering can still move before it merges. Levels 4 and 5 of the ladder carry this in the p