x402-safe-fetch 0.17.0 → 0.19.0

package/README.md

@@ -23,12 +23,15 @@ npm install x402-safe-fetch @x402/fetch @x402/evm viem
 An agent that works in a terminal (or you) can pay for one API call with one command, with the same checks:
 
 ```sh
+npx x402-safe-fetch connect                         # once: a wallet for this computer, linked to your Fizzl wallet
 npx x402-safe-fetch find "bitcoin price in usd"     # free: who sells it, the price, how often it delivered
 npx x402-safe-fetch check <url>                     # free: the price per network and x402 Doctor's free check; pays nothing
-EVM_PRIVATE_KEY=0x… npx x402-safe-fetch pay <url> --max 0.05 --daily 1
+npx x402-safe-fetch pay <url> --max 0.05 --daily 1
 npx x402-safe-fetch spent                           # what was paid today, and what is left
 ```
 
+**No key to copy.** `connect` makes a wallet for this computer (its key stays in `~/.x402-safe-fetch/wallet.json`, readable by you only) and shows a link and a code: open it on your phone, sign in to [wallet.fizzl.eu](https://wallet.fizzl.eu) and approve. From then on every payment is first reserved on your Fizzl wallet: your limits there apply, and above them you get Approve / Deny on your phone (Telegram or the dashboard) before anything is signed; the key never leaves this computer. Then add a few dollars of USDC on Base to the address it shows (`wallet` shows it again, with the balance): no crypto yet? It also prints a link to buy $5 of USDC with a card at Coinbase, sent straight to that address (the link starts a Coinbase Onramp session through x402 Doctor; you pay Coinbase, Fizzl never holds the money). Or send USDC on Base from Coinbase, a wallet app or an exchange. `init` makes the wallet without linking it, and `EVM_PRIVATE_KEY` still overrides both.
+
 `pay` pays USDC on Base, only when x402 Doctor's preflight says go: the cheapest option within `--max`, all calls of the UTC day together within `--daily` (preflights included), and the paid answer checked for instructions aimed at your agent (`--no-answer-check` turns that off). An endpoint that took a payment without delivering isn't paid again for 30 minutes, also by the next command and whatever is added to its URL. `--method POST --data '{"q":1}'` sends a body, `--dry-run` is `check`, and `--json` prints one line of JSON (with the answer, the transaction hash and the day's spend). Exit code 0 is done, 1 is not paid (a check said no, or a limit), 2 is a usage error. The day's spend is kept in `~/.x402-safe-fetch/state.json` (`X402_SAFE_FETCH_HOME` moves it). Use a dedicated wallet with a few dollars.
 
 ## Use

package/cli.js

@@ -6,16 +6,19 @@
 //
 //   npx x402-safe-fetch find "bitcoin price in usd"        free: who sells it, at what price, and whether it delivers
 //   npx x402-safe-fetch check <url>                        free: the price and x402 Doctor's free check; pays nothing
-//   EVM_PRIVATE_KEY=0x… npx x402-safe-fetch pay <url> --max 0.05 --daily 1
+//   npx x402-safe-fetch connect                            a wallet for this computer, linked to your Fizzl wallet
+//   npx x402-safe-fetch pay <url> --max 0.05 --daily 1
 //   npx x402-safe-fetch spent                              what was paid today, and what is left
 //
-// Pays USDC on Base from EVM_PRIVATE_KEY (use a dedicated wallet with a few dollars). The day's spend and the
+// Pays USDC on Base from this computer's own wallet (init or connect make it; EVM_PRIVATE_KEY overrides it). Linked
+// to a Fizzl Agent Wallet (connect), the owner's limits and approvals apply to every payment (wallet.js). The day's spend and the
 // endpoints that took money without delivering are kept in ~/.x402-safe-fetch/state.json (X402_SAFE_FETCH_HOME
 // moves it), so the limits and the paid-twice guard hold across commands.
 
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { ensureWallet, readWallet, writeWallet, pair, serverSigner, usdcBalance, buyUsdcUrl, WALLET_URL } from "./wallet.js";
 import {
   createSafeFetch, SafePayError, receiptOf, readOffer, usdOfOption, answerCheckOf, purchaseKey, paidTwiceMessage,
   PAID_ERROR_MS, DOCTOR_URL, VERSION,
@@ -26,9 +29,13 @@ const PREFLIGHT_USD = 0.001;
 
 const HELP = `x402-safe-fetch ${VERSION}: pay for an API call from the command line, checked first.
 
+  connect              Start here. Makes a wallet for this computer and links it to your Fizzl wallet
+                       (wallet.fizzl.eu): approve the code on your phone. Your limits and approvals then apply.
+  init                 Only the wallet for this computer, not linked: shows its address and a link to buy USDC with a card.
+  wallet               This computer's wallet: address, USDC balance, and whether it is linked.
   find <need>          Free. Who sells it (Fizzl Buy's pick): URL, price, and how often it delivered.
   check <url>          Free, pays nothing. The price per network and x402 Doctor's free check of the endpoint.
-  pay <url>            Pays one call in USDC on Base from EVM_PRIVATE_KEY, only if x402 Doctor's preflight says go.
+  pay <url>            Pays one call in USDC on Base, only if x402 Doctor's preflight says go.
   spent                What was paid today and what is left of the day's limit.
 
 Options for pay (check takes --method and --data too):
@@ -83,7 +90,7 @@ export function stateStore({ home = process.env.X402_SAFE_FETCH_HOME || path.joi
     fs.mkdirSync(home, { recursive: true, mode: 0o700 });
     fs.writeFileSync(file, JSON.stringify(s, null, 2), { mode: 0o600 });
   }
-  return { file, read, write, now };
+  return { home, file, read, write, now };
 }
 
 function requestInit(flags) {
@@ -133,7 +140,7 @@ async function check(args, { fetch }) {
   return { ok: true, url, status: 402, paid: false, options, doctor };
 }
 
-async function pay(args, { fetch, env, store, createPayingFetch, safeFetchOptions = {} }) {
+async function pay(args, { fetch, env, store, createPayingFetch, safeFetchOptions = {}, say = () => {} }) {
   if (args.flags["dry-run"]) return check(args, { fetch });
   const url = targetUrl(args);
   const init = requestInit(args.flags);
@@ -150,9 +157,12 @@ async function pay(args, { fetch, env, store, createPayingFetch, safeFetchOption
   if (earlier) return { ok: false, url, code: "paid_no_delivery", message: paidTwiceMessage(url, earlier), earlier };
 
   let register;
+  let linked = null; // the Fizzl wallet's signer, when this computer's wallet is linked
   if (!createPayingFetch) {
-    const raw = String(env.EVM_PRIVATE_KEY || "").trim();
-    if (!raw) throw new UsageError("set EVM_PRIVATE_KEY: a dedicated wallet with a few dollars of USDC on Base");
+    const envKey = String(env.EVM_PRIVATE_KEY || "").trim();
+    const own = envKey ? null : readWallet(store.home);
+    const raw = envKey || own?.privateKey;
+    if (!raw) throw new UsageError("no wallet yet: run  npx x402-safe-fetch connect  (or init), or set EVM_PRIVATE_KEY");
     let ExactEvmScheme, privateKeyToAccount;
     try {
       ({ ExactEvmScheme } = await import("@x402/evm/exact/client"));
@@ -161,7 +171,10 @@ async function pay(args, { fetch, env, store, createPayingFetch, safeFetchOption
       throw new UsageError("paying needs @x402/evm and viem: npx -p x402-safe-fetch -p @x402/evm -p viem x402-safe-fetch pay <url>");
     }
     const account = privateKeyToAccount(raw.startsWith("0x") ? raw : `0x${raw}`);
-    register = (client) => client.register("eip155:8453", new ExactEvmScheme(account));
+    if (own?.server?.key) {
+      linked = serverSigner({ account, server: own.server, fetch, purchase: { url, description: "x402-safe-fetch pay" }, onWait: (summary) => say(`Waiting for your approval (${summary}): check Telegram or ${own.server.url}`) });
+    }
+    register = (client) => client.register("eip155:8453", new ExactEvmScheme(linked ?? account));
   }
 
   let preflights = 0;
@@ -194,7 +207,7 @@ async function pay(args, { fetch, env, store, createPayingFetch, safeFetchOption
   const verdict = () => preflight && { verdict: preflight.verdict, summary: preflight.summary };
 
   try {
-    const res = await safeFetch(url, init);
+    const res = await safeFetch(url, init).finally(() => linked?.finish("x402-safe-fetch"));
     const text = await res.text();
     const receipt = receiptOf(res);
     // A response after a preflight means the endpoint was paid (or a payment was sent): a 2xx clears it, anything else
@@ -211,12 +224,43 @@ async function pay(args, { fetch, env, store, createPayingFetch, safeFetchOption
       ...(delivered ? {} : { code: "not_delivered", message: `paid, but the endpoint answered HTTP ${res.status}; it won't be paid again for 30 minutes` }),
     };
   } catch (err) {
+    const refused = linked?.state.denied;
+    if (refused) {
+      const totals = settle(null);
+      return { ok: false, url, code: refused.code, message: `not paid: your Fizzl wallet says no: ${refused.summary}`, preflight: verdict(), ...totals };
+    }
     if (!(err instanceof SafePayError)) throw err;
     const totals = settle(null);
     return { ok: false, url, code: err.code, message: err.message, preflight: verdict() ?? (err.preflight ? { verdict: err.preflight.verdict, summary: err.preflight.summary } : null), reasons: (err.preflight?.reasons || []).filter((r) => r.level !== "info").map((r) => ({ level: r.level, code: r.code, message: r.message })), ...totals };
   }
 }
 
+async function init(args, { store, fetch }) {
+  const { wallet, created } = await ensureWallet(store.home);
+  const usdc = await usdcBalance(wallet.address, { fetch });
+  return { ok: true, created, address: wallet.address, usdc_base: usdc, buy_usdc_url: buyUsdcUrl(wallet.address), linked: wallet.server ? { url: wallet.server.url, agent: wallet.server.agent } : null, file: path.join(store.home, "wallet.json") };
+}
+
+async function connect(args, { store, fetch, say, sleep }) {
+  const { wallet } = await ensureWallet(store.home);
+  const url = String(args.flags.server || WALLET_URL);
+  const label = String(args.flags.name || `x402-safe-fetch on ${os.hostname()}`).slice(0, 40);
+  const linked = await pair({
+    address: wallet.address, label, url, fetch, sleep,
+    onCode: ({ code, url: link }) => say(`Open this on your phone and approve:\n\n  ${link}\n\n  code ${code}  (valid 10 minutes)\n\nNo Fizzl wallet yet? One is made when you sign in. Waiting...`),
+  });
+  writeWallet(store.home, { ...wallet, server: linked });
+  const usdc = await usdcBalance(wallet.address, { fetch });
+  return { ok: true, address: wallet.address, linked: { url: linked.url, agent: linked.agent }, usdc_base: usdc, buy_usdc_url: buyUsdcUrl(wallet.address) };
+}
+
+async function walletInfo(args, { store, fetch }) {
+  const wallet = readWallet(store.home);
+  if (!wallet) return { ok: false, code: "no_wallet", message: "no wallet yet: run  npx x402-safe-fetch connect  (or init)" };
+  const usdc = await usdcBalance(wallet.address, { fetch });
+  return { ok: true, address: wallet.address, usdc_base: usdc, buy_usdc_url: buyUsdcUrl(wallet.address), linked: wallet.server ? { url: wallet.server.url, agent: wallet.server.agent } : null };
+}
+
 function spent(args, { store }) {
   const s = store.read();
   const daily = money(args.flags.daily, "daily") ?? 1;
@@ -252,6 +296,20 @@ function text(cmd, r) {
       if (r.status && r.body !== undefined) lines.push(typeof r.body === "string" ? r.body.slice(0, 600) : JSON.stringify(r.body).slice(0, 600));
     }
     if (r.spent_today_usd !== undefined) lines.push(`Today: $${r.spent_today_usd} of $${r.daily_limit_usd}`);
+  } else if (cmd === "init" || cmd === "connect" || cmd === "wallet") {
+    if (!r.ok) return r.message;
+    if (cmd === "init" && r.created) lines.push("Made a wallet for this computer (the key stays here, readable by you only).");
+    if (cmd === "connect") lines.push(`Linked to your Fizzl wallet${r.linked?.agent ? ` as "${r.linked.agent}"` : ""}: your limits and approvals now apply.`);
+    lines.push(`Address: ${r.address}`, `USDC on Base: ${r.usdc_base === null ? "?" : `$${r.usdc_base}`}`);
+    if (cmd !== "connect") lines.push(r.linked ? `Linked to ${r.linked.url}${r.linked.agent ? ` as "${r.linked.agent}"` : ""}` : "Not linked to a Fizzl wallet (run connect for limits and phone approvals).");
+    if (!r.usdc_base) {
+      lines.push(
+        "To pay, add a few dollars of USDC on Base to the address above:",
+        `  with a card (Coinbase, $5; open it in your browser): ${r.buy_usdc_url}`,
+        "  or send USDC from Coinbase, a wallet app or an exchange (choose the Base network).",
+      );
+    }
+    lines.push('Then: npx x402-safe-fetch find "what you need"');
   } else if (cmd === "spent") {
     lines.push(`${r.day}: $${r.spent_today_usd} paid in ${r.calls} call(s), $${r.left_usd} left of $${r.daily_limit_usd}`);
     if (r.blocked_endpoints.length) lines.push("Not paid again for now (took money without delivering):", ...r.blocked_endpoints.map((b) => `  ${b}`));
@@ -259,14 +317,15 @@ function text(cmd, r) {
   return lines.join("\n");
 }
 
-export async function main(argv, { fetch = globalThis.fetch, env = process.env, store = stateStore(), createPayingFetch, safeFetchOptions, out = console.log, err = console.error } = {}) {
+export async function main(argv, { fetch = globalThis.fetch, env = process.env, store = stateStore(), createPayingFetch, safeFetchOptions, sleep, out = console.log, err = console.error } = {}) {
   const args = parseArgs(argv);
   const cmd = args._[0];
   if (!cmd || args.flags.help || cmd === "help") { out(HELP); return cmd || args.flags.help ? 0 : 2; }
-  const commands = { find, check, pay, spent };
+  const commands = { connect, init, wallet: walletInfo, find, check, pay, spent };
   if (!commands[cmd]) { err(`unknown command "${cmd}"\n\n${HELP}`); return 2; }
   try {
-    const r = await commands[cmd](args, { fetch, env, store, createPayingFetch, safeFetchOptions });
+    const say = args.flags.json ? () => {} : (s) => err(s);
+    const r = await commands[cmd](args, { fetch, env, store, createPayingFetch, safeFetchOptions, say, sleep });
     out(args.flags.json ? JSON.stringify(r) : text(cmd === "pay" && args.flags["dry-run"] ? "check" : cmd, r));
     return r.ok ? 0 : 1;
   } catch (e) {

package/index.js

@@ -51,7 +51,7 @@ export const PRESIGN_GUARD_URL = "https://presign-guard.fizzl.eu";
 export const INJECTION_CAP = "$0.02"; // presign-guard's injection check costs $0.01; never more than twice that
 // The header a checked answer carries: green, orange, red (only with onInjection "flag" or a function) or unchecked.
 export const ANSWER_CHECK_HEADER = "x-answer-check";
-export const VERSION = "0.17.0";
+export const VERSION = "0.19.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";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "x402-safe-fetch",
-  "version": "0.17.0",
+  "version": "0.19.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",
   "bin": {
@@ -21,6 +21,7 @@
   "files": [
     "index.js",
     "cli.js",
+    "wallet.js",
     "receipt.js",
     "paid-guard.js",
     "hook.js",

package/wallet.js

@@ -0,0 +1,144 @@
+// The command line's own wallet, and its link to a Fizzl Agent Wallet (wallet.fizzl.eu).
+//
+// init makes a dedicated wallet for the command line: a new key in ~/.x402-safe-fetch/wallet.json (readable by you
+// only), so nobody has to paste a private key. connect links that wallet to the owner's Fizzl Agent Wallet with a
+// code the owner approves on their phone (the same link Claude Desktop's wallet uses: /v1/pair). Once linked, every
+// payment is first reserved on the wallet server: the owner's limits apply, and above them the owner is asked
+// (Telegram or the dashboard) before anything is signed. The key never leaves this computer.
+
+import fs from "node:fs";
+import path from "node:path";
+import { SafePayError } from "./index.js";
+
+export const WALLET_URL = "https://wallet.fizzl.eu";
+export const BASE_USDC = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
+const BASE_RPC = "https://mainnet.base.org";
+export const ONRAMP_URL = "https://x402-doctor.fizzl.eu/api/onramp";
+
+// A link to buy USDC on Base with a card at Coinbase, delivered to `address`. Each visit starts a new Coinbase session
+// (x402 Doctor asks Coinbase Onramp for it); the buyer pays Coinbase and Fizzl never holds the money.
+export function buyUsdcUrl(address, { amount = 5 } = {}) {
+  return `${ONRAMP_URL}?${new URLSearchParams({ address, amount: String(amount) })}`;
+}
+
+export function walletFile(home) {
+  return path.join(home, "wallet.json");
+}
+
+export function readWallet(home) {
+  try {
+    const w = JSON.parse(fs.readFileSync(walletFile(home), "utf8"));
+    return /^0x[0-9a-fA-F]{64}$/.test(w?.privateKey ?? "") ? w : null;
+  } catch {
+    return null;
+  }
+}
+
+export function writeWallet(home, wallet) {
+  fs.mkdirSync(home, { recursive: true, mode: 0o700 });
+  const file = walletFile(home);
+  fs.writeFileSync(file, JSON.stringify(wallet, null, 2), { mode: 0o600 });
+  try { fs.chmodSync(file, 0o600); } catch { /* not on every file system */ }
+}
+
+// A wallet for this computer: the existing one, or a new key. Needs viem (a peer dependency of x402-safe-fetch).
+export async function ensureWallet(home) {
+  const existing = readWallet(home);
+  if (existing) return { wallet: existing, created: false };
+  const { generatePrivateKey, privateKeyToAccount } = await import("viem/accounts");
+  const privateKey = generatePrivateKey();
+  const wallet = { address: privateKeyToAccount(privateKey).address, privateKey, createdAt: new Date().toISOString() };
+  writeWallet(home, wallet);
+  return { wallet, created: true };
+}
+
+// USDC on Base held by `address`, in dollars (null when the network can't be read).
+export async function usdcBalance(address, { fetch = globalThis.fetch, rpc = BASE_RPC } = {}) {
+  try {
+    const data = `0x70a08231${address.slice(2).toLowerCase().padStart(64, "0")}`;
+    const res = await fetch(rpc, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "eth_call", params: [{ to: BASE_USDC, data }, "latest"] }) });
+    const j = await res.json();
+    return typeof j?.result === "string" && j.result.startsWith("0x") ? Number(BigInt(j.result)) / 1e6 : null;
+  } catch {
+    return null;
+  }
+}
+
+async function call(fetch, base, key, method, p, body) {
+  const res = await fetch(`${base}${p}`, {
+    method,
+    headers: { ...(key ? { authorization: `Bearer ${key}` } : {}), "content-type": "application/json", accept: "application/json" },
+    body: body === undefined ? undefined : JSON.stringify(body, (_k, v) => (typeof v === "bigint" ? v.toString() : v)),
+  });
+  const data = await res.json().catch(() => null);
+  if (!res.ok) throw new Error(`wallet server ${p}: ${data?.message ?? data?.error ?? `HTTP ${res.status}`}`);
+  return data;
+}
+
+/**
+ * Links this wallet to a Fizzl Agent Wallet: asks for a code, shows it (onCode), and waits until the owner approves it
+ * where they are signed in. Returns { url, key, agent }. The code is useless without the token kept here.
+ */
+export async function pair({ address, label = "x402-safe-fetch", url = WALLET_URL, fetch = globalThis.fetch, onCode, sleep = (ms) => new Promise((r) => setTimeout(r, ms)), now = Date.now } = {}) {
+  const base = url.replace(/\/$/, "");
+  const start = await call(fetch, base, null, "POST", "/v1/pair/start", { address, label });
+  if (!start?.code || !start?.token) throw new Error("wallet server: no pairing code");
+  const link = start.url || `${base}/pair?code=${start.code}`;
+  onCode?.({ code: start.code, url: link, expiresIn: start.expiresIn ?? 600 });
+  const until = now() + (Number(start.expiresIn) || 600) * 1000;
+  const every = Math.max(1, Number(start.interval) || 3) * 1000;
+  while (now() < until) {
+    await sleep(every);
+    const p = await call(fetch, base, null, "POST", "/v1/pair/poll", { token: start.token });
+    if (p?.status === "linked" && typeof p.key === "string") return { url: base, key: p.key, agent: p.agent ?? null };
+  }
+  throw new Error("the code expired before it was approved (10 minutes); run connect again");
+}
+
+/**
+ * A signer that asks the owner's wallet server before each signature (reserve), waits for the owner's approval when
+ * a limit is reached, and reports what was signed afterwards (finish). Throws SafePayError wallet_denied or
+ * wallet_paused when the server says no; `denied` keeps the last refusal for the caller.
+ */
+export function serverSigner({ account, server, fetch = globalThis.fetch, purchase, onWait, sleep = (ms) => new Promise((r) => setTimeout(r, ms)), now = Date.now }) {
+  const base = server.url.replace(/\/$/, "");
+  const reserved = [];
+  const state = { denied: null };
+  const deny = (code, summary) => {
+    state.denied = { code, summary };
+    throw new SafePayError(`not paid: your Fizzl wallet says no: ${summary}`, { code });
+  };
+  return {
+    address: account.address,
+    state,
+    async signTypedData(typedData) {
+      const { domain, types, primaryType, message } = typedData;
+      const request = { type: "signature", chainId: Number(domain?.chainId ?? 8453), typedData: { domain, types, primaryType, message } };
+      let r = await call(fetch, base, server.key, "POST", "/v1/reserve", { method: "signTypedData", request, verdict: null, purchase });
+      if (r.status === "pending") {
+        onWait?.(r.summary);
+        const deadline = (r.expiresAt ?? now() + 600_000) + 10_000;
+        let a = null;
+        while (now() < deadline) {
+          a = await call(fetch, base, server.key, "GET", `/v1/approvals/${encodeURIComponent(r.approvalId)}?wait=25`);
+          if (a.status !== "pending") break;
+          await sleep(1000);
+        }
+        if (a?.status === "approved") r = { status: "ok", entries: a.entries ?? [], purchaseId: a.purchaseId ?? null };
+        else deny("wallet_denied", `${r.summary} (${a?.status === "denied" ? "denied by the owner" : "no answer in time"})`);
+      }
+      if (r.status === "paused") deny("wallet_paused", r.summary || "paused");
+      if (r.status === "denied") deny("wallet_denied", r.summary || "over a hard limit");
+      if (r.status !== "ok") throw new Error(`wallet server: unexpected answer ${r.status}`);
+      reserved.push({ entries: r.entries ?? [], purchaseId: r.purchaseId ?? null });
+      return account.signTypedData(typedData);
+    },
+    // After the call: every signed payment counts as spent (a signed authorization can be settled by the seller).
+    async finish(result) {
+      for (const r of reserved.splice(0)) {
+        if (!r.entries.length) continue;
+        await call(fetch, base, server.key, "POST", "/v1/spent", { entries: r.entries, result: String(result ?? ""), ...(r.purchaseId ? { purchaseId: r.purchaseId } : {}) }).catch(() => {});
+      }
+    },
+  };
+}