x402-safe-fetch 0.13.0 → 0.15.0

package/README.md

@@ -119,6 +119,8 @@ The hook can't see your request, only the 402, so Doctor checks the endpoint wit
 | `register` | required | `(client) => client.register(network, scheme)`: your payment schemes; your keys stay in your code |
 | `network` | `"base"` | `"base"`, `"solana"`, `"algorand"` (USDC), `"xrpl"` (RLUSD), `"stellar"` (USDC), `"xlayer"` (USD₮0 or USDC), their `-testnet` forms, or a CAIP-2 id; the preflight checks the option on this network |
 | `maxUsd` | `0.05` | Budget per endpoint call; the payment is capped at it and the preflight says `no_go` above it |
+| `maxTotalUsd` | none | Budget for every payment this safeFetch makes together; make one per task or session (see below) |
+| `maxPerSellerUsd` | none | The same per seller (the endpoint's host) |
 | `onCaution` | `"stop"` | `"stop"`, `"pay"` or `async (preflight) => boolean` |
 | `onIncomplete` | `"pay"` | A `go` whose `checks_complete` is `false` (a check that applies couldn't run this time, named in `not_checked`): `"pay"`, `"stop"` (throws code `incomplete`; not reported to the seller as a refusal) or `async (preflight) => boolean`. Such a verdict is reused for at most 10 minutes |
 | `trusted` | `[]` | Hosts paid without a preflight |
@@ -129,11 +131,45 @@ The hook can't see your request, only the 402, so Doctor checks the endpoint wit
 | `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.
+
+## A budget for the whole task
+
+`maxUsd` caps each payment. A seller that splits its answer over many cheap calls (2 cents a page, "call again for the next page") stays under that cap on every call and still runs up the bill. In the agent exam this is the `page-drip` task. Give safe-fetch a total, a budget per seller, or both:
+
+```js
+const safeFetch = createSafeFetch({
+  register,
+  maxUsd: 0.05,          // each payment
+  maxTotalUsd: 0.10,     // every payment of this safeFetch together
+  maxPerSellerUsd: 0.10, // every payment to one host
+});
+safeFetch.spent(); // { totalUsd: 0.06, bySeller: { "api.example.com": 0.06 } }
+```
+
+A payment that would go past either one throws `SafePayError` with code `over_total_budget` or `over_seller_budget` (and `error.spent`), before the preflight is bought. Near the end, x402's own cap on the next payment shrinks to what is left. The price comes from the seller's 402; when it can't be read, a payment counts as the most it may cost. A payment answered with another 402 isn't counted; a paid error is (the money is gone). Doctor's preflights and diagnoses are not counted. The totals live as long as the safeFetch: make one per task, user or session.
+
 ## 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/index.d.ts

@@ -41,9 +41,13 @@ 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" | "over_total_budget" | "over_seller_budget";
   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 };
+  /** With code "over_total_budget" or "over_seller_budget": what this safeFetch had paid. */
+  spent?: SpentUsd;
   /** Set when diagnoseOnFailure diagnosed a payment that failed. */
   diagnosis?: Diagnosis;
 }
@@ -55,6 +59,10 @@ export interface SafeFetchOptions {
   network?: string;
   /** Budget per endpoint call in USD. Default 0.05. */
   maxUsd?: number | string;
+  /** Budget in USD for every payment this safeFetch makes together (make one per task or session). Past it: code "over_total_budget". Default none. */
+  maxTotalUsd?: number | string;
+  /** Budget in USD per seller (the endpoint's host). Past it: code "over_seller_budget". Default none. */
+  maxPerSellerUsd?: number | string;
   /** What to do on a caution verdict. Default "stop". */
   onCaution?: "stop" | "pay" | ((preflight: Preflight) => boolean | Promise<boolean>);
   /** What to do on a "go" whose checks_complete is false (a check that applies couldn't run). Default "pay"; "stop" throws code "incomplete". */
@@ -78,13 +86,29 @@ 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;
   now?: () => number;
 }
 
-export declare function createSafeFetch(options: SafeFetchOptions): (input: string | URL, init?: RequestInit) => Promise<Response>;
+/** What a safeFetch paid to sellers, in USD (Doctor's preflights and diagnoses not included). */
+export interface SpentUsd {
+  totalUsd: number;
+  bySeller: Record<string, number>;
+}
+export interface SafeFetch {
+  (input: string | URL, init?: RequestInit): Promise<Response>;
+  /** What this safeFetch paid to sellers so far. */
+  spent(): SpentUsd;
+}
+export declare function createSafeFetch(options: SafeFetchOptions): SafeFetch;
+/** What an option costs in USD on `network` (USDC and USD₮0: 6 decimals; Stellar USDC: 7; RLUSD: decimal dollars), or null. */
+export declare function usdOfOption(option: { amount?: unknown; maxAmountRequired?: unknown }, network: string): number | null;
 export declare function usdCap(maxUsd: number | string): string;
 export declare function preflightUrl(target: string, options?: { method?: string; maxUsd?: number | string; network?: string; doctorUrl?: string }): string;
 export declare function diagnoseUrl(target: string, options?: { method?: string; doctorUrl?: string }): string;
@@ -102,3 +126,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.13.0";
+export const VERSION = "0.15.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";
@@ -92,6 +98,10 @@ export function anyAlgorandId(scheme) {
 // (not extra: invoices and nonces change per request). null when there is no x402 challenge to read (e.g. an
 // MPP-only 402). Reads and consumes the response body.
 export async function offerFingerprint(res) {
+  return (await readOffer(res)).fingerprint;
+}
+// The 402's x402 options and their fingerprint (see offerFingerprint). Reads and consumes the response body.
+export async function readOffer(res) {
   let challenge = null;
   const header = res?.headers?.get?.("payment-required");
   if (header) {
@@ -100,9 +110,18 @@ export async function offerFingerprint(res) {
   } else {
     try { challenge = JSON.parse(await res.text()); } catch { /* not JSON */ }
   }
-  if (!Array.isArray(challenge?.accepts)) return null;
+  if (!Array.isArray(challenge?.accepts)) return { fingerprint: null, accepts: null };
   const parts = challenge.accepts.map((a) => JSON.stringify([a?.scheme ?? null, a?.network ?? null, String(a?.asset ?? ""), String(a?.amount ?? a?.maxAmountRequired ?? ""), String(a?.payTo ?? "")]));
-  return JSON.stringify(parts.sort());
+  return { fingerprint: JSON.stringify(parts.sort()), accepts: challenge.accepts };
+}
+
+// What an option paid on `network` costs in US dollars, or null when it can't be read: RLUSD amounts are decimal
+// dollars, Circle's USDC on Stellar has 7 decimals, and every other token safe-fetch pays (USDC, USD₮0) has 6.
+export function usdOfOption(option, network) {
+  const raw = String(option?.amount ?? option?.maxAmountRequired ?? "");
+  if (RLUSD_ISSUER[network]) return /^\d+(\.\d+)?$/.test(raw) ? Number(raw) : null;
+  if (!/^\d+$/.test(raw)) return null;
+  return Number(raw) / (STELLAR_USDC[network] ? 1e7 : 1e6);
 }
 // Without an offer to compare (no readable x402 challenge), a verdict is reused for at most 10 minutes.
 const UNREAD_OFFER_MS = 10 * 60 * 1000;
@@ -141,13 +160,15 @@ 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" | "over_total_budget" | "over_seller_budget" */
+  constructor(message, { code, preflight = null, url = null, earlier, spent } = {}) {
     super(message);
     this.name = "SafePayError";
     this.code = code;
     this.preflight = preflight;
     this.url = url;
+    if (earlier) this.earlier = earlier;
+    if (spent) this.spent = spent;
   }
 }
 
@@ -229,6 +250,9 @@ function sameSite(a, b) {
  * @param {(client: x402Client) => unknown} options.register  registers your payment schemes on a client
  * @param {string} [options.network]  the network you pay on: "base", "solana", "algorand", "xrpl", "stellar" or a CAIP-2 id (default Base)
  * @param {number|string} [options.maxUsd]  budget per endpoint call (default 0.05)
+ * @param {number|string} [options.maxTotalUsd]  budget for every endpoint payment this safeFetch makes together (make
+ *   one per task or session); a payment that would pass it is refused with code "over_total_budget" (default: none)
+ * @param {number|string} [options.maxPerSellerUsd]  the same per seller (the endpoint's host); code "over_seller_budget"
  * @param {"stop"|"pay"|((preflight: object) => boolean|Promise<boolean>)} [options.onCaution]
  * @param {"pay"|"stop"|((preflight: object) => boolean|Promise<boolean>)} [options.onIncomplete]  a "go" whose checks_complete
  *   is false (a check that applies couldn't run): "pay" (default), "stop" throws code "incomplete", a function decides
@@ -244,6 +268,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]
  */
@@ -251,6 +279,8 @@ export function createSafeFetch({
   register,
   network = BASE,
   maxUsd = 0.05,
+  maxTotalUsd,
+  maxPerSellerUsd,
   onCaution = "stop",
   onIncomplete = "pay",
   trusted = [],
@@ -264,12 +294,18 @@ export function createSafeFetch({
   onDiagnosis,
   shareOutcomes = false,
   tellSellers = false,
+  onPaidError = "stop",
+  paidErrorMs = PAID_ERROR_MS,
   fetch: baseFetch = globalThis.fetch,
   createPayingFetch,
   now = Date.now,
 } = {}) {
   const payNetwork = NETWORK_ALIASES[network] ?? network;
   const budget = usdCap(maxUsd);
+  const perCall = Number(budget.slice(1));
+  const totalCap = maxTotalUsd === undefined || maxTotalUsd === null ? null : Number(usdCap(maxTotalUsd).slice(1));
+  const sellerCap = maxPerSellerUsd === undefined || maxPerSellerUsd === null ? null : Number(usdCap(maxPerSellerUsd).slice(1));
+  const limited = totalCap !== null || sellerCap !== null;
   if (!createPayingFetch && typeof register !== "function") {
     throw new TypeError("register is required: (client) => client.register(network, scheme)");
   }
@@ -279,6 +315,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));
 
@@ -309,7 +349,47 @@ export function createSafeFetch({
   let diagnoseFetch;
   const payPreflight = (...args) => (preflightFetch ??= makePayingFetch(PREFLIGHT_CAP))(...args);
   const payDiagnose = (...args) => (diagnoseFetch ??= makePayingFetch(DIAGNOSE_CAP))(...args);
-  const payEndpoint = (...args) => (endpointFetch ??= makePayingFetch(budget))(...args);
+  // With a total or per-seller budget, a payment is capped at what is left of it (x402's spend controls): a paying
+  // fetch per cap, kept for the caps in use.
+  const cappedFetches = new Map();
+  const payEndpoint = (url, init, cap = budget) => {
+    if (cap === budget) return (endpointFetch ??= makePayingFetch(budget))(url, init);
+    if (!cappedFetches.has(cap)) {
+      if (cappedFetches.size >= 50) cappedFetches.delete(cappedFetches.keys().next().value);
+      cappedFetches.set(cap, makePayingFetch(cap));
+    }
+    return cappedFetches.get(cap)(url, init);
+  };
+
+  // What was paid (or is being paid) to sellers, for maxTotalUsd and maxPerSellerUsd, in dollars.
+  const spend = { total: 0, bySeller: new Map() };
+  const round6 = (n) => Math.round(n * 1e6) / 1e6;
+  const spentAt = (host) => spend.bySeller.get(host) ?? 0;
+  function addSpend(host, usd) {
+    spend.total = round6(spend.total + usd);
+    spend.bySeller.set(host, round6(spentAt(host) + usd));
+  }
+  const spentNow = () => ({ totalUsd: spend.total, bySeller: Object.fromEntries(spend.bySeller) });
+  // What one more payment to `host` may cost: the per-call budget, or less when the total or the seller's budget is
+  // nearly spent. Throws when nothing is left of either, or when the price (if it can be read) is over what is left.
+  // A price over the per-call budget alone is left to Doctor's preflight (over_budget) and x402's cap, as before.
+  function allowance(url, host, price) {
+    const totalLeft = totalCap === null ? Infinity : round6(totalCap - spend.total);
+    const sellerLeft = sellerCap === null ? Infinity : round6(sellerCap - spentAt(host));
+    const cap = Math.min(perCall, totalLeft, sellerLeft);
+    const short = Math.min(totalLeft, sellerLeft);
+    const over = short <= 0 || (price !== null && price > short + 1e-9);
+    if (over) {
+      const byTotal = totalLeft <= sellerLeft;
+      const which = byTotal ? `the total budget ($${totalCap})` : `the budget for ${host} ($${sellerCap})`;
+      const asks = price === null ? "" : `; the endpoint asks $${round6(price)}`;
+      const paid = byTotal ? spend.total : spentAt(host);
+      throw new SafePayError(`not paid: ${which} has $${Math.max(0, short)} left${asks} (already paid $${paid})`, {
+        code: byTotal ? "over_total_budget" : "over_seller_budget", url, spent: spentNow(),
+      });
+    }
+    return { cap, price };
+  }
 
   const verdicts = new Map();
   async function preflightFor(url, method, offer) {
@@ -422,11 +502,37 @@ export function createSafeFetch({
     tellSeller(url, preflight);
   }
 
-  async function payAndCheck(url, init, method) {
-    if (!diagnoseOnFailure) return payEndpoint(url, init);
+  // Every endpoint payment goes through here: what it was answered with is remembered for the paid-twice guard.
+  // With a total or per-seller budget, the payment is capped at what is left and counted as it starts (so parallel
+  // calls can't both spend the rest), and taken back when nothing was paid (402 again, or paying threw).
+  async function payAndCheck(url, init, method, offer) {
+    let host = null;
+    let counted = 0;
+    let cap = budget;
+    if (limited) {
+      host = hostOf(url);
+      const option = offer?.accepts ? payableOption(offer.accepts, payNetwork, budget) : null;
+      const allowed = allowance(url, host, option ? usdOfOption(option, payNetwork) : null);
+      counted = allowed.price ?? allowed.cap; // an unreadable price counts as the most it may cost
+      if (allowed.cap < perCall) cap = usdCap(allowed.cap);
+      addSpend(host, counted);
+    }
+    let res;
+    try {
+      res = await payAndDiagnose(url, init, method, cap);
+    } catch (error) {
+      if (limited) addSpend(host, -counted);
+      throw error;
+    }
+    if (limited && res.status === 402) addSpend(host, -counted);
+    paidGuard.record(url, { method, body: init.body }, res.status);
+    return res;
+  }
+  async function payAndDiagnose(url, init, method, cap) {
+    if (!diagnoseOnFailure) return payEndpoint(url, init, cap);
     let res;
     try {
-      res = await payEndpoint(url, init);
+      res = await payEndpoint(url, init, cap);
     } catch (error) {
       if (error instanceof SafePayError && error.code !== "no_option") throw error;
       const report = await diagnoseFor(url, method);
@@ -446,19 +552,33 @@ export function createSafeFetch({
     return res;
   }
 
-  return async function safeFetch(input, init = {}) {
+  async function safeFetch(input, init = {}) {
     const { url, method } = requestOf(input, init);
     const probe = await baseFetch(url, init);
     if (probe.status !== 402) return probe;
 
-    if (trustedHosts.has(hostOf(url))) {
-      try { await probe.body?.cancel(); } catch { /* already consumed */ }
-      return payAndCheck(url, init, method);
+    // 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 });
+      }
+    }
+
+    const offer = await readOffer(probe);
+    // Already over the total or the seller's budget: refused before the preflight, so nothing is spent on it.
+    if (limited) {
+      const option = offer.accepts ? payableOption(offer.accepts, payNetwork, budget) : null;
+      allowance(url, hostOf(url), option ? usdOfOption(option, payNetwork) : null);
     }
 
-    const { preflight, cached } = await preflightFor(url, method, await offerFingerprint(probe));
+    if (trustedHosts.has(hostOf(url))) return payAndCheck(url, init, method, offer);
+
+    const { preflight, cached } = await preflightFor(url, method, offer.fingerprint);
     const payAfterPreflight = async () => {
-      const res = await payAndCheck(url, init, method);
+      const res = await payAndCheck(url, init, method, offer);
       reportOutcome(url, method, preflight, res);
       return res;
     };
@@ -484,5 +604,8 @@ export function createSafeFetch({
       if (!ok) throw new SafePayError(`not paid: go, but not every check ran (${missing}); try again in a few minutes`, { code: "incomplete", preflight, url });
     }
     return payAfterPreflight();
-  };
+  }
+  // What this safeFetch paid to sellers so far, in US dollars (Doctor's preflights and diagnoses not included).
+  safeFetch.spent = spentNow;
+  return safeFetch;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "x402-safe-fetch",
-  "version": "0.13.0",
+  "version": "0.15.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": {
@@ -18,6 +18,7 @@
   "files": [
     "index.js",
     "receipt.js",
+    "paid-guard.js",
     "hook.js",
     "index.d.ts",
     "hook.d.ts",

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.`;
+}