x402-safe-fetch 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Frits Zwager
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,69 @@
+# x402-safe-fetch
+
+A `fetch` for AI agents that checks an unknown x402 endpoint before paying it.
+
+A free endpoint is answered as is. For a paid one (HTTP 402), your agent first pays **$0.001** for an [x402 Doctor](https://x402-doctor.onrender.com) preflight and acts on it:
+
+| Preflight | What `safeFetch` does |
+|---|---|
+| `go` | Pays the endpoint, never more than `maxUsd` |
+| `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.
+
+## Install
+
+```sh
+npm install x402-safe-fetch @x402/fetch @x402/evm viem
+```
+
+## Use
+
+```js
+import { createSafeFetch, SafePayError } from "x402-safe-fetch";
+import { ExactEvmScheme } from "@x402/evm/exact/client";
+import { privateKeyToAccount } from "viem/accounts";
+
+const account = privateKeyToAccount(process.env.EVM_PRIVATE_KEY); // a dedicated wallet with a few dollars of USDC
+
+const safeFetch = createSafeFetch({
+  register: (client) => client.register("eip155:8453", new ExactEvmScheme(account)),
+  maxUsd: 0.05,          // budget per endpoint call
+  onCaution: "stop",     // or "pay", or async (preflight) => askUser(preflight.summary)
+  trusted: ["api.my-own-service.com"],
+});
+
+try {
+  const res = await safeFetch("https://ichimoku-signal.onrender.com/signal/BTC-USDT");
+  console.log(await res.json());
+} catch (err) {
+  if (err instanceof SafePayError) console.log(err.code, err.message, err.preflight?.reasons);
+  else throw err;
+}
+```
+
+Solana works the same way: `network: "solana"` and register an `ExactSvmScheme` from `@x402/svm/exact/client` with a `@solana/kit` signer.
+
+## 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 |
+| `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 |
+
+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.
+
+## Costs and limits
+
+- $0.001 per preflight (once per endpoint per 10 minutes), plus the endpoint's own price.
+- 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.
+
+Try it without code first: [safe-pay](../safe-pay) is a runnable script with the same logic. MIT licensed.

package/index.d.ts

@@ -0,0 +1,47 @@
+import type { x402Client } from "@x402/fetch";
+
+export declare const DOCTOR_URL: string;
+export declare const PREFLIGHT_CAP: string;
+export declare const BASE: "eip155:8453";
+export declare const SOLANA: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp";
+
+/** The x402 Doctor preflight: see https://x402-doctor.onrender.com/openapi.json */
+export interface Preflight {
+  verdict: "go" | "caution" | "no_go";
+  summary?: string;
+  reasons?: Array<{ level: string; code?: string; message: string }>;
+  signals?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+export declare class SafePayError extends Error {
+  code: "no_go" | "caution" | "preflight_failed" | "no_option";
+  preflight: Preflight | null;
+  url: string | null;
+}
+
+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. */
+  network?: string;
+  /** Budget per endpoint call in USD. Default 0.05. */
+  maxUsd?: number | string;
+  /** What to do on a caution verdict. Default "stop". */
+  onCaution?: "stop" | "pay" | ((preflight: Preflight) => boolean | Promise<boolean>);
+  /** 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. */
+  cacheMs?: number;
+  doctorUrl?: string;
+  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>;
+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 receiptOf(response: Response): { transaction?: string; network?: string; success?: boolean; [key: string]: unknown } | null;

package/index.js

@@ -0,0 +1,165 @@
+// x402-safe-fetch: a fetch for agents that checks an unknown x402 endpoint
+// before paying it.
+//
+// A free endpoint is answered as is. For a paid one (HTTP 402), the agent first
+// pays $0.001 for an x402 Doctor preflight and acts on it:
+//   no_go   → throws SafePayError (the payment would fail, is over budget, or
+//             should not be made); the endpoint is not paid
+//   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.
+//
+// Payments use @x402/fetch with the schemes you register (your keys stay in
+// your code): register: (client) => client.register("eip155:8453", new ExactEvmScheme(account))
+
+import { wrapFetchWithPayment, x402Client, decodePaymentResponseHeader } from "@x402/fetch";
+
+export const DOCTOR_URL = "https://x402-doctor.onrender.com";
+export const PREFLIGHT_CAP = "$0.002"; // the preflight costs $0.001; never more than twice that
+export const BASE = "eip155:8453";
+export const SOLANA = "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp";
+const NETWORK_ALIASES = { base: BASE, solana: SOLANA };
+
+export class SafePayError extends Error {
+  /** code: "no_go" | "caution" | "preflight_failed" | "no_option" */
+  constructor(message, { code, preflight = null, url = null } = {}) {
+    super(message);
+    this.name = "SafePayError";
+    this.code = code;
+    this.preflight = preflight;
+    this.url = url;
+  }
+}
+
+// A USD budget as the spend-control string x402 expects: 0.05 → "$0.05".
+export function usdCap(maxUsd) {
+  const n = Number(String(maxUsd).replace(/^\$/, ""));
+  if (!(n > 0) || !Number.isFinite(n)) throw new TypeError("maxUsd must be a positive number of US dollars, e.g. 0.05");
+  return `$${Number(n.toFixed(6))}`;
+}
+
+export function preflightUrl(target, { method = "GET", maxUsd, network, doctorUrl = DOCTOR_URL } = {}) {
+  const q = new URLSearchParams({ url: target, method });
+  if (maxUsd !== undefined) q.set("max_usd", String(maxUsd).replace(/^\$/, ""));
+  if (network) q.set("network", network);
+  return `${doctorUrl.replace(/\/$/, "")}/api/v1/preflight?${q}`;
+}
+
+// The transaction of a paid response (PAYMENT-RESPONSE header), or null.
+export function receiptOf(response) {
+  const header = response?.headers?.get?.("payment-response");
+  if (!header) return null;
+  try {
+    return decodePaymentResponseHeader(header);
+  } catch {
+    return null;
+  }
+}
+
+function hostOf(value) {
+  try {
+    return new URL(value.includes("://") ? value : `https://${value}`).host.toLowerCase();
+  } catch {
+    return null;
+  }
+}
+
+function requestOf(input, init) {
+  if (typeof Request !== "undefined" && input instanceof Request) {
+    throw new TypeError("pass the URL and an init object, not a Request (the body is sent up to three times)");
+  }
+  const body = init?.body;
+  if (body && typeof body === "object" && (typeof body.getReader === "function" || typeof body[Symbol.asyncIterator] === "function")) {
+    throw new TypeError("use a string, Buffer or URLSearchParams body: a stream cannot be sent again after the 402");
+  }
+  return { url: String(input), method: String(init?.method ?? "GET").toUpperCase() };
+}
+
+/**
+ * @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 {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 {string} [options.doctorUrl]
+ * @param {typeof fetch} [options.fetch]  the underlying fetch (default globalThis.fetch)
+ * @param {(cap: string) => typeof fetch} [options.createPayingFetch]  advanced/testing: a paying fetch capped at `cap`
+ * @param {() => number} [options.now]
+ */
+export function createSafeFetch({
+  register,
+  network = BASE,
+  maxUsd = 0.05,
+  onCaution = "stop",
+  trusted = [],
+  onPreflight,
+  cacheMs = 10 * 60 * 1000,
+  doctorUrl = DOCTOR_URL,
+  fetch: baseFetch = globalThis.fetch,
+  createPayingFetch,
+  now = Date.now,
+} = {}) {
+  const payNetwork = NETWORK_ALIASES[network] ?? network;
+  const budget = usdCap(maxUsd);
+  if (!createPayingFetch && typeof register !== "function") {
+    throw new TypeError("register is required: (client) => client.register(network, scheme)");
+  }
+  if (!["stop", "pay"].includes(onCaution) && typeof onCaution !== "function") {
+    throw new TypeError('onCaution must be "stop", "pay" or a function');
+  }
+  const trustedHosts = new Set(trusted.map(hostOf).filter(Boolean));
+
+  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" });
+      return pick;
+    }).setSpendControls({ maxAmountPerPayment: cap });
+    register(client);
+    return wrapFetchWithPayment(baseFetch, client);
+  });
+  let preflightFetch;
+  let endpointFetch;
+  const payPreflight = (...args) => (preflightFetch ??= makePayingFetch(PREFLIGHT_CAP))(...args);
+  const payEndpoint = (...args) => (endpointFetch ??= makePayingFetch(budget))(...args);
+
+  const verdicts = new Map();
+  async function preflightFor(url, method) {
+    const key = `${method} ${url}`;
+    const hit = verdicts.get(key);
+    if (hit && hit.expires > now()) return { preflight: hit.preflight, cached: true };
+    const res = await payPreflight(preflightUrl(url, { method, maxUsd: budget, network: payNetwork, doctorUrl }), { headers: { accept: "application/json" } });
+    const preflight = await res.json().catch(() => null);
+    if (!res.ok || !preflight?.verdict) {
+      throw new SafePayError(`preflight failed (HTTP ${res.status}); the endpoint was not paid`, { code: "preflight_failed", preflight, url });
+    }
+    verdicts.set(key, { preflight, expires: now() + cacheMs });
+    if (verdicts.size > 1000) verdicts.delete(verdicts.keys().next().value);
+    return { preflight, cached: false };
+  }
+
+  return async function safeFetch(input, init = {}) {
+    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 payEndpoint(url, init);
+
+    const { preflight, cached } = await preflightFor(url, method);
+    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 });
+    if (preflight.verdict === "caution") {
+      const ok = onCaution === "pay" || (typeof onCaution === "function" && (await onCaution(preflight)) === true);
+      if (!ok) throw new SafePayError(`not paid (caution): ${why}`, { code: "caution", preflight, url });
+    } else if (preflight.verdict !== "go") {
+      throw new SafePayError(`not paid: unknown verdict ${preflight.verdict}`, { code: "preflight_failed", preflight, url });
+    }
+    return payEndpoint(url, init);
+  };
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "x402-safe-fetch",
+  "version": "0.1.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"
+    }
+  },
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "peerDependencies": {
+    "@x402/fetch": "^2.27.0"
+  },
+  "devDependencies": {
+    "@x402/evm": "^2.27.0",
+    "@x402/fetch": "^2.27.0",
+    "viem": "^2.56.9"
+  },
+  "keywords": [
+    "x402",
+    "agents",
+    "payments",
+    "fetch",
+    "preflight",
+    "usdc",
+    "base",
+    "solana"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Fizzl13/x402-examples.git",
+    "directory": "safe-fetch"
+  },
+  "homepage": "https://github.com/Fizzl13/x402-examples/tree/main/safe-fetch#readme",
+  "license": "MIT"
+}