x402-safe-fetch 0.4.0 → 0.6.0

package/README.md

@@ -10,7 +10,7 @@ A free endpoint is answered as is. For a paid one (HTTP 402), your agent first p
 | `caution` | `onCaution`: `"stop"` (default, throws), `"pay"`, or your own function (e.g. ask the user) |
 | `no_go` | Throws `SafePayError`; the endpoint is not paid |
 
-The preflight reads the endpoint's 402 challenge and checks, among others, the price against your budget and against what the service advertises, whether the option is payable on your network (USDC, a valid payout address, a Solana payout account that exists), HTTPS, and whether the endpoint is listed in the CDP Bazaar. A verdict is reused for 10 minutes; hosts you already trust skip it.
+The preflight reads the endpoint's 402 challenge and checks, among others, the price against your budget and against what the service advertises, whether the option is payable on your network (USDC, a valid payout address, a Solana payout account that exists, an Algorand payout opted in to USDC), HTTPS, and whether the endpoint is listed in the CDP Bazaar. A verdict is reused while the endpoint's 402 offers the same thing (up to an hour); a changed price, payout address, token or network is checked again right away. Hosts you already trust skip it.
 
 ## Install
 
@@ -45,20 +45,35 @@ try {
 
 Solana works the same way: `network: "solana"` and register an `ExactSvmScheme` from `@x402/svm/exact/client` with a `@solana/kit` signer.
 
+Algorand and the XRP Ledger work the same way, and only their dollar stablecoin is ever paid. On Algorand that is USDC (ASA 31566704), never ALGO or another ASA. On the XRP Ledger it is RLUSD from Ripple's issuer, never XRP or a look-alike token. RLUSD prices are decimal dollars, so the budget is checked in dollars. The Doctor preflight is paid on the same network.
+
+```js
+import { toClientAvmSigner } from "@x402/avm";
+import { ExactAvmScheme } from "@x402/avm/exact/client";
+
+const safeFetch = createSafeFetch({
+  network: "algorand", // your account must be opted in to USDC
+  register: (client) => client.register("algorand:*", new ExactAvmScheme(toClientAvmSigner(process.env.AVM_PRIVATE_KEY))),
+});
+// XRP Ledger: network: "xrpl" and an ExactXrplScheme from @x402/xrpl/exact/client
+// (createXrplWalletSigner(Wallet.fromSeed(process.env.XRPL_SEED))); needs an RLUSD trust line.
+```
+
 ## Options
 
 | Option | Default | |
 |---|---|---|
 | `register` | required | `(client) => client.register(network, scheme)`: your payment schemes; your keys stay in your code |
-| `network` | `"base"` | `"base"`, `"solana"` or a CAIP-2 id; the preflight checks the option on this network |
+| `network` | `"base"` | `"base"`, `"solana"`, `"algorand"` (USDC), `"xrpl"` (RLUSD), 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 |
 | `onCaution` | `"stop"` | `"stop"`, `"pay"` or `async (preflight) => boolean` |
 | `trusted` | `[]` | Hosts paid without a preflight |
 | `onPreflight` | | `(preflight, { url, method, cached }) => void`, e.g. for logging |
-| `cacheMs` | 10 minutes | How long a verdict is reused per method and URL |
+| `cacheMs` | 1 hour | How long a verdict is reused per method and URL while the 402 offers the same thing (at most 10 minutes when the offer can't be read); any change in price, payout address, token or network means a new preflight |
 | `verifyReceipts` | `"require"` | Check Doctor's signed receipt on every preflight; `"off"` skips it |
 | `doctorSigners` | Doctor's published signer | Accepted signer addresses (for a self-hosted Doctor) |
 | `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 (see below) |
 | `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` |
 
@@ -88,6 +103,14 @@ if (res.status === 402) {
 
 Doctor's requests carry `user-agent: x402-safe-fetch/<version>` so the service can count how often the package is used; nothing about your agent or wallet is sent beyond the payment itself.
 
+## Helping the preflight learn
+
+With `shareOutcomes: true`, safe-fetch tells x402 Doctor what happened after it paid an endpoint that a preflight approved: `paid_ok` (2xx), `paid_failed` (402 again: the payment was not accepted) or `paid_error` (another error). Doctor counts these reports per endpoint over 30 days, from every agent that shares them. When most payments to an endpoint failed, reported by at least three different wallets, later preflights for it answer `caution` (`payments_fail_after_preflight`), so the next agent does not pay into the same wall.
+
+- What is sent: the outcome, the HTTP status, the signed preflight you already received and its query (endpoint, method, budget, network). No keys, no response content.
+- A report only counts with a real, paid preflight for that endpoint, once per preflight, so reports cannot be made up for free.
+- It is sent after the answer and never delays or changes it. Off by default.
+
 ## Signed verdicts
 
 x402 Doctor signs every paid preflight (EIP-191 over canonical JSON, with the request inside the signed body; see [Signed verdicts](https://github.com/Fizzl13/x402-doctor#signed-verdicts)). safe-fetch checks that signature before it acts on a verdict:
@@ -102,8 +125,8 @@ x402 Doctor signs every paid preflight (EIP-191 over canonical JSON, with the re
 
 ## Costs and limits
 
-- $0.001 per preflight (once per endpoint per 10 minutes), plus the endpoint's own price.
-- With `diagnoseOnFailure`: $0.01 per diagnosis, only when a payment fails (once per endpoint per 10 minutes).
+- $0.001 per preflight (once per endpoint per hour while its offer stays the same, again at once when it changes), plus the endpoint's own price.
+- With `diagnoseOnFailure`: $0.01 per diagnosis, only when a payment fails (once per endpoint per `cacheMs`).
 - Bodies must be strings, Buffers or `URLSearchParams`: the request is sent once unpaid (to see the 402) and once paid.
 - If Doctor is unreachable, nothing is paid (`SafePayError` with code `preflight_failed`).
 - The preflight checks whether a payment can succeed and is sensible; it does not guarantee what the service delivers after payment.

package/index.d.ts

@@ -6,6 +6,14 @@ export declare const DIAGNOSE_CAP: string;
 export declare const VERSION: string;
 export declare const BASE: "eip155:8453";
 export declare const SOLANA: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp";
+export declare const ALGORAND: "algorand:wGHE2Pwdvd7S12BL5FaOP20EGYesN73ktiC1qzkkit8=";
+export declare const ALGORAND_TESTNET: "algorand:SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI=";
+export declare const XRPL: "xrpl:0";
+export declare const XRPL_TESTNET: "xrpl:1";
+/** The option paid on `network`: on Algorand only USDC, on the XRP Ledger only RLUSD from Ripple's issuer within maxUsd (in dollars); null when there is none. */
+/** What a 402 offers (per x402 option: scheme, network, asset, amount, payTo) as a stable string; null without a readable x402 challenge. Consumes the body. */
+export declare function offerFingerprint(res: Response): Promise<string | null>;
+export declare function payableOption<A extends { network: string; asset?: unknown; amount?: unknown; extra?: Record<string, unknown> }>(accepts: A[], network: string, maxUsd: number | string): A | null;
 
 /** The x402 Doctor preflight: see https://x402-doctor.fizzl.eu/openapi.json */
 export interface Preflight {
@@ -34,7 +42,7 @@ export declare class SafePayError extends Error {
 export interface SafeFetchOptions {
   /** Registers your payment schemes, e.g. (c) => c.register("eip155:8453", new ExactEvmScheme(account)). */
   register: (client: x402Client) => unknown;
-  /** The network you pay on: "base", "solana" or a CAIP-2 id. Default Base. */
+  /** The network you pay on: "base", "solana", "algorand" (USDC), "xrpl" (RLUSD), their "-testnet" forms, or a CAIP-2 id. Default Base. */
   network?: string;
   /** Budget per endpoint call in USD. Default 0.05. */
   maxUsd?: number | string;
@@ -43,7 +51,7 @@ export interface SafeFetchOptions {
   /** Hosts you already trust: paid without a preflight. */
   trusted?: string[];
   onPreflight?: (preflight: Preflight, info: { url: string; method: string; cached: boolean }) => void;
-  /** How long a verdict is reused, in ms. Default 10 minutes. */
+  /** How long a verdict is reused while the endpoint's 402 offers the same thing, in ms. Default 1 hour; a changed price, payout address, token or network is checked again at once; at most 10 minutes when the offer can't be read. */
   cacheMs?: number;
   doctorUrl?: string;
   /** Check Doctor's signed receipt on every preflight (signer, and bound to this request). Default "require". */
@@ -55,6 +63,8 @@ export interface SafeFetchOptions {
   /** When a payment still fails (402 again, or paying throws), buy a $0.01 Doctor diagnosis of why. Default false. */
   diagnoseOnFailure?: boolean;
   onDiagnosis?: (report: Diagnosis, info: { url: string; method: string; status: number | null; error: Error | null }) => void;
+  /** After paying, tell Doctor whether the payment worked (with the signed preflight as proof), so later preflights learn from it. Default false. */
+  shareOutcomes?: boolean;
   fetch?: typeof globalThis.fetch;
   /** Advanced/testing: a paying fetch capped at `cap` (e.g. "$0.05"). */
   createPayingFetch?: (cap: string) => typeof globalThis.fetch;

package/index.js

@@ -8,16 +8,22 @@
 //   caution → onCaution: "stop" (default, throws), "pay", or your own async
 //             function that decides (e.g. ask the user)
 //   go      → pays the endpoint, never more than maxUsd
-// Trusted hosts skip the preflight; a verdict is reused for 10 minutes.
+// Trusted hosts skip the preflight. A verdict is reused while the endpoint's 402 offers the same thing
+// (up to an hour); a changed price, payout address, token or network is checked again at once.
 // With diagnoseOnFailure, a payment that still fails (the endpoint answers 402
 // again, or paying throws) gets a $0.01 Doctor diagnosis that says why and how
 // to fix it: onDiagnosis(report), diagnosisOf(response) or error.diagnosis.
+// With shareOutcomes, after paying it tells Doctor what happened (paid_ok,
+// paid_failed, paid_error), with the signed preflight as proof, so later
+// preflights for that endpoint learn from what agents ran into. Off by
+// default; no keys, amounts or response content are sent.
 // 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).
 //
 // Payments use @x402/fetch with the schemes you register (your keys stay in
 // your code): register: (client) => client.register("eip155:8453", new ExactEvmScheme(account))
+// On Algorand (USDC) and the XRP Ledger (RLUSD) only the dollar stablecoin is paid.
 
 import { wrapFetchWithPayment, x402Client, decodePaymentResponseHeader } from "@x402/fetch";
 import { verifyReceipt, DOCTOR_SIGNERS, AUTHORITY } from "./receipt.js";
@@ -27,12 +33,54 @@ export { verifyReceipt, recoverSigner, canonicalJson, inputHash, certMessage, DO
 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.4.0";
+export const VERSION = "0.6.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";
 export const SOLANA = "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp";
-const NETWORK_ALIASES = { base: BASE, solana: SOLANA };
+export const ALGORAND = "algorand:wGHE2Pwdvd7S12BL5FaOP20EGYesN73ktiC1qzkkit8=";
+export const ALGORAND_TESTNET = "algorand:SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI=";
+export const XRPL = "xrpl:0";
+export const XRPL_TESTNET = "xrpl:1";
+const NETWORK_ALIASES = { base: BASE, solana: SOLANA, algorand: ALGORAND, "algorand-testnet": ALGORAND_TESTNET, xrpl: XRPL, "xrpl-testnet": XRPL_TESTNET };
+
+// On Algorand and the XRP Ledger only the dollar stablecoin is paid: USDC (an ASA) on Algorand, RLUSD from
+// Ripple's issuer on the XRP Ledger. Never ALGO, XRP or another token, so the dollar budget always holds.
+const ALGORAND_USDC = { [ALGORAND]: "31566704", [ALGORAND_TESTNET]: "10458941" };
+const RLUSD_HEX = "524C555344000000000000000000000000000000";
+const RLUSD_ISSUER = { [XRPL]: "rMxCKbEDwqr76QuheSUMdEGf4B9xJ8m5De", [XRPL_TESTNET]: "rQhWct2fv4Vc4KRjRgMrxa8xPN9Zx9iLKV" };
+
+// The option to pay on `network`, or null. RLUSD prices are decimal dollars ("0.001", and "2" is two dollars),
+// which x402's spend controls would read as base units, so the budget is checked here in dollars.
+// What a 402 offers, as a stable string: per x402 option its scheme, network, asset, amount and payout address
+// (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) {
+  let challenge = null;
+  const header = res?.headers?.get?.("payment-required");
+  if (header) {
+    try { challenge = JSON.parse(new TextDecoder().decode(Uint8Array.from(atob(header), (c) => c.charCodeAt(0)))); } catch { /* not base64 JSON */ }
+    try { await res.body?.cancel(); } catch { /* already consumed */ }
+  } else {
+    try { challenge = JSON.parse(await res.text()); } catch { /* not JSON */ }
+  }
+  if (!Array.isArray(challenge?.accepts)) return 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());
+}
+// 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;
+
+export function payableOption(accepts, network, maxUsd) {
+  const cap = Number(String(maxUsd).replace(/^\$/, ""));
+  const on = (accepts ?? []).filter((a) => a?.network === network);
+  if (ALGORAND_USDC[network]) return on.find((a) => String(a.asset) === ALGORAND_USDC[network]) ?? null;
+  if (RLUSD_ISSUER[network]) {
+    return on.find((a) => String(a.asset ?? "").toUpperCase() === RLUSD_HEX && a.extra?.issuer === RLUSD_ISSUER[network]
+      && /^\d+(\.\d+)?$/.test(String(a.amount)) && Number(a.amount) > 0 && Number(a.amount) <= cap) ?? null;
+  }
+  return on[0] ?? null;
+}
 
 export class SafePayError extends Error {
   /** code: "no_go" | "caution" | "preflight_failed" | "bad_receipt" | "no_option" */
@@ -103,12 +151,12 @@ function requestOf(input, init) {
 /**
  * @param {object} options
  * @param {(client: x402Client) => unknown} options.register  registers your payment schemes on a client
- * @param {string} [options.network]  the network you pay on: "base", "solana" or a CAIP-2 id (default Base)
+ * @param {string} [options.network]  the network you pay on: "base", "solana", "algorand", "xrpl" or a CAIP-2 id (default Base)
  * @param {number|string} [options.maxUsd]  budget per endpoint call (default 0.05)
  * @param {"stop"|"pay"|((preflight: object) => boolean|Promise<boolean>)} [options.onCaution]
  * @param {string[]} [options.trusted]  hosts you already trust: paid without a preflight
  * @param {(preflight: object, info: {url: string, method: string, cached: boolean}) => void} [options.onPreflight]
- * @param {number} [options.cacheMs]  how long a verdict is reused (default 10 minutes)
+ * @param {number} [options.cacheMs]  how long a verdict is reused while the 402 offers the same thing (default 1 hour; at most 10 minutes when the offer can't be read)
  * @param {string} [options.doctorUrl]
  * @param {"require"|"off"} [options.verifyReceipts]  check Doctor's signature on every preflight (default "require")
  * @param {string[]} [options.doctorSigners]  accepted Doctor signer addresses (default: the published signer)
@@ -116,6 +164,7 @@ function requestOf(input, init) {
  * @param {typeof fetch} [options.fetch]  the underlying fetch (default globalThis.fetch)
  * @param {boolean} [options.diagnoseOnFailure]  when a payment still fails, buy a $0.01 Doctor diagnosis of why (default false)
  * @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 {(cap: string) => typeof fetch} [options.createPayingFetch]  advanced/testing: a paying fetch capped at `cap`
  * @param {() => number} [options.now]
  */
@@ -126,13 +175,14 @@ export function createSafeFetch({
   onCaution = "stop",
   trusted = [],
   onPreflight,
-  cacheMs = 10 * 60 * 1000,
+  cacheMs = 60 * 60 * 1000,
   doctorUrl = DOCTOR_URL,
   verifyReceipts = "require",
   doctorSigners = DOCTOR_SIGNERS,
   authority = AUTHORITY,
   diagnoseOnFailure = false,
   onDiagnosis,
+  shareOutcomes = false,
   fetch: baseFetch = globalThis.fetch,
   createPayingFetch,
   now = Date.now,
@@ -150,8 +200,8 @@ export function createSafeFetch({
 
   const makePayingFetch = createPayingFetch ?? ((cap) => {
     const client = new x402Client((_version, accepts) => {
-      const pick = accepts.find((a) => a.network === payNetwork);
-      if (!pick) throw new SafePayError(`no payment option on ${payNetwork}`, { code: "no_option" });
+      const pick = payableOption(accepts, payNetwork, cap);
+      if (!pick) throw new SafePayError(`no payment option on ${payNetwork}${ALGORAND_USDC[payNetwork] ? " in USDC" : RLUSD_ISSUER[payNetwork] ? ` in RLUSD within ${cap}` : ""}`, { code: "no_option" });
       return pick;
     }).setSpendControls({ maxAmountPerPayment: cap });
     register(client);
@@ -165,10 +215,11 @@ export function createSafeFetch({
   const payEndpoint = (...args) => (endpointFetch ??= makePayingFetch(budget))(...args);
 
   const verdicts = new Map();
-  async function preflightFor(url, method) {
+  async function preflightFor(url, method, offer) {
     const key = `${method} ${url}`;
     const hit = verdicts.get(key);
-    if (hit && hit.expires > now()) return { preflight: hit.preflight, cached: true };
+    const ttl = offer === null ? Math.min(cacheMs, UNREAD_OFFER_MS) : cacheMs;
+    if (hit && hit.offer === offer && hit.at + ttl > now()) return { preflight: hit.preflight, cached: true };
     const pfUrl = preflightUrl(url, { method, maxUsd: budget, network: payNetwork, doctorUrl });
     const res = await payPreflight(pfUrl, { headers: DOCTOR_HEADERS });
     const preflight = await res.json().catch(() => null);
@@ -181,7 +232,7 @@ export function createSafeFetch({
       const check = verifyReceipt(preflight, { signers: doctorSigners, route: "GET /api/v1/preflight", input, authority, service: "x402-doctor" });
       if (!check.valid) throw new SafePayError(`preflight not trusted (${check.reason}); the endpoint was not paid`, { code: "bad_receipt", preflight, url });
     }
-    verdicts.set(key, { preflight, expires: now() + cacheMs });
+    verdicts.set(key, { preflight, offer, at: now() });
     if (verdicts.size > 1000) verdicts.delete(verdicts.keys().next().value);
     return { preflight, cached: false };
   }
@@ -211,6 +262,26 @@ export function createSafeFetch({
     return report;
   }
 
+  // One outcome report per paid preflight: Doctor counts it once anyway.
+  const reported = new Set();
+  function reportOutcome(url, method, preflight, res) {
+    if (!shareOutcomes || !preflight?.receipt?.request_id || reported.has(preflight.receipt.request_id)) return;
+    const outcome = res.ok ? "paid_ok" : res.status === 402 ? "paid_failed" : res.status >= 400 ? "paid_error" : null;
+    if (!outcome) return;
+    reported.add(preflight.receipt.request_id);
+    if (reported.size > 1000) reported.delete(reported.values().next().value);
+    const query = Object.fromEntries(new URL(preflightUrl(url, { method, maxUsd: budget, network: payNetwork, doctorUrl })).searchParams);
+    // Fire and forget: the report never delays or changes the answer.
+    Promise.resolve()
+      .then(() => baseFetch(`${doctorUrl.replace(/\/$/, "")}/api/v1/outcome`, {
+        method: "POST",
+        headers: { ...DOCTOR_HEADERS, "content-type": "application/json" },
+        body: JSON.stringify({ outcome, status: res.status, preflight, query }),
+      }))
+      .then((r) => r?.body?.cancel?.())
+      .catch(() => {});
+  }
+
   async function payAndCheck(url, init, method) {
     if (!diagnoseOnFailure) return payEndpoint(url, init);
     let res;
@@ -239,11 +310,18 @@ export function createSafeFetch({
     const { url, method } = requestOf(input, init);
     const probe = await baseFetch(url, init);
     if (probe.status !== 402) return probe;
-    try { await probe.body?.cancel(); } catch { /* already consumed */ }
 
-    if (trustedHosts.has(hostOf(url))) return payAndCheck(url, init, method);
+    if (trustedHosts.has(hostOf(url))) {
+      try { await probe.body?.cancel(); } catch { /* already consumed */ }
+      return payAndCheck(url, init, method);
+    }
 
-    const { preflight, cached } = await preflightFor(url, method);
+    const { preflight, cached } = await preflightFor(url, method, await offerFingerprint(probe));
+    const payAfterPreflight = async () => {
+      const res = await payAndCheck(url, init, method);
+      reportOutcome(url, method, preflight, res);
+      return res;
+    };
     onPreflight?.(preflight, { url, method, cached });
     const why = preflight.summary || preflight.verdict;
     if (preflight.verdict === "no_go") throw new SafePayError(`not paid: ${why}`, { code: "no_go", preflight, url });
@@ -253,6 +331,6 @@ export function createSafeFetch({
     } else if (preflight.verdict !== "go") {
       throw new SafePayError(`not paid: unknown verdict ${preflight.verdict}`, { code: "preflight_failed", preflight, url });
     }
-    return payAndCheck(url, init, method);
+    return payAfterPreflight();
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "x402-safe-fetch",
-  "version": "0.4.0",
+  "version": "0.6.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": {
@@ -28,8 +28,11 @@
     "@x402/fetch": "^2.27.0"
   },
   "devDependencies": {
+    "@algorandfoundation/algokit-utils": "^10.0.0-alpha.46",
+    "@x402/avm": "^2.28.0",
     "@x402/evm": "^2.27.0",
     "@x402/fetch": "^2.27.0",
+    "@x402/xrpl": "^2.28.0",
     "viem": "^2.56.9"
   },
   "keywords": [
@@ -41,6 +44,9 @@
     "usdc",
     "base",
     "solana",
+    "algorand",
+    "xrpl",
+    "rlusd",
     "signed-receipts"
   ],
   "repository": {