Verify the requirement before the payment wrapper sees it.

npm install @ifandonlyif/x402-preflight

import { verify, VerifyRequestError } from "@ifandonlyif/x402-preflight";

// Demonstration data, not a request to buy this service.
const endpoint = "https://api.example.com/v1/quote";
const paymentRequired = {
  x402Version: 2,
  accepts: [{
    scheme: "exact",
    network: "eip155:8453",
    asset: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    amount: "1000",
    payTo: "0x1111111111111111111111111111111111111111",
    maxTimeoutSeconds: 60,
  }],
};

// Example application policy, NOT wrapFetch's default policy.
function decide(result) {
  switch (result?.verdict) {
    case "consistent":
      return result.matches_last_observed === true
        ? { state: "consistent", action: "continue_to_own_policy" }
        : { state: "unexpected_result", action: "hold" };
    case "diverged":
      return { state: "diverged", action: "hold" };
    case "stale":
      return {
        state: result.matches_last_observed === true ? "stale_match"
          : result.matches_last_observed === false ? "stale_mismatch"
          : "stale_unknown",
        action: "hold",
      };
    case "unobserved":
      return { state: "unobserved", action: "hold" };
    default:
      return { state: "unexpected_result", action: "hold" };
  }
}

async function preflightDecision(url, requirement) {
  const controller = new AbortController();
  const timer = setTimeout(() => controller.abort(), 3000);
  try {
    const result = await verify(url, requirement, {
      fetch: (input, init) => fetch(input, {
        ...init, signal: controller.signal, redirect: "error",
      }),
    });
    return decide(result);
  } catch (error) {
    if (error instanceof VerifyRequestError) {
      return error.status === 429
        ? { state: "iff_rate_limited", action: "retry_later" }
        : { state: "iff_request_failed", action: "hold", status: error.status };
    }
    return {
      state: controller.signal.aborted ? "iff_timeout" : "iff_unavailable",
      action: "hold",
    };
  } finally {
    clearTimeout(timer);
  }
}

// Log the decision only, not the requirement or raw error body.
console.log(await preflightDecision(endpoint, paymentRequired));
// No payment follows, including when the state is consistent.

import { verify, VerifyRequestError } from "@ifandonlyif/x402-preflight";

export async function shadowPreflight(url, paymentRequired, record = console.info) {
  const controller = new AbortController();
  const timer = setTimeout(() => controller.abort(), 3000);
  let event;
  try {
    const result = await verify(url, paymentRequired, {
      fetch: (input, init) => fetch(input, {
        ...init, signal: controller.signal, redirect: "error",
      }),
    });
    const verdicts = ["consistent", "diverged", "stale", "unobserved"];
    event = {
      mode: "shadow",
      state: verdicts.includes(result?.verdict) ? result.verdict : "unexpected_result",
      matches_last_observed: typeof result?.matches_last_observed === "boolean"
        ? result.matches_last_observed : null,
    };
  } catch (error) {
    event = {
      mode: "shadow",
      state: error instanceof VerifyRequestError && error.status === 429
        ? "iff_rate_limited" : controller.signal.aborted ? "iff_timeout" : "iff_unavailable",
    };
  } finally {
    clearTimeout(timer);
  }
  // Do not expose the URL, requirement, API error body or wallet details.
  try { await record(event); } catch { /* Telemetry must not change policy. */ }
}

// At the point where your client already has the actual requirement:
// void shadowPreflight(exactEndpointUrl, actualPaymentRequired);
// Keep the existing payment decision separate; this helper never authorizes it.

import {
  wrapFetch, X402DivergenceError, X402StaleMismatchError,
} from "@ifandonlyif/x402-preflight";

const preflightFetch = wrapFetch(fetch, {
  onDiverged: "throw",
  onStale: "strict",
  onUnobserved: "warn",
});

export async function fetchWithPreflight(url, init) {
  try {
    return await preflightFetch(url, { ...init, redirect: "error" });
  } catch (error) {
    if (error instanceof X402DivergenceError) {
      console.warn("IFF requirement diverged; payment flow stopped.");
    } else if (error instanceof X402StaleMismatchError) {
      console.warn("IFF stale evidence mismatched; payment flow stopped.");
    }
    // Do not turn a rejected preflight into a bare-fetch/payment retry.
    throw error;
  }
}

// Give fetchWithPreflight to your payment library as its base fetch.
// This snippet alone does not send a request or enable payments.

npx --package=@ifandonlyif/x402-preflight \
  iff-x402-preflight-mcp