x402-safe-fetch 0.5.0 → 0.7.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), whether the payout address is on the OFAC SDN sanctions list (then `no_go`: never paid), 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,17 +45,34 @@ 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.
+// Stellar: network: "stellar" and an ExactStellarScheme from @x402/stellar/exact/client
+// (createEd25519Signer(process.env.STELLAR_SECRET, "stellar:pubnet")); needs a USDC trustline.
+// Only Circle's USDC contract is paid, never XLM; the facilitator pays the network fee.
+```
+
 ## 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) |
@@ -111,8 +128,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,16 @@ 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";
+export declare const STELLAR: "stellar:pubnet";
+export declare const STELLAR_TESTNET: "stellar:testnet";
+/** The option paid on `network`: on Algorand only USDC, on Stellar only Circle's USDC contract within maxUsd, 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 +44,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), "stellar" (USDC), 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 +53,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". */

package/index.js

@@ -8,7 +8,8 @@
 //   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.
@@ -22,6 +23,7 @@
 //
 // 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), the XRP Ledger (RLUSD) and Stellar (USDC) only the dollar stablecoin is paid.
 
 import { wrapFetchWithPayment, x402Client, decodePaymentResponseHeader } from "@x402/fetch";
 import { verifyReceipt, DOCTOR_SIGNERS, AUTHORITY } from "./receipt.js";
@@ -31,12 +33,62 @@ 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.5.0";
+export const VERSION = "0.7.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";
+export const STELLAR = "stellar:pubnet";
+export const STELLAR_TESTNET = "stellar:testnet";
+const NETWORK_ALIASES = { base: BASE, solana: SOLANA, algorand: ALGORAND, "algorand-testnet": ALGORAND_TESTNET, xrpl: XRPL, "xrpl-testnet": XRPL_TESTNET, stellar: STELLAR, "stellar-testnet": STELLAR_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" };
+// On Stellar only Circle's USDC token contract (7 decimals), never XLM or another token named USDC.
+const STELLAR_USDC = { [STELLAR]: "CCW67TSZV3SSS2HXMBQ5JFGCKJNXKZM7UQUWUZPUTHXSTZLEO7SJMI75", [STELLAR_TESTNET]: "CBIELTK6YBZJU5UP2WWQEUCYKLPU6AUNZ2BQ4WWFEIE3USCIHMXQDAMA" };
+
+// 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;
+  // x402's spend controls cap Stellar USDC too; the budget is checked here as well, in dollars.
+  if (STELLAR_USDC[network]) {
+    return on.find((a) => a.asset === STELLAR_USDC[network] && /^\d+$/.test(String(a.amount)) && Number(a.amount) > 0 && Number(a.amount) / 1e7 <= cap) ?? 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" */
@@ -107,12 +159,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", "stellar" 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)
@@ -131,7 +183,7 @@ export function createSafeFetch({
   onCaution = "stop",
   trusted = [],
   onPreflight,
-  cacheMs = 10 * 60 * 1000,
+  cacheMs = 60 * 60 * 1000,
   doctorUrl = DOCTOR_URL,
   verifyReceipts = "require",
   doctorSigners = DOCTOR_SIGNERS,
@@ -156,8 +208,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" : STELLAR_USDC[payNetwork] ? ` in USDC within ${cap}` : RLUSD_ISSUER[payNetwork] ? ` in RLUSD within ${cap}` : ""}`, { code: "no_option" });
       return pick;
     }).setSpendControls({ maxAmountPerPayment: cap });
     register(client);
@@ -171,10 +223,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);
@@ -187,7 +240,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 };
   }
@@ -265,11 +318,13 @@ 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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "x402-safe-fetch",
-  "version": "0.5.0",
+  "version": "0.7.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,12 @@
     "@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/stellar": "^2.28.0",
+    "@x402/xrpl": "^2.28.0",
     "viem": "^2.56.9"
   },
   "keywords": [
@@ -41,7 +45,11 @@
     "usdc",
     "base",
     "solana",
-    "signed-receipts"
+    "algorand",
+    "xrpl",
+    "rlusd",
+    "signed-receipts",
+    "stellar"
   ],
   "repository": {
     "type": "git",