x402-verified-payment-fetch

Verify every x402 payment on-chain, from the client

An agent with a wallet can auto-settle any HTTP 402 challenge. The x402 handshake tells it nothing about whether the money actually landed — at the recipient the endpoint advertised, for the amount it advertised, with a non-replayable authorization, for the resource it actually fetched. A facilitator that returns "settled": true is a claim, not a receipt. This skill makes the agent read the chain itself and decide.

Install

npm i github:rezearcher/x402-verified-fetch

(ESM, dependency-free beyond @x402/fetch + a wallet client; keyless public RPC, $0 COGS.)

Use

Same signature as @x402/fetch's wrapFetchWithPayment — it drops into an existing x402-paying agent with one line changed:

import { wrapFetchWithVerifiedPayment } from "@grey-ridge/x402-verified-fetch";

const fetchVerified = wrapFetchWithVerifiedPayment(fetch, walletClient, {
  onMismatch: "throw",        // abort the call if the money mis-settled
  onResourceMismatch: "strict" // abort if a different resource was substituted
});

const res = await fetchVerified("https://some-x402-api.example/paid");

// The verdict rides on a response header as JSON:
const s = JSON.parse(res.headers.get("x-grs-settlement") ?? "{}");
// s.verdict -> "SETTLED" | "UNDERPAID" | "WRONG_RECIPIENT" | "NO_TRANSFER" | "REVERTED" | "UNVERIFIED"
// s.rail    -> "evm" | "svm"
// (or pass { onSettlement: (s) => ... } to get the verdict object via callback)

After the payment settles, the wrapper decodes the PAYMENT-RESPONSE tx, reads it from two independent public RPCs (cross-confirmed, fails closed on disagreement), and reconciles the real on-chain transfer against the endpoint's advertised payTo + amount. SETTLED is the only verdict that means the money landed correctly; anything else is surfaced before the agent trusts the paid response. With onMismatch: "throw" a mis-settled call raises instead of returning a response the agent already paid for.