x402-safe-fetch 0.7.0 → 0.9.0

package/README.md

@@ -45,7 +45,7 @@ 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.
+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. Sellers name Algorand mainnet either by the whole genesis hash or by its CAIP-2 id (`algorand:wGHE2Pwdvd7S12BL5FaOP20EGYesN73k`); both are paid, also with `@x402/avm` 2.29.0, which on its own accepts only the short id. 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";
@@ -60,14 +60,38 @@ const safeFetch = createSafeFetch({
 // 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.
+// X Layer (OKX): network: "xlayer" and an ExactEvmScheme from @x402/evm/exact/client with your viem account.
+// Only USD₮0 (0x779d…3736) or USDC (0x74b7…6d22) is paid, never OKB or another token named USDC; the
+// facilitator (PayAI) pays the gas.
 ```
 
+### Escrowed payments (auth-capture)
+
+Some sellers on Base take payment through Coinbase's escrow instead of a direct transfer: the x402 scheme
+`auth-capture`. Your wallet signs once, the USDC is held, and the seller captures it only after it has delivered
+(Atom's domain checkout, for instance, captures once the domain is registered, and releases it if registration
+fails). Register that scheme next to the exact one to pay such sellers (`@x402/evm` 2.27 or later):
+
+```js
+import { AuthCaptureEvmScheme } from "@x402/evm/auth-capture/client";
+
+const safeFetch = createSafeFetch({
+  register: (client) => {
+    client.register("eip155:8453", new ExactEvmScheme(account));
+    client.register("eip155:8453", new AuthCaptureEvmScheme(account));
+  },
+  maxUsd: 25, // the budget caps the most that can be captured
+});
+```
+
+When a seller offers both, the exact option is paid. The preflight and the budget apply the same way.
+
 ## Options
 
 | Option | Default | |
 |---|---|---|
 | `register` | required | `(client) => client.register(network, scheme)`: your payment schemes; your keys stay in your code |
-| `network` | `"base"` | `"base"`, `"solana"`, `"algorand"` (USDC), `"xrpl"` (RLUSD), their `-testnet` forms, or a CAIP-2 id; the preflight checks the option on this network |
+| `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 |
 | `onCaution` | `"stop"` | `"stop"`, `"pay"` or `async (preflight) => boolean` |
 | `trusted` | `[]` | Hosts paid without a preflight |

package/index.d.ts

@@ -12,9 +12,12 @@ 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. */
+export declare const XLAYER: "eip155:196";
+/** The option paid on `network`: on Algorand only USDC, on Stellar only Circle's USDC contract within maxUsd, on X Layer only USD₮0 or USDC 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>;
+/** Wraps an Algorand scheme (e.g. @x402/avm's ExactAvmScheme) so it pays sellers that name Algorand by the whole genesis hash as well as by the CAIP-2 id. createSafeFetch does this for you. */
+export declare function anyAlgorandId<S extends object>(scheme: S): S;
 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 */
@@ -44,7 +47,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", "algorand" (USDC), "xrpl" (RLUSD), "stellar" (USDC), their "-testnet" forms, or a CAIP-2 id. Default Base. */
+  /** The network you pay on: "base", "solana", "algorand" (USDC), "xrpl" (RLUSD), "stellar" (USDC), "xlayer" (USD₮0 or 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;

package/index.js

@@ -23,7 +23,8 @@
 //
 // 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.
+// On Algorand (USDC), the XRP Ledger (RLUSD), Stellar (USDC) and X Layer (USD₮0 or USDC) only the dollar
+// stablecoin is paid.
 
 import { wrapFetchWithPayment, x402Client, decodePaymentResponseHeader } from "@x402/fetch";
 import { verifyReceipt, DOCTOR_SIGNERS, AUTHORITY } from "./receipt.js";
@@ -33,7 +34,7 @@ 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.7.0";
+export const VERSION = "0.9.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";
@@ -44,15 +45,39 @@ 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 };
+export const XLAYER = "eip155:196";
+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, xlayer: XLAYER };
 
 // 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 ALGORAND_USDC = { [algorandId(ALGORAND)]: "31566704", [algorandId(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" };
+// On X Layer only USD₮0 (what most sellers there ask for) and the USDC x402 Doctor checks against (both 6 decimals,
+// EIP-3009), never OKB or another token that calls itself USDC. @x402/evm has no default asset there, so x402's
+// spend controls only let these through with an allowedAssets entry, capped at the budget (see safeFetch).
+const XLAYER_DOLLARS = {
+  [XLAYER]: ["0x779ded0c9e1022225f8e0630b35a9b54be713736", "0x74b7f16337b8972027f6196a17a631ac6de26d22"],
+};
+
+// Algorand by its CAIP-2 id: the first 32 characters of the genesis hash. Sellers name it either way (the whole hash,
+// or since @x402/avm 2.29.0 only the short id), so networks are compared by this.
+function algorandId(network) {
+  return typeof network === "string" && network.startsWith("algorand:") ? network.slice(0, 41) : network;
+}
+
+// @x402/avm 2.29.0's ExactAvmScheme refuses the whole-hash form, which most Algorand sellers still use (2.28.0 took
+// both). This hands the scheme the short id; the payment still names the seller's own network (x402 puts the
+// seller's option in `accepted`), so either kind of seller can be paid. createSafeFetch wraps Algorand schemes in it.
+export function anyAlgorandId(scheme) {
+  return Object.assign(Object.create(scheme), {
+    createPaymentPayload: (version, requirements, context) =>
+      scheme.createPaymentPayload(version, { ...requirements, network: algorandId(requirements.network) }, context),
+    ...(typeof scheme.findDefaultAsset === "function" && { findDefaultAsset: (asset, network) => scheme.findDefaultAsset(asset, algorandId(network)) }),
+  });
+}
 
 // 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.
@@ -77,17 +102,26 @@ 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;
+  const on = (accepts ?? []).filter((a) => algorandId(a?.network) === algorandId(network));
+  const usdc = ALGORAND_USDC[algorandId(network)];
+  if (usdc) return on.find((a) => String(a.asset) === usdc) ?? 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 (XLAYER_DOLLARS[network]) {
+    return on.find((a) => XLAYER_DOLLARS[network].includes(String(a.asset ?? "").toLowerCase())
+      && /^\d+$/.test(String(a.amount)) && Number(a.amount) > 0 && Number(a.amount) / 1e6 <= 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;
+  // Base and other EVM chains: "exact" first (what most clients register), then "auth-capture" (Coinbase's escrow:
+  // the buyer signs once, the USDC is held and only captured when the seller delivers, e.g. Atom's domain checkout).
+  // Either is paid only if your register() added its scheme, and both stay within the budget (x402's spend controls
+  // read the amount, which for auth-capture is the most that can be captured).
+  return on.find((a) => a?.scheme === "exact") ?? on.find((a) => a?.scheme === "auth-capture") ?? on[0] ?? null;
 }
 
 export class SafePayError extends Error {
@@ -108,6 +142,13 @@ export function usdCap(maxUsd) {
   return `$${Number(n.toFixed(6))}`;
 }
 
+// x402 spend controls for X Layer's dollars: each one allowed up to the budget in atomic units (6 decimals).
+function xlayerAllowance(network, cap) {
+  if (!XLAYER_DOLLARS[network]) return {};
+  const atomic = String(Math.round(Number(String(cap).replace(/^\$/, "")) * 1e6));
+  return { allowedAssets: XLAYER_DOLLARS[network].map((asset) => ({ network, asset, maxAmountPerPayment: atomic })) };
+}
+
 export function diagnoseUrl(target, { method = "GET", doctorUrl = DOCTOR_URL } = {}) {
   const q = new URLSearchParams({ url: target, method });
   return `${doctorUrl.replace(/\/$/, "")}/api/v1/diagnose?${q}`;
@@ -209,10 +250,23 @@ export function createSafeFetch({
   const makePayingFetch = createPayingFetch ?? ((cap) => {
     const client = new x402Client((_version, accepts) => {
       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" });
+      if (!pick) throw new SafePayError(`no payment option on ${payNetwork}${ALGORAND_USDC[algorandId(payNetwork)] ? " in USDC" : STELLAR_USDC[payNetwork] ? ` in USDC within ${cap}` : XLAYER_DOLLARS[payNetwork] ? ` in USD₮0 or USDC within ${cap}` : RLUSD_ISSUER[payNetwork] ? ` in RLUSD within ${cap}` : ""}`, { code: "no_option" });
       return pick;
-    }).setSpendControls({ maxAmountPerPayment: cap });
-    register(client);
+    }).setSpendControls({ maxAmountPerPayment: cap, ...xlayerAllowance(payNetwork, cap) });
+    // Algorand schemes get anyAlgorandId, so sellers with either network id can be paid.
+    const registering = new Proxy(client, {
+      get(target, prop) {
+        if (prop === "register") {
+          return (network, scheme) => {
+            target.register(network, String(network).startsWith("algorand:") ? anyAlgorandId(scheme) : scheme);
+            return registering;
+          };
+        }
+        const value = Reflect.get(target, prop);
+        return typeof value === "function" ? value.bind(target) : value;
+      },
+    });
+    register(registering);
     return wrapFetchWithPayment(baseFetch, client);
   });
   let preflightFetch;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "x402-safe-fetch",
-  "version": "0.7.0",
+  "version": "0.9.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": {
@@ -29,7 +29,7 @@
   },
   "devDependencies": {
     "@algorandfoundation/algokit-utils": "^10.0.0-alpha.46",
-    "@x402/avm": "^2.28.0",
+    "@x402/avm": "^2.29.0",
     "@x402/evm": "^2.27.0",
     "@x402/fetch": "^2.27.0",
     "@x402/stellar": "^2.28.0",