x402-safe-fetch 0.12.0 → 0.14.0

package/README.md

@@ -86,6 +86,32 @@ const safeFetch = createSafeFetch({
 
 When a seller offers both, the exact option is paid. The preflight and the budget apply the same way.
 
+## Already have an x402 client? One line
+
+If your agent already pays with the official x402 client (`x402Client` from `@x402/core`, used by `@x402/fetch`, `@x402/axios` and the other transports), you don't have to switch to `safeFetch`. Add the preflight as a hook, and every payment that client makes is checked first:
+
+```js
+import { x402Client } from "@x402/core/client";
+import { wrapFetchWithPayment } from "@x402/fetch";
+import { doctorPreflight } from "x402-safe-fetch/hook";
+
+const client = new x402Client();
+// … register your schemes as before (registerExactEvmScheme(client, { signer }), …)
+client.onBeforePaymentCreation(doctorPreflight({ client, maxUsd: 0.05 }));
+
+const fetchWithPayment = wrapFetchWithPayment(fetch, client); // unchanged
+```
+
+Before the client signs a payment, the hook asks x402 Doctor ($0.001, paid by the same client, or 1 prepaid credit with `creditKey`). Then:
+
+- `no_go`: the payment is aborted (`Payment creation aborted: x402 Doctor: …`). Nothing is signed.
+- `caution`: aborted, unless `onCaution` is `"pay"` or your function says yes.
+- `go`: the payment goes ahead. With `onIncomplete: "stop"`, a `go` whose `checks_complete` is false is aborted too.
+
+The verdict is signed by Doctor and checked, and reused while the endpoint asks the same thing (same payTo, amount, token and network). Doctor's own 402 for the preflight is never checked again and is paid only up to $0.002. Options: `client`, `pay` or `creditKey` (how the preflight is paid), `maxUsd`, `method`, `onCaution`, `onIncomplete`, `onError` (`"stop"` by default), `trusted`, `onPreflight`, `cacheMs`.
+
+The hook can't see your request, only the 402, so Doctor checks the endpoint with `method` (GET by default; it tries the other method too).
+
 ## Options
 
 | Option | Default | |
@@ -103,11 +129,29 @@ When a seller offers both, the exact option is paid. The preflight and the budge
 | `diagnoseOnFailure` | `false` | When a payment still fails, buy a $0.01 Doctor diagnosis of why (see below) |
 | `shareOutcomes` | `false` | After paying, tell Doctor whether the payment worked, so its later preflights learn from it; when not paying, tell it why (see below) |
 | `tellSellers` | `false` | When not paying, tell the seller itself why, if its 402 takes refusals (draft refusal extension, see below) |
+| `onPaidError` | `"stop"` | The same request was paid before and answered without delivering: `"stop"` throws code `paid_no_delivery`, `"pay"` pays again, or a function decides (see below) |
+| `paidErrorMs` | 30 minutes | How long such a request stays blocked |
 | `onDiagnosis` | | `(report, { url, method, status, error }) => void`, e.g. for logging or alerting |
 | `authority` | the Fizzl payout wallet | Wallet whose certificates also make a signer trusted (key rotation); `null` accepts only `doctorSigners` |
 
 The preflight itself is capped at $0.002 and paid with the same schemes. `receiptOf(response)` returns the payment receipt (transaction hash) of a paid response.
 
+## Never paid twice for nothing
+
+A seller can take the payment and still answer with an error: a 405, a 500, or another 402 asking to pay again. Paying the same request again then usually costs a second payment for nothing. In the agent exam at [exam.fizzl.eu](https://exam.fizzl.eu) this was the most common loss: every model we examined did it at least once, with or without a preflight, because a preflight only sees the 402 before paying.
+
+So safe-fetch remembers each paid request (method, URL and body) whose paid answer was not a success. Calling that same request again within 30 minutes throws `SafePayError` with code `paid_no_delivery` (and `error.earlier`: when it was paid and what it was answered with), without paying and without buying another preflight. A different request is not affected, and a success clears it.
+
+```js
+const safeFetch = createSafeFetch({
+  register,
+  onPaidError: "stop", // default; "pay" pays again, or a function (earlier, { url, method }) => boolean decides
+  paidErrorMs: 30 * 60 * 1000, // how long such a request stays blocked
+});
+```
+
+The guard is also exported on its own (`createPaidGuard`, no dependencies) for agents that pay through another client.
+
 ## When a payment still fails
 
 Sometimes the preflight says `go` and the payment still fails: the endpoint answers 402 again, or paying throws (a facilitator that rejects it, a wrong network). With `diagnoseOnFailure: true`, safe-fetch then buys one **$0.01** [x402 Doctor diagnosis](https://github.com/Fizzl13/x402-doctor#paid-api-for-agents-x402) of that endpoint: every check of its payment flow, with what is wrong and how to fix it.

package/hook.d.ts

@@ -0,0 +1,34 @@
+import type { Preflight } from "./index.js";
+
+export interface DoctorPreflightOptions {
+  /** The x402Client the hook is added to: it pays the $0.001 preflight too (Doctor's own 402 is skipped by the hook). */
+  client?: unknown;
+  /** Or a fetch that pays x402, for the preflight. */
+  pay?: typeof fetch;
+  /** Or prepaid x402 Doctor credits (xdc_…): tried first, then pay or client. */
+  creditKey?: string;
+  /** Your budget per call in USD: Doctor says no_go above it. */
+  maxUsd?: number | string;
+  /** How your calls reach the endpoints. Default "GET"; Doctor tries the other method too. */
+  method?: "GET" | "POST";
+  /** On a caution verdict. Default "stop". */
+  onCaution?: "stop" | "pay" | ((preflight: Preflight) => boolean | Promise<boolean>);
+  /** On a go whose checks_complete is false. Default "pay". */
+  onIncomplete?: "pay" | "stop" | ((preflight: Preflight) => boolean | Promise<boolean>);
+  /** When Doctor can't be asked. Default "stop". */
+  onError?: "stop" | "pay";
+  /** Hosts paid without a preflight. */
+  trusted?: string[];
+  onPreflight?: (preflight: Preflight, info: { url: string; cached: boolean }) => void;
+  /** How long a verdict is reused while the endpoint asks the same thing, in ms. Default 1 hour (10 minutes for an incomplete one). */
+  cacheMs?: number;
+  doctorUrl?: string;
+  verifyReceipts?: "require" | "off";
+  doctorSigners?: string[];
+  authority?: string | null;
+  fetch?: typeof fetch;
+  now?: () => number;
+}
+
+/** A BeforePaymentCreationHook for any @x402/core x402Client: client.onBeforePaymentCreation(doctorPreflight({ client })). */
+export function doctorPreflight(options?: DoctorPreflightOptions): (context: { paymentRequired: unknown; selectedRequirements: unknown }) => Promise<void | { abort: true; reason: string }>;

package/hook.js

@@ -0,0 +1,145 @@
+// x402 Doctor's pre-payment check as a hook for any x402 client (@x402/core x402Client, which @x402/fetch,
+// @x402/axios and the other x402 transports use): one line, and every payment that client makes is checked first.
+//
+//   import { doctorPreflight } from "x402-safe-fetch/hook";
+//   client.onBeforePaymentCreation(doctorPreflight({ client }));
+//
+// Before the client signs a payment, the hook asks Doctor (GET /api/v1/preflight, $0.001, or 1 prepaid credit)
+// whether the endpoint is safe to pay: no_go stops the payment, caution stops it unless onCaution says otherwise,
+// go lets it through. The verdict is signed by Doctor and checked; it is reused while the endpoint asks the same
+// thing. Doctor's own 402 (for the preflight itself) is never checked again, and is paid only up to $0.002.
+import { wrapFetchWithPayment } from "@x402/fetch";
+import { DOCTOR_URL, preflightUrl, VERSION } from "./index.js";
+import { verifyReceipt, DOCTOR_SIGNERS, AUTHORITY } from "./receipt.js";
+
+const CREDIT_HEADER = "x-credit-key";
+const CREDIT_KEY = /^xdc_[A-Za-z0-9_-]{43}$/;
+// The preflight costs $0.001; its own payment is refused above twice that (USDC and the other dollar tokens Doctor
+// takes have 6 decimals; RLUSD on the XRP Ledger is a decimal amount).
+const PREFLIGHT_MAX_ATOMIC = 2000n;
+const PREFLIGHT_MAX_DECIMAL = 0.002;
+
+const hostOf = (u) => { try { return new URL(u).host; } catch { return null; } };
+const abort = (reason) => ({ abort: true, reason: String(reason).slice(0, 300) });
+
+// Within the preflight's price: atomic units (EVM, Solana, Algorand, Stellar) or a decimal amount (XRPL RLUSD).
+function withinPreflightPrice(amount) {
+  const s = String(amount ?? "");
+  if (/^\d+$/.test(s)) return BigInt(s) <= PREFLIGHT_MAX_ATOMIC;
+  const n = Number(s);
+  return Number.isFinite(n) && n > 0 && n <= PREFLIGHT_MAX_DECIMAL;
+}
+
+/**
+ * @param {object} options
+ * @param {object} [options.client]  the x402Client the hook is added to: it pays the preflight too (the hook skips Doctor's own 402)
+ * @param {typeof fetch} [options.pay]  or a fetch that pays x402, for the preflight
+ * @param {string} [options.creditKey]  or prepaid Doctor credits (xdc_…): tried first, then pay or client
+ * @param {number|string} [options.maxUsd]  your budget per call: Doctor says no_go above it
+ * @param {"GET"|"POST"} [options.method]  how your calls reach the endpoints (Doctor tries the other method too)
+ * @param {"stop"|"pay"|((preflight: object) => boolean|Promise<boolean>)} [options.onCaution]  default "stop"
+ * @param {"pay"|"stop"|((preflight: object) => boolean|Promise<boolean>)} [options.onIncomplete]  a go whose checks_complete is false; default "pay"
+ * @param {"stop"|"pay"} [options.onError]  when Doctor can't be asked; default "stop"
+ * @param {string[]} [options.trusted]  hosts paid without a preflight
+ * @param {(preflight: object, info: {url: string, cached: boolean}) => void} [options.onPreflight]
+ * @param {number} [options.cacheMs]  how long a verdict is reused while the endpoint asks the same thing (default 1 hour)
+ * @param {"require"|"off"} [options.verifyReceipts]  check Doctor's signature (default "require")
+ * @returns {(context: {paymentRequired: object, selectedRequirements: object}) => Promise<void|{abort: true, reason: string}>}
+ */
+export function doctorPreflight({
+  client,
+  pay,
+  creditKey,
+  maxUsd,
+  method = "GET",
+  onCaution = "stop",
+  onIncomplete = "pay",
+  onError = "stop",
+  trusted = [],
+  onPreflight,
+  cacheMs = 60 * 60 * 1000,
+  doctorUrl = DOCTOR_URL,
+  verifyReceipts = "require",
+  doctorSigners = DOCTOR_SIGNERS,
+  authority = AUTHORITY,
+  fetch: plainFetch = globalThis.fetch,
+  now = Date.now,
+} = {}) {
+  if (!client && typeof pay !== "function" && !creditKey) throw new TypeError("doctorPreflight needs a way to pay the $0.001 preflight: client, pay or creditKey");
+  if (creditKey !== undefined && !CREDIT_KEY.test(String(creditKey))) throw new TypeError("creditKey must be an x402 Doctor credit key (xdc_…)");
+  if (!["stop", "pay"].includes(onCaution) && typeof onCaution !== "function") throw new TypeError('onCaution must be "stop", "pay" or a function');
+  if (!["pay", "stop"].includes(onIncomplete) && typeof onIncomplete !== "function") throw new TypeError('onIncomplete must be "pay", "stop" or a function');
+  if (!["stop", "pay"].includes(onError)) throw new TypeError('onError must be "stop" or "pay"');
+  if (!["require", "off"].includes(verifyReceipts)) throw new TypeError('verifyReceipts must be "require" or "off"');
+  const doctorHost = hostOf(doctorUrl);
+  const trustedHosts = new Set(trusted.map((t) => hostOf(/^https?:/.test(t) ? t : `https://${t}`)).filter(Boolean));
+  let payingFetch = typeof pay === "function" ? pay : null;
+  const payer = () => (payingFetch ??= client ? wrapFetchWithPayment(plainFetch, client) : null);
+  const headers = { accept: "application/json", "user-agent": `x402-safe-fetch/${VERSION} (hook)` };
+  const verdicts = new Map();
+
+  async function ask(url, network) {
+    const pfUrl = preflightUrl(url, { method, maxUsd, network, doctorUrl });
+    let res = null;
+    if (creditKey) {
+      res = await plainFetch(pfUrl, { headers: { ...headers, [CREDIT_HEADER]: creditKey } });
+      if (res.status === 402) res = null; // credits used up or unknown: pay instead, if we can
+    }
+    if (!res) {
+      const f = payer();
+      if (!f) throw new Error("no prepaid credits left and nothing to pay the preflight with");
+      res = await f(pfUrl, { headers });
+    }
+    const preflight = await res.json().catch(() => null);
+    if (!res.ok || !preflight?.verdict) throw new Error(`preflight answered HTTP ${res.status}`);
+    if (verifyReceipts === "require") {
+      const input = Object.fromEntries(new URL(pfUrl).searchParams);
+      const check = verifyReceipt(preflight, { signers: doctorSigners, route: "GET /api/v1/preflight", input, authority, service: "x402-doctor" });
+      if (!check.valid) throw new Error(`preflight not trusted (${check.reason})`);
+    }
+    return preflight;
+  }
+
+  return async function doctorPreflightHook({ paymentRequired, selectedRequirements } = {}) {
+    const url = paymentRequired?.resource?.url;
+    const host = hostOf(url);
+    // Doctor's own 402, for the preflight we are paying: never checked again, and never more than its price.
+    if (host && host === doctorHost) {
+      return withinPreflightPrice(selectedRequirements?.amount ?? selectedRequirements?.maxAmountRequired) ? undefined : abort("x402 Doctor's preflight asked more than $0.002");
+    }
+    if (!url || (host && trustedHosts.has(host))) return undefined;
+
+    const r = selectedRequirements || {};
+    const key = JSON.stringify([url, r.network, r.asset, String(r.amount ?? r.maxAmountRequired ?? ""), r.payTo]);
+    const hit = verdicts.get(key);
+    const ttl = hit?.preflight?.checks_complete === false ? Math.min(cacheMs, 10 * 60 * 1000) : cacheMs;
+    let preflight;
+    let cached = false;
+    if (hit && hit.at + ttl > now()) {
+      preflight = hit.preflight;
+      cached = true;
+    } else {
+      try {
+        preflight = await ask(url, r.network);
+      } catch (err) {
+        return onError === "pay" ? undefined : abort(`x402 Doctor's preflight failed (${err.message}); not paid`);
+      }
+      verdicts.set(key, { preflight, at: now() });
+      if (verdicts.size > 1000) verdicts.delete(verdicts.keys().next().value);
+    }
+    onPreflight?.(preflight, { url, cached });
+
+    const why = preflight.summary || preflight.verdict;
+    if (preflight.verdict === "no_go") return abort(`x402 Doctor: ${why}`);
+    if (preflight.verdict === "caution") {
+      const ok = onCaution === "pay" || (typeof onCaution === "function" && (await onCaution(preflight)) === true);
+      return ok ? undefined : abort(`x402 Doctor (caution): ${why}`);
+    }
+    if (preflight.verdict !== "go") return abort(`x402 Doctor: unknown verdict ${preflight.verdict}`);
+    if (preflight.checks_complete === false && onIncomplete !== "pay") {
+      const ok = typeof onIncomplete === "function" && (await onIncomplete(preflight)) === true;
+      if (!ok) return abort("x402 Doctor: go, but not every check ran; try again in a few minutes");
+    }
+    return undefined;
+  };
+}

package/index.d.ts

@@ -41,9 +41,11 @@ export interface Diagnosis {
 }
 
 export declare class SafePayError extends Error {
-  code: "no_go" | "caution" | "incomplete" | "preflight_failed" | "bad_receipt" | "no_option";
+  code: "no_go" | "caution" | "incomplete" | "preflight_failed" | "bad_receipt" | "no_option" | "paid_no_delivery";
   preflight: Preflight | null;
   url: string | null;
+  /** With code "paid_no_delivery": when the same request was paid before, and what it was answered with. */
+  earlier?: { at: number; status: number };
   /** Set when diagnoseOnFailure diagnosed a payment that failed. */
   diagnosis?: Diagnosis;
 }
@@ -78,6 +80,10 @@ export interface SafeFetchOptions {
   shareOutcomes?: boolean;
   /** When not paying, tell the seller why if its 402 names a refusal url on its own site (draft x402-foundation/x402#4087). Default false. */
   tellSellers?: boolean;
+  /** The same request (method, URL, body) was paid before and answered without delivering (an error, or another 402): "stop" (default) throws code "paid_no_delivery" without paying, "pay" pays again, a function decides. */
+  onPaidError?: "stop" | "pay" | ((earlier: { at: number; status: number }, info: { url: string; method: string }) => boolean | Promise<boolean>);
+  /** How long such a request stays blocked, in ms. Default 30 minutes. A success clears it. */
+  paidErrorMs?: number;
   fetch?: typeof globalThis.fetch;
   /** Advanced/testing: a paying fetch capped at `cap` (e.g. "$0.05"). */
   createPayingFetch?: (cap: string) => typeof globalThis.fetch;
@@ -102,3 +108,13 @@ export declare function verifyReceipt(body: unknown, options?: { signers?: strin
 
 /** The reason code reported with a refused outcome: the preflight's first reason at its verdict's level. */
 export function refusalReason(preflight: { verdict?: string; reasons?: { level?: string; code?: string }[] }): string;
+
+/** Remembers paid requests that weren't delivered, so the same request isn't paid again (used by createSafeFetch; usable on its own). */
+export declare function createPaidGuard(options?: { windowMs?: number; now?: () => number }): {
+  blocked(url: string, init?: { method?: string; body?: unknown }): { at: number; status: number } | null;
+  record(url: string, init: { method?: string; body?: unknown } | undefined, status: number): void;
+  clear(url: string, init?: { method?: string; body?: unknown }): void;
+};
+export declare function purchaseKey(url: string, init?: { method?: string; body?: unknown }): string;
+export declare function paidTwiceMessage(url: string, earlier: { at: number; status: number }): string;
+export declare const PAID_ERROR_MS: number;

package/index.js

@@ -24,6 +24,10 @@
 // draft refusal extension, x402-foundation/x402#4087): the ready report from Doctor's preflight (reason code and the
 // hash of the refused offer; no query, no keys, nothing about the buyer or this client), once a day per endpoint and
 // reason. A screening_hit isn't sent: the draft takes it only signed. Off by default.
+// A paid request answered without delivery (an error, or another 402) is never paid again on its own: the same
+// method, URL and body within paidErrorMs throws SafePayError code "paid_no_delivery" (onPaidError "stop", the
+// default). The most common loss in the agent exam (exam.fizzl.eu) was paying again after a seller took the payment
+// and answered with an error; a preflight can't see that, it only reads the 402 before paying (paid-guard.js).
 // Every preflight must carry Doctor's signed receipt for exactly this request
 // (endpoint, method, budget, network), checked against Doctor's pinned signer:
 // a missing, changed or forged verdict is never a payment (receipt.js).
@@ -35,13 +39,15 @@
 
 import { wrapFetchWithPayment, x402Client, decodePaymentResponseHeader } from "@x402/fetch";
 import { verifyReceipt, DOCTOR_SIGNERS, AUTHORITY } from "./receipt.js";
+import { createPaidGuard, paidTwiceMessage, PAID_ERROR_MS } from "./paid-guard.js";
 
+export { createPaidGuard, purchaseKey, paidTwiceMessage, PAID_ERROR_MS } from "./paid-guard.js";
 export { verifyReceipt, recoverSigner, canonicalJson, inputHash, certMessage, DOCTOR_SIGNERS, AUTHORITY } from "./receipt.js";
 
 export const DOCTOR_URL = "https://x402-doctor.fizzl.eu";
 export const PREFLIGHT_CAP = "$0.002"; // the preflight costs $0.001; never more than twice that
 export const DIAGNOSE_CAP = "$0.02"; // the diagnosis costs $0.01; never more than twice that
-export const VERSION = "0.12.0";
+export const VERSION = "0.14.0";
 // Doctor sees which calls come from this package (in its usage counts), nothing more.
 const DOCTOR_HEADERS = { accept: "application/json", "user-agent": `x402-safe-fetch/${VERSION}` };
 export const BASE = "eip155:8453";
@@ -141,13 +147,14 @@ export function refusalReason(preflight) {
 }
 
 export class SafePayError extends Error {
-  /** code: "no_go" | "caution" | "preflight_failed" | "bad_receipt" | "no_option" */
-  constructor(message, { code, preflight = null, url = null } = {}) {
+  /** code: "no_go" | "caution" | "incomplete" | "preflight_failed" | "bad_receipt" | "no_option" | "paid_no_delivery" */
+  constructor(message, { code, preflight = null, url = null, earlier } = {}) {
     super(message);
     this.name = "SafePayError";
     this.code = code;
     this.preflight = preflight;
     this.url = url;
+    if (earlier) this.earlier = earlier;
   }
 }
 
@@ -244,6 +251,10 @@ function sameSite(a, b) {
  * @param {(report: object, info: {url: string, method: string, status: number|null, error: Error|null}) => void} [options.onDiagnosis]
  * @param {boolean} [options.shareOutcomes]  after paying, tell Doctor whether the payment worked (default false)
  * @param {boolean} [options.tellSellers]  when not paying, tell the seller why if its 402 takes refusals (default false)
+ * @param {"stop"|"pay"|((earlier: {at: number, status: number}, info: {url: string, method: string}) => boolean|Promise<boolean>)} [options.onPaidError]
+ *   the same request was paid before and answered without delivering: "stop" (default) throws code "paid_no_delivery",
+ *   "pay" pays again, a function decides
+ * @param {number} [options.paidErrorMs]  how long such a request stays blocked (default 30 minutes)
  * @param {(cap: string) => typeof fetch} [options.createPayingFetch]  advanced/testing: a paying fetch capped at `cap`
  * @param {() => number} [options.now]
  */
@@ -264,6 +275,8 @@ export function createSafeFetch({
   onDiagnosis,
   shareOutcomes = false,
   tellSellers = false,
+  onPaidError = "stop",
+  paidErrorMs = PAID_ERROR_MS,
   fetch: baseFetch = globalThis.fetch,
   createPayingFetch,
   now = Date.now,
@@ -279,6 +292,10 @@ export function createSafeFetch({
   if (!["pay", "stop"].includes(onIncomplete) && typeof onIncomplete !== "function") {
     throw new TypeError('onIncomplete must be "pay", "stop" or a function');
   }
+  if (!["stop", "pay"].includes(onPaidError) && typeof onPaidError !== "function") {
+    throw new TypeError('onPaidError must be "stop", "pay" or a function');
+  }
+  const paidGuard = createPaidGuard({ windowMs: paidErrorMs, now });
   if (!["require", "off"].includes(verifyReceipts)) throw new TypeError('verifyReceipts must be "require" or "off"');
   const trustedHosts = new Set(trusted.map(hostOf).filter(Boolean));
 
@@ -422,7 +439,13 @@ export function createSafeFetch({
     tellSeller(url, preflight);
   }
 
+  // Every endpoint payment goes through here: what it was answered with is remembered for the paid-twice guard.
   async function payAndCheck(url, init, method) {
+    const res = await payAndDiagnose(url, init, method);
+    paidGuard.record(url, { method, body: init.body }, res.status);
+    return res;
+  }
+  async function payAndDiagnose(url, init, method) {
     if (!diagnoseOnFailure) return payEndpoint(url, init);
     let res;
     try {
@@ -451,6 +474,16 @@ export function createSafeFetch({
     const probe = await baseFetch(url, init);
     if (probe.status !== 402) return probe;
 
+    // Paid before and not delivered: not paid again (and no preflight bought) unless onPaidError says so.
+    const earlier = paidGuard.blocked(url, { method, body: init.body });
+    if (earlier && onPaidError !== "pay") {
+      const again = typeof onPaidError === "function" && (await onPaidError(earlier, { url, method })) === true;
+      if (!again) {
+        try { await probe.body?.cancel(); } catch { /* already consumed */ }
+        throw new SafePayError(paidTwiceMessage(url, earlier), { code: "paid_no_delivery", url, earlier });
+      }
+    }
+
     if (trustedHosts.has(hostOf(url))) {
       try { await probe.body?.cancel(); } catch { /* already consumed */ }
       return payAndCheck(url, init, method);

package/package.json

@@ -1,12 +1,16 @@
 {
   "name": "x402-safe-fetch",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "A fetch for AI agents that checks an unknown x402 endpoint ($0.001 x402 Doctor preflight) before paying it, and never pays above your budget.",
   "type": "module",
   "exports": {
     ".": {
       "types": "./index.d.ts",
       "default": "./index.js"
+    },
+    "./hook": {
+      "types": "./hook.d.ts",
+      "default": "./hook.js"
     }
   },
   "main": "./index.js",
@@ -14,7 +18,10 @@
   "files": [
     "index.js",
     "receipt.js",
+    "paid-guard.js",
+    "hook.js",
     "index.d.ts",
+    "hook.d.ts",
     "README.md",
     "LICENSE"
   ],

package/paid-guard.js

@@ -0,0 +1,64 @@
+// Never pay twice for one purchase that wasn't delivered.
+//
+// The costliest mistake in the agent exam (exam.fizzl.eu): a seller takes the payment, then answers with an error
+// (a 405, a 500, or another 402 asking to pay again), and the agent pays the same request again, and again. Every
+// model we examined did it at least once, with or without a preflight: the preflight only sees the 402 before paying.
+//
+// The guard remembers each paid request (method, URL and body) whose paid answer was not a success. Paying that same
+// request again within the window is refused, so the loss stops at one payment. A success clears it. A different
+// request (another URL, method or body) is not affected. No dependencies: it runs anywhere fetch does.
+
+export const PAID_ERROR_MS = 30 * 60 * 1000;
+
+// A short, stable fingerprint of the body (FNV-1a, 32 bit): the key holds no request content.
+function bodyKey(body) {
+  if (body === undefined || body === null) return "";
+  const text = typeof body === "string" ? body : body instanceof URLSearchParams ? body.toString() : ArrayBuffer.isView(body) ? new TextDecoder().decode(body) : body instanceof ArrayBuffer ? new TextDecoder().decode(new Uint8Array(body)) : String(body);
+  let h = 0x811c9dc5;
+  for (let i = 0; i < text.length; i++) {
+    h ^= text.charCodeAt(i);
+    h = Math.imul(h, 0x01000193) >>> 0;
+  }
+  return `${text.length}:${h.toString(16)}`;
+}
+
+/** The request as the guard sees it: method, URL and a fingerprint of the body. */
+export function purchaseKey(url, { method = "GET", body } = {}) {
+  return `${String(method).toUpperCase()} ${String(url)} ${bodyKey(body)}`;
+}
+
+/**
+ * @param {object} [options]
+ * @param {number} [options.windowMs]  how long a paid request that wasn't delivered stays blocked (default 30 minutes)
+ * @param {() => number} [options.now]
+ */
+export function createPaidGuard({ windowMs = PAID_ERROR_MS, now = Date.now } = {}) {
+  const failed = new Map(); // purchase key → { at, status }
+  const prune = () => {
+    const t = now();
+    for (const [k, v] of failed) if (t - v.at >= windowMs) failed.delete(k);
+    while (failed.size > 1000) failed.delete(failed.keys().next().value);
+  };
+  return {
+    /** The earlier paid answer that wasn't delivered ({ at, status }), while it blocks this request; else null. */
+    blocked(url, init = {}) {
+      prune();
+      return failed.get(purchaseKey(url, init)) ?? null;
+    },
+    /** After paying: what the paid request was answered with. */
+    record(url, init = {}, status) {
+      const key = purchaseKey(url, init);
+      if (status >= 200 && status < 300) failed.delete(key);
+      else failed.set(key, { at: now(), status });
+    },
+    /** Forget a request (e.g. the owner said to pay it again). */
+    clear(url, init = {}) {
+      failed.delete(purchaseKey(url, init));
+    },
+  };
+}
+
+/** The refusal text, for an error or a tool answer. */
+export function paidTwiceMessage(url, earlier) {
+  return `not paid again: ${url} was already paid at ${new Date(earlier.at).toISOString()} and answered HTTP ${earlier.status} without delivering. Paying the same request again would most likely be charged again for nothing; ask the seller, or try a different request.`;
+}