@wafermapxyz/cli 0.4.10 → 0.4.12

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.4.12 (16 Nov 2026)
+
+**`wafermap call <llm> --metered`: pay only the tokens the model used.**
+
+- Signs one ceiling (x402 scheme `upto`, a Permit2 transfer of at most that much) instead of the flat price. After the model finishes, Wafermap settles only the input and output tokens it reported, never more than the ceiling and never less than $0.001. The confirmation shows the ceiling; the receipt line shows the token counts, what was charged and what was signed.
+- USDC on `base`, `arbitrum` or `polygon` (pick one with `--network`). A wallet that never approved Permit2 for USDC signs an EIP-2612 permit with the payment, so no gas and no extra transaction is needed.
+- The signature can only be spent by the x402 upto proxy (its address is fixed in the client), only to the quote's recipient and only through the facilitator named in the quote, and it expires after at most 5 minutes. Spending caps count the full ceiling, because that is what was signed.
+- Works with `--stream`. Cannot be combined with `--pay wafermap`.
+- SDK: `call(id, input, { metered: true })`; the receipt carries `metered` (`inputTokens`, `outputTokens`, `estimated`, `ceilingUsd`, `chargedUsd`). MCP: `wafermap_call` takes `metered`.
+
+## 0.4.11 (15 Nov 2026)
+
+**`wafermap statement`: a monthly statement you can check against the chains.**
+
+- `wafermap statement --month 2026-11 --out statement.json` downloads one month of this wallet's payments to Wafermap and to marketplace sellers (EVM and Solana sides together), from https://wafermap.xyz/api/statement. `--csv` gives the accounting version; without `--out` it prints the lines and the total.
+- `wafermap statement --verify statement.json` reads every transaction from its own chain, not from Wafermap: an EVM line passes only if the receipt holds a Transfer of exactly that amount of that token from the payer to the recipient; a Solana line only if the transaction succeeded and moved exactly that amount between those two owners. It also checks that the totals add up to the lines, and exits with code 2 on any mismatch, failed or missing transaction. Public RPCs by default; set `WAFERMAP_RPC_<NETWORK>` to use your own.
+- Works on statements downloaded anywhere: the Wallet page, a team owner's statement from /teams, or the API.
+- SDK: `fetchStatement`, `parseStatement`, `verifyStatement`, `verifyLine`.
+
 ## 0.4.10 (12 Nov 2026)
 
 **`wafermap discover` shows the price on every network a service accepts.**

package/README.md

@@ -33,6 +33,8 @@ wafermap discover weather
 wafermap pay https://x402.agentindex.world/weather city=Jakarta
 wafermap swap 0.01 ETH USDG
 wafermap history
+wafermap statement --month 2026-11 --out nov.json
+wafermap statement --verify nov.json
 ```
 
 Add `--yes` to skip the confirmation prompt (caps still apply), `--network base`, `arbitrum`, `polygon`, `arc`, `soneium` or `solana` to pay in USDC on that network (swaps run on `robinhood` or `base`). Set `WAFERMAP_PASSWORD` to avoid the password prompt in scripts.
@@ -84,6 +86,8 @@ Pass `approve: (a) => boolean` to confirm each payment or swap yourself, and `le
 
 A wallet that holds at least 100,000 $WAFERMAP on Robinhood Chain pays 50% less for Wafermap's own resources when it pays on an EVM network (Robinhood Chain, Base, Arbitrum, Polygon, Arc, Soneium). Nothing to set up: `wafermap call` names the wallet to Wafermap and the quote comes back discounted; the server re-checks the balance of the wallet that signs. Marketplace listings and Solana payments keep the regular price. Check a wallet: https://wafermap.xyz/api/holder?address=0x…, or run `wafermap holder`.
 
+LLM resources can also be **metered**: `wafermap call llama-4-scout prompt="hi" --metered --network base` signs a ceiling (shown before you confirm) and pays only the tokens the model used, at least $0.001, in USDC on Base, Arbitrum or Polygon. No gas needed. Caps count the ceiling. Details: https://wafermap.xyz/docs#metered
+
 LLM resources can **stream**: `wafermap call gemma-4 prompt="hi" --stream` prints the answer as it arrives, and the payment settles only once the model finishes.
 
 Wafermap's own resources can also be **paid in $WAFERMAP at 50% off, and the tokens are burned**: `wafermap approve-wafermap` once (a Permit2 approval, one Robinhood Chain transaction), then `wafermap call <id> --pay wafermap`. Each payment is a Permit2 signature for one exact amount, usable for two minutes only by Wafermap's relayer (fixed in the client), checked against a market price the client reads itself.

package/dist/cli.js

@@ -374,6 +374,36 @@ var init_solana = __esm({
 });
 
 // shared/x402client.ts
+async function signUptoPayment(signer, req, resource, opts = {}) {
+  const fac = String(req.raw?.extra?.facilitatorAddress ?? "");
+  if (!/^0x[0-9a-fA-F]{40}$/.test(fac)) throw new X402Error("bad_quote", "The metered quote names no facilitator. Nothing was signed.");
+  const nonce = BigInt(randomNonce()) >> 8n;
+  const deadline = BigInt(Math.floor(Date.now() / 1e3) + Math.min(req.maxTimeoutSeconds, MAX_METERED_SECONDS));
+  const max = BigInt(req.amount);
+  const witness = { to: req.payTo, facilitator: fac, validAfter: 0n };
+  let signature;
+  try {
+    signature = await signer.signTypedData({ domain: { name: "Permit2", chainId: req.chain.id, verifyingContract: PERMIT2 }, types: UPTO_TYPES, primaryType: "PermitWitnessTransferFrom", message: { permitted: { token: req.asset, amount: max }, spender: UPTO_PROXY, nonce, deadline, witness } });
+  } catch (e) {
+    throw new X402Error("sign_rejected", e?.shortMessage ?? e?.message ?? "Signature rejected.");
+  }
+  let extensions;
+  if (opts.gasless && opts.reader) {
+    const allowance = await opts.reader.allowance(req.chain, signer.address, req.asset).catch(() => 0n);
+    if (allowance < max) {
+      const pn = await opts.reader.permitNonce(req.chain, signer.address, req.asset);
+      let ps;
+      try {
+        ps = await signer.signTypedData({ domain: { name: req.extra.name, version: req.extra.version, chainId: req.chain.id, verifyingContract: req.asset }, types: EIP2612_TYPES, primaryType: "Permit", message: { owner: signer.address, spender: PERMIT2, value: max, nonce: pn, deadline } });
+      } catch (e) {
+        throw new X402Error("sign_rejected", e?.shortMessage ?? e?.message ?? "Signature rejected.");
+      }
+      extensions = { eip2612GasSponsoring: { info: { from: signer.address, asset: req.asset, spender: PERMIT2, amount: max.toString(), nonce: pn.toString(), deadline: deadline.toString(), signature: ps, version: "1" } } };
+    }
+  }
+  const permit2Authorization = { from: signer.address, permitted: { token: req.asset, amount: req.amount }, spender: UPTO_PROXY, nonce: nonce.toString(), deadline: deadline.toString(), witness: { to: req.payTo, facilitator: fac, validAfter: "0" } };
+  return { name: "PAYMENT-SIGNATURE", value: b64encode(JSON.stringify({ x402Version: 2, resource, accepted: req.raw, payload: { signature, permit2Authorization }, ...extensions ? { extensions } : {} })), deadline: Number(deadline) };
+}
 async function wafermapPriceUsd(f = fetch) {
   const res = await f(`https://api.geckoterminal.com/api/v2/simple/networks/robinhood/token_price/${WAFERMAP_TOKEN}`, { headers: { accept: "application/json" }, signal: AbortSignal.timeout(15e3) });
   const j = await res.json().catch(() => null);
@@ -421,12 +451,19 @@ async function readQuote(res) {
   const accepts = [];
   const offered = [];
   let token;
+  const metered = [];
   for (const r of body.accepts) {
     offered.push(`${r.scheme ?? "?"}/${r.network ?? "?"}`);
     if (r?.scheme === TOKEN_SCHEME) {
       token ??= tokenOption(r);
       continue;
     }
+    if (r?.scheme === "upto" && version === 2) {
+      const ch = chainOf(r.network);
+      if (ch && ch.vm === "evm" && String(r.asset ?? "").toLowerCase() === ch.stable.toLowerCase() && /^\d+$/.test(String(r.amount)) && /^0x[0-9a-fA-F]{40}$/.test(String(r.extra?.facilitatorAddress ?? "")) && /^0x[0-9a-fA-F]{40}$/.test(String(r.payTo ?? "")))
+        metered.push({ version, chain: ch, amount: String(r.amount), usd: Number(r.amount) / 1e6, payTo: r.payTo, asset: r.asset, maxTimeoutSeconds: Number(r.maxTimeoutSeconds) || 120, extra: r.extra?.name && r.extra?.version ? { name: String(r.extra.name), version: String(r.extra.version) } : ch.domain, raw: r });
+      continue;
+    }
     const chain = chainOf(r.network);
     if (!chain || r.scheme !== "exact") continue;
     if (chain.vm === "evm" ? String(r.asset ?? "").toLowerCase() !== chain.stable.toLowerCase() : r.asset !== chain.stable) continue;
@@ -440,7 +477,10 @@ async function readQuote(res) {
     accepts.push({ version, chain, amount, usd: Number(amount) / 1e6, payTo: r.payTo, asset: r.asset, maxTimeoutSeconds: Number(r.maxTimeoutSeconds) || 120, extra, raw: r });
   }
   const inputError = body.inputError?.message ? { code: String(body.inputError.code ?? "invalid_input"), message: String(body.inputError.message) } : void 0;
-  return { version, resource: body.resource ?? null, accepts, offered, inputError, ...token ? { token } : {} };
+  const m = body.metered;
+  const meterInfo = m && Number.isFinite(Number(m.ceilingUsd)) ? { inputPer1kTokensUsd: Number(m.inputPer1kTokensUsd), outputPer1kTokensUsd: Number(m.outputPer1kTokensUsd), ceilingUsd: Number(m.ceilingUsd), minimumUsd: Number(m.minimumUsd) } : void 0;
+  const gasless = !!body.extensions?.eip2612GasSponsoring;
+  return { version, resource: body.resource ?? null, accepts, offered, inputError, ...token ? { token } : {}, ...metered.length ? { metered: metered.map((q) => ({ ...q, gasless })) } : {}, ...meterInfo ? { meterInfo } : {} };
 }
 function choose(q, prefer = CHAIN_KEYS) {
   for (const k of prefer) {
@@ -512,6 +552,20 @@ async function x402fetch(url, init, opts) {
     const res2 = await f(url, { ...init, headers: headers2 });
     return { res: res2, paid: { ...signed2, tx: readSettlement(res2)?.tx ?? null } };
   }
+  if (opts.meter) {
+    const pref = (opts.prefer ?? CHAIN_KEYS).filter((k) => k !== "solana");
+    const req2 = pref.map((k) => quote.metered?.find((q) => q.chain.key === k)).find(Boolean);
+    if (!req2) throw new X402Error("metered_not_offered", quote.metered?.length ? `Metered calls are offered on ${quote.metered.map((q) => q.chain.name).join(", ")}; pick one of those networks.` : "This call is not offered as a metered (pay per token) call. Pay the flat price instead.");
+    if (opts.approve) await opts.approve(req2);
+    const signer2 = typeof opts.signer === "function" ? await opts.signer() : opts.signer;
+    const header2 = await signUptoPayment(signer2, req2, quote.resource, { reader: opts.reader, gasless: !!req2.gasless });
+    const signed2 = { req: req2, from: signer2.address, metered: { ceiling: req2.amount, deadline: header2.deadline } };
+    opts.onSigned?.(signed2);
+    const headers2 = new Headers(init.headers);
+    headers2.set(header2.name, header2.value);
+    const res2 = await f(url, { ...init, headers: headers2 });
+    return { res: res2, paid: { ...signed2, tx: readSettlement(res2)?.tx ?? null } };
+  }
   const req = choose(quote, (opts.prefer ?? CHAIN_KEYS).filter((k) => k !== "solana" || opts.solana));
   if (opts.approve) await opts.approve(req);
   const svm = req.chain.vm === "svm";
@@ -524,7 +578,7 @@ async function x402fetch(url, init, opts) {
   const res = await f(url, { ...init, headers });
   return { res, paid: { ...signed, tx: readSettlement(res)?.tx ?? null } };
 }
-var USDC_DOMAIN, PAY_CHAINS, EVM_CHAINS, CHAIN_KEYS, WAFERMAP_TOKEN, PERMIT2, DEAD, TOKEN_SCHEME, WAFERMAP_RELAYERS, TOKEN_VALUE_SLACK, PERMIT_TYPES, X402Error, b64encode, b64decode, TYPES, MAX_VALIDITY_SECONDS, randomNonce;
+var USDC_DOMAIN, PAY_CHAINS, EVM_CHAINS, CHAIN_KEYS, UPTO_PROXY, MAX_METERED_SECONDS, UPTO_TYPES, EIP2612_TYPES, WAFERMAP_TOKEN, PERMIT2, DEAD, TOKEN_SCHEME, WAFERMAP_RELAYERS, TOKEN_VALUE_SLACK, PERMIT_TYPES, X402Error, b64encode, b64decode, TYPES, MAX_VALIDITY_SECONDS, randomNonce;
 var init_x402client = __esm({
   "shared/x402client.ts"() {
     "use strict";
@@ -542,6 +596,35 @@ var init_x402client = __esm({
     ];
     EVM_CHAINS = PAY_CHAINS.filter((c) => c.vm === "evm");
     CHAIN_KEYS = PAY_CHAINS.map((c) => c.key);
+    UPTO_PROXY = "0x4020A4f3b7b90ccA423B9fabCc0CE57C6C240002";
+    MAX_METERED_SECONDS = 300;
+    UPTO_TYPES = {
+      PermitWitnessTransferFrom: [
+        { name: "permitted", type: "TokenPermissions" },
+        { name: "spender", type: "address" },
+        { name: "nonce", type: "uint256" },
+        { name: "deadline", type: "uint256" },
+        { name: "witness", type: "Witness" }
+      ],
+      TokenPermissions: [
+        { name: "token", type: "address" },
+        { name: "amount", type: "uint256" }
+      ],
+      Witness: [
+        { name: "to", type: "address" },
+        { name: "facilitator", type: "address" },
+        { name: "validAfter", type: "uint256" }
+      ]
+    };
+    EIP2612_TYPES = {
+      Permit: [
+        { name: "owner", type: "address" },
+        { name: "spender", type: "address" },
+        { name: "value", type: "uint256" },
+        { name: "nonce", type: "uint256" },
+        { name: "deadline", type: "uint256" }
+      ]
+    };
     WAFERMAP_TOKEN = "0xfda080f64d84c989cfc50ff18253542cfe502db3";
     PERMIT2 = "0x000000000022D473030F116dDEE9F6B43aC78BA3";
     DEAD = "0x000000000000000000000000000000000000dEaD";
@@ -858,7 +941,15 @@ var init_core = __esm({
         this.queue = prev.then(() => held);
         return prev.then(() => release);
       }
-      async paidFetch(kind, what, url, init, network, payIn) {
+      /** Chain reads for a metered payment's EIP-2612 permit: Permit2 allowance and the token's permit nonce. */
+      reader() {
+        const nonces = [{ type: "function", name: "nonces", stateMutability: "view", inputs: [{ name: "owner", type: "address" }], outputs: [{ type: "uint256" }] }];
+        return {
+          allowance: (chain, owner, token) => this.client(chain.key).readContract({ address: token, abi: erc20Abi2, functionName: "allowance", args: [owner, PERMIT2] }),
+          permitNonce: (chain, owner, token) => this.client(chain.key).readContract({ address: token, abi: nonces, functionName: "nonces", args: [owner] })
+        };
+      }
+      async paidFetch(kind, what, url, init, network, payIn, meter) {
         let id = null;
         let release = null;
         const unlock = () => {
@@ -872,10 +963,12 @@ var init_core = __esm({
             prefer: this.prefer(network),
             fetch: this.fetch,
             payIn,
+            meter,
+            reader: meter ? this.reader() : void 0,
             tokenPriceUsd: this.tokenPriceUsd,
             approve: async (req) => {
               release = await this.acquire();
-              await this.gate({ kind, what, usd: req.usd, network: req.chain.key, detail: req.asset === WAFERMAP_TOKEN ? "in $WAFERMAP at 50% off, burned" : `${req.chain.symbol} to ${req.payTo}` });
+              await this.gate({ kind, what, usd: req.usd, network: req.chain.key, detail: req.asset === WAFERMAP_TOKEN ? "in $WAFERMAP at 50% off, burned" : meter ? `at most ${req.chain.symbol} ${req.usd}, charged for the tokens used, to ${req.payTo}` : `${req.chain.symbol} to ${req.payTo}` });
             },
             onSigned: (s) => {
               id = this.booked(kind, what, s);
@@ -963,11 +1056,12 @@ var init_core = __esm({
       }
       async call(id, input = {}, o = {}) {
         const inToken = o.payIn === "wafermap";
+        if (o.metered && inToken) throw new WafermapError("bad_options", "A metered call is paid in USDC; it cannot also be paid in $WAFERMAP.");
         const stream = !!o.onDelta && !inToken;
         if (inToken && id.startsWith("m/")) throw new WafermapError("token_not_offered", "Marketplace listings are paid in USDG or USDC to their seller, not in $WAFERMAP.");
         if (inToken && !await this.wafermapApproved().catch(() => true)) throw new WafermapError("permit2_not_approved", "Paying in $WAFERMAP needs a one-time approval of Permit2. Run `wafermap approve-wafermap` (one transaction on Robinhood Chain, paid in ETH), then call again.");
         const pass = id.startsWith("m/") ? null : await this.holderPass();
-        const go = () => this.paidFetch("resource", id, `${this.baseUrl}/v1/${id}`, { method: "POST", headers: { "content-type": "application/json", "x-wafermap-payer": this.address, ...stream ? { accept: "text/event-stream" } : {}, ...pass ? { [PASS_HEADER]: pass } : {} }, body: JSON.stringify(input) }, o.network, inToken ? "wafermap" : void 0);
+        const go = () => this.paidFetch("resource", id, `${this.baseUrl}/v1/${id}`, { method: "POST", headers: { "content-type": "application/json", "x-wafermap-payer": this.address, ...stream ? { accept: "text/event-stream" } : {}, ...pass ? { [PASS_HEADER]: pass } : {} }, body: JSON.stringify(input) }, o.network, inToken ? "wafermap" : void 0, o.metered);
         const settle = (r2, out2) => {
           if (!r2.paid || !r2.id) return;
           const status = r2.res.status === 402 ? "refused" : r2.res.ok && !out2?.streamError ? "ok" : "failed";
@@ -1288,7 +1382,119 @@ var VERSION;
 var init_version = __esm({
   "src/version.ts"() {
     "use strict";
-    VERSION = "0.4.10";
+    VERSION = "0.4.12";
+  }
+});
+
+// src/statement.ts
+var statement_exports = {};
+__export(statement_exports, {
+  defaultClients: () => defaultClients,
+  fetchStatement: () => fetchStatement,
+  parseStatement: () => parseStatement,
+  verifyLine: () => verifyLine,
+  verifyStatement: () => verifyStatement
+});
+import { createPublicClient as createPublicClient2, getAddress as getAddress3, http as http2, isAddress as isAddress3, parseAbiItem as parseAbiItem2, toEventSelector as toEventSelector2 } from "viem";
+import { arbitrum as arbitrum2, arc as arc2, base as base2, polygon as polygon2, robinhood as robinhood2, soneium as soneium2 } from "viem/chains";
+async function fetchStatement(wallets, month, opts = {}) {
+  const url = `${(opts.baseUrl ?? "https://wafermap.xyz").replace(/\/$/, "")}/api/statement?wallet=${encodeURIComponent(wallets.join(","))}&month=${encodeURIComponent(month)}${opts.csv ? "&format=csv" : ""}`;
+  const r = await fetch(url, { signal: AbortSignal.timeout(opts.timeoutMs ?? 6e4) });
+  if (!r.ok) {
+    const j = await r.json().catch(() => null);
+    throw new Error(j?.error?.message ?? `Statement request failed (${r.status}).`);
+  }
+  return opts.csv ? r.text() : await r.json();
+}
+function parseStatement(text2) {
+  let s;
+  try {
+    s = JSON.parse(text2);
+  } catch {
+    throw new Error("That file is not JSON. Download the JSON statement (not the CSV) to verify it.");
+  }
+  if (s?.kind !== "wafermap-statement" || !Array.isArray(s.lines)) throw new Error("That file is not a Wafermap statement.");
+  return s;
+}
+function defaultClients(env = process.env) {
+  const cache = /* @__PURE__ */ new Map();
+  return {
+    evm: (network) => {
+      const chain = EVM[network];
+      if (!chain) return null;
+      if (!cache.has(network)) cache.set(network, createPublicClient2({ chain, transport: http2(env[ENV_RPC[network]] || void 0, { timeout: 3e4 }) }));
+      return cache.get(network);
+    },
+    solana: (method, params) => solanaRpc(env.WAFERMAP_RPC_SOLANA || SOLANA_PUBLIC_RPC, method, params)
+  };
+}
+async function verifyLine(l, clients) {
+  try {
+    if (!/^\d+$/.test(l.amountUnits)) return "mismatch";
+    const want = BigInt(l.amountUnits);
+    if (l.network.startsWith("solana:")) {
+      const tx = await clients.solana("getTransaction", [l.tx, { encoding: "jsonParsed", maxSupportedTransactionVersion: 0, commitment: "finalized" }]);
+      if (!tx) return "not_found";
+      if (tx.meta?.err) return "failed";
+      const delta = (owner) => {
+        const sum = (xs) => (xs ?? []).filter((b) => b.owner === owner && b.mint === l.token).reduce((a, b) => a + BigInt(b.uiTokenAmount?.amount ?? "0"), 0n);
+        return sum(tx.meta?.postTokenBalances) - sum(tx.meta?.preTokenBalances);
+      };
+      return delta(l.from) === -want && delta(l.to) === want ? "ok" : "mismatch";
+    }
+    const client = clients.evm(l.network);
+    if (!client) return "unsupported";
+    if (!/^0x[0-9a-fA-F]{64}$/.test(l.tx) || !isAddress3(l.token) || !isAddress3(l.from) || !isAddress3(l.to)) return "mismatch";
+    const receipt = await client.getTransactionReceipt({ hash: l.tx }).catch((e) => /not.*found|could not be found/i.test(String(e?.message)) ? null : Promise.reject(e));
+    if (!receipt) return "not_found";
+    if (receipt.status !== "success") return "failed";
+    const hit = receipt.logs.some(
+      (g) => g.address.toLowerCase() === l.token.toLowerCase() && g.topics[0] === TRANSFER && topicAddr(g.topics[1]) === getAddress3(l.from) && topicAddr(g.topics[2]) === getAddress3(l.to) && BigInt(g.data) === want
+    );
+    return hit ? "ok" : "mismatch";
+  } catch {
+    return "error";
+  }
+}
+async function verifyStatement(s, clients = defaultClients(), onLine) {
+  const results = new Array(s.lines.length);
+  let next = 0;
+  await Promise.all(
+    Array.from({ length: 4 }, async () => {
+      while (next < s.lines.length) {
+        const i = next++;
+        results[i] = await verifyLine(s.lines[i], clients);
+        onLine?.(i, results[i]);
+      }
+    })
+  );
+  const usd = (pick) => Math.round(s.lines.reduce((a, l, i) => a + (pick(results[i]) ? Number(l.amountUsd) : 0), 0) * 1e6) / 1e6;
+  const count = (r) => results.filter((x) => x === r).length;
+  const linesUsd = usd(() => true);
+  return {
+    results,
+    lines: s.lines.length,
+    ok: count("ok"),
+    mismatch: count("mismatch"),
+    failed: count("failed"),
+    notFound: count("not_found"),
+    unsupported: count("unsupported"),
+    error: count("error"),
+    confirmedUsd: usd((r) => r === "ok"),
+    linesUsd,
+    // The totals block must add up to the lines it sits next to.
+    totalsMatch: s.totals?.calls === s.lines.length && Math.abs((s.totals?.usd ?? NaN) - linesUsd) < 1e-6
+  };
+}
+var EVM, ENV_RPC, TRANSFER, topicAddr;
+var init_statement = __esm({
+  "src/statement.ts"() {
+    "use strict";
+    init_solana();
+    EVM = { "eip155:4663": robinhood2, "eip155:8453": base2, "eip155:42161": arbitrum2, "eip155:137": polygon2, "eip155:5042": arc2, "eip155:1868": soneium2 };
+    ENV_RPC = { "eip155:4663": "WAFERMAP_RPC_ROBINHOOD", "eip155:8453": "WAFERMAP_RPC_BASE", "eip155:42161": "WAFERMAP_RPC_ARBITRUM", "eip155:137": "WAFERMAP_RPC_POLYGON", "eip155:5042": "WAFERMAP_RPC_ARC", "eip155:1868": "WAFERMAP_RPC_SONEIUM", solana: "WAFERMAP_RPC_SOLANA" };
+    TRANSFER = toEventSelector2(parseAbiItem2("event Transfer(address indexed from, address indexed to, uint256 value)"));
+    topicAddr = (t) => t ? getAddress3(`0x${t.slice(-40)}`) : null;
   }
 });
 
@@ -1392,12 +1598,13 @@ async function runMcp() {
         resource: z.string().describe("Resource id, e.g. market-brief, prediction-markets, stock-signal, flux-2-dev."),
         input: z.record(z.string(), z.any()).optional().describe("Input fields for the resource."),
         network: NET,
-        payIn: z.enum(["stablecoin", "wafermap"]).optional().describe("wafermap: pay Wafermap's own resources in $WAFERMAP at 50% off (the tokens are burned; needs `wafermap approve-wafermap` once). Default: USDG/USDC.")
+        payIn: z.enum(["stablecoin", "wafermap"]).optional().describe("wafermap: pay Wafermap's own resources in $WAFERMAP at 50% off (the tokens are burned; needs `wafermap approve-wafermap` once). Default: USDG/USDC."),
+        metered: z.boolean().optional().describe("LLM resources only: sign a ceiling and pay only the tokens the model used (USDC on base, arbitrum or polygon; no gas needed). Caps count the ceiling.")
       }
     },
-    async ({ resource, input, network, payIn }) => {
+    async ({ resource, input, network, payIn, metered }) => {
       try {
-        return result(await wm.call(resource, input ?? {}, { network, payIn }));
+        return result(await wm.call(resource, input ?? {}, { network, payIn, metered }));
       } catch (e) {
         return failure(e);
       }
@@ -1844,6 +2051,8 @@ Wallet
   wafermap balance                      USDG / USDC and gas on every payment network
   wafermap limits [--per-payment 0.1] [--per-day 1] [--per-swap 25] [--network <net>] [--mcp-swaps on|off] [--mcp-confirm on|off]
   wafermap history [--days 7] [--verify]  payments and swaps from this machine; --verify checks on-chain
+  wafermap statement [--month 2026-11] [--csv] [--out file]  a month of payments to Wafermap and its sellers
+  wafermap statement --verify <file.json>  check every line of a statement against the chain
   wafermap export-key [--solana]        print the private key, or the Solana key for Phantom/Solflare
   wafermap keychain [on|off]            keep the password for \`wafermap mcp\` in the OS keychain, not in plain text
 
@@ -1851,6 +2060,7 @@ Pay
   wafermap resources [words]            Wafermap's pay-per-call catalog
   wafermap call <id> [field=value ...]  run a resource and pay its price  (--json '{...}' for complex input)
   wafermap call <id> ... --pay wafermap pay a Wafermap resource in $WAFERMAP at 50% off (the tokens are burned)
+  wafermap call <llm> ... --metered      pay only the tokens used, up to a ceiling you sign (USDC on base, arbitrum, polygon)
   wafermap call <llm> ... --stream       print the answer as it arrives; you pay only once the model finishes
   wafermap approve-wafermap             one-time approval so the wallet can pay in $WAFERMAP (Robinhood Chain, ETH gas)
   wafermap holder                       what this wallet's $WAFERMAP unlocks: holder price, Pro free calls left today
@@ -1873,7 +2083,7 @@ function parse(argv) {
     if (a.startsWith("--")) {
       const [k, v] = a.slice(2).split("=", 2);
       if (v !== void 0) out.flags[k] = v;
-      else if (argv[i + 1] && !argv[i + 1].startsWith("--") && !["yes", "post", "import", "stream"].includes(k)) out.flags[k] = argv[++i];
+      else if (argv[i + 1] && !argv[i + 1].startsWith("--") && !["yes", "post", "import", "stream", "metered"].includes(k)) out.flags[k] = argv[++i];
       else out.flags[k] = true;
     } else out._.push(a);
   }
@@ -2080,6 +2290,60 @@ Total $${total.toFixed(4)} in ${pays.length} payments. From 0.3.3 every payment
       } else console.log("Add --verify to check on-chain which signed payments were executed.");
       return;
     }
+    case "statement": {
+      const { fetchStatement: fetchStatement2, parseStatement: parseStatement2, verifyStatement: verifyStatement2 } = await Promise.resolve().then(() => (init_statement(), statement_exports));
+      const { readFileSync: readFileSync2, writeFileSync: writeFileSync2 } = await import("node:fs");
+      if (a.flags.verify !== void 0) {
+        const file2 = typeof a.flags.verify === "string" ? a.flags.verify : a._[0];
+        if (!file2) die("Which file? wafermap statement --verify wafermap-statement-2026-11.json");
+        let text2;
+        try {
+          text2 = readFileSync2(file2, "utf8");
+        } catch {
+          die(`Cannot read ${file2}.`);
+        }
+        let st;
+        try {
+          st = parseStatement2(text2);
+        } catch (e) {
+          die(e.message);
+        }
+        console.error(`Checking ${st.lines.length} payments from ${st.month} on-chain\u2026`);
+        const r = await verifyStatement2(st);
+        st.lines.forEach((l, i) => {
+          if (r.results[i] !== "ok") console.log(`${r.results[i].toUpperCase().padEnd(11)} ${l.date.slice(0, 16).replace("T", " ")}  $${l.amountUsd.padEnd(8)} ${l.resource}  ${l.explorer ?? l.tx}`);
+        });
+        console.log(`
+${r.ok} of ${r.lines} payments confirmed on-chain, $${r.confirmedUsd} of $${r.linesUsd}.${r.totalsMatch ? " The totals match the lines." : " The totals block does NOT match the lines."}${st.truncated ? " This statement was cut at 10,000 lines." : ""}`);
+        if (r.ok !== r.lines)
+          console.log(`ok = the transaction moved exactly that amount from the payer to the recipient \xB7 mismatch = it did not \xB7 failed = the transaction reverted \xB7 not_found = no such transaction \xB7 error = the RPC did not answer, try again (set WAFERMAP_RPC_<NETWORK> to your own RPC) \xB7 unsupported = a network this CLI cannot read.`);
+        if (r.mismatch || r.failed || r.notFound || !r.totalsMatch) process.exitCode = 2;
+        return;
+      }
+      const evm = keystoreAddress() ?? die("No wallet yet. Run `wafermap init`, or check a downloaded file with --verify.");
+      const wallets = [evm, ...keystoreSolana() ? [keystoreSolana()] : []];
+      const month = typeof a.flags.month === "string" ? a.flags.month : (/* @__PURE__ */ new Date()).toISOString().slice(0, 7);
+      if (!/^20\d\d-(0[1-9]|1[0-2])$/.test(month)) die("--month must be YYYY-MM, for example 2026-11.");
+      const csv = a.flags.csv === true;
+      const out = await fetchStatement2(wallets, month, { baseUrl: process.env.WAFERMAP_URL, csv, timeoutMs: Number(process.env.WAFERMAP_TIMEOUT_MS) || void 0 });
+      const file = typeof a.flags.out === "string" ? a.flags.out : null;
+      if (typeof out === "string") {
+        if (file) writeFileSync2(file, out);
+        else process.stdout.write(out);
+        if (file) console.error(`Saved ${file}.`);
+        return;
+      }
+      if (file) {
+        writeFileSync2(file, JSON.stringify(out, null, 2) + "\n");
+        console.error(`Saved ${file}. Check it any time with: wafermap statement --verify ${file}`);
+      }
+      if (!file || a.flags.print !== void 0) {
+        for (const l of out.lines) console.log(`${l.date.slice(0, 16).replace("T", " ")}  $${l.amountUsd.padEnd(8)} ${l.network.padEnd(14).slice(0, 14)}  ${l.resource}  ${l.explorer ?? l.tx}`);
+        console.log(`
+${month}: ${out.totals.calls} paid calls, $${out.totals.usd}.${out.lines.length ? " Save it with --out statement.json, then check it with --verify." : ""}`);
+      }
+      return;
+    }
     case "resources": {
       const q = a._.join(" ").toLowerCase();
       const list = await listResources(process.env.WAFERMAP_URL, Number(process.env.WAFERMAP_TIMEOUT_MS) || void 0);
@@ -2103,9 +2367,11 @@ Total $${total.toFixed(4)} in ${pays.length} payments. From 0.3.3 every payment
       const payIn = a.flags.pay === "wafermap" ? "wafermap" : a.flags.pay === void 0 || a.flags.pay === "usd" ? void 0 : die("--pay must be wafermap (or leave it out to pay in USDG/USDC)");
       let streamed = false;
       const onDelta = a.flags.stream === true ? (t) => (streamed = true, process.stdout.write(t)) : void 0;
-      const out = await wm.call(id, inputOf(a, 1), { network: net(a.flags.network), payIn, onDelta });
+      const metered = a.flags.metered === true;
+      const out = await wm.call(id, inputOf(a, 1), { network: net(a.flags.network), payIn, onDelta, metered });
       if (streamed) process.stdout.write("\n");
       if (out.receipt?.asset === "WAFERMAP") console.error(`\u2713 Paid ${out.receipt.amountTokens} $WAFERMAP (\u2248 $${out.receipt.amountUsd}), burned \xB7 ${EXPLORER(out.receipt.network)}/tx/${out.receipt.tx}`);
+      else if (out.receipt?.metered) console.error(`\u2713 Paid $${out.receipt.amountUsd} ${out.receipt.asset} for ${out.receipt.metered.inputTokens} in + ${out.receipt.metered.outputTokens} out tokens${out.receipt.metered.estimated ? " (estimated)" : ""}, signed up to $${out.receipt.metered.ceilingUsd} \xB7 ${EXPLORER(out.receipt.network)}/tx/${out.receipt.tx}`);
       else if (out.receipt) console.error(`\u2713 Paid $${out.receipt.amountUsd} ${out.receipt.asset} \xB7 ${EXPLORER(out.receipt.network)}/tx/${out.receipt.tx}`);
       else if (out.free) console.error(`\u2713 Free call ($WAFERMAP Pro) \xB7 ${out.free.left} of ${out.free.perDay} left today. Nothing was paid.`);
       if (typeof a.flags.out === "string") await saveMedia(out.result, a.flags.out);

package/dist/index.js

@@ -364,6 +364,65 @@ var PAY_CHAINS = [
 ];
 var EVM_CHAINS = PAY_CHAINS.filter((c) => c.vm === "evm");
 var CHAIN_KEYS = PAY_CHAINS.map((c) => c.key);
+var UPTO_PROXY = "0x4020A4f3b7b90ccA423B9fabCc0CE57C6C240002";
+var MAX_METERED_SECONDS = 300;
+var UPTO_TYPES = {
+  PermitWitnessTransferFrom: [
+    { name: "permitted", type: "TokenPermissions" },
+    { name: "spender", type: "address" },
+    { name: "nonce", type: "uint256" },
+    { name: "deadline", type: "uint256" },
+    { name: "witness", type: "Witness" }
+  ],
+  TokenPermissions: [
+    { name: "token", type: "address" },
+    { name: "amount", type: "uint256" }
+  ],
+  Witness: [
+    { name: "to", type: "address" },
+    { name: "facilitator", type: "address" },
+    { name: "validAfter", type: "uint256" }
+  ]
+};
+var EIP2612_TYPES = {
+  Permit: [
+    { name: "owner", type: "address" },
+    { name: "spender", type: "address" },
+    { name: "value", type: "uint256" },
+    { name: "nonce", type: "uint256" },
+    { name: "deadline", type: "uint256" }
+  ]
+};
+async function signUptoPayment(signer, req, resource, opts = {}) {
+  const fac = String(req.raw?.extra?.facilitatorAddress ?? "");
+  if (!/^0x[0-9a-fA-F]{40}$/.test(fac)) throw new X402Error("bad_quote", "The metered quote names no facilitator. Nothing was signed.");
+  const nonce = BigInt(randomNonce()) >> 8n;
+  const deadline = BigInt(Math.floor(Date.now() / 1e3) + Math.min(req.maxTimeoutSeconds, MAX_METERED_SECONDS));
+  const max = BigInt(req.amount);
+  const witness = { to: req.payTo, facilitator: fac, validAfter: 0n };
+  let signature;
+  try {
+    signature = await signer.signTypedData({ domain: { name: "Permit2", chainId: req.chain.id, verifyingContract: PERMIT2 }, types: UPTO_TYPES, primaryType: "PermitWitnessTransferFrom", message: { permitted: { token: req.asset, amount: max }, spender: UPTO_PROXY, nonce, deadline, witness } });
+  } catch (e) {
+    throw new X402Error("sign_rejected", e?.shortMessage ?? e?.message ?? "Signature rejected.");
+  }
+  let extensions;
+  if (opts.gasless && opts.reader) {
+    const allowance = await opts.reader.allowance(req.chain, signer.address, req.asset).catch(() => 0n);
+    if (allowance < max) {
+      const pn = await opts.reader.permitNonce(req.chain, signer.address, req.asset);
+      let ps;
+      try {
+        ps = await signer.signTypedData({ domain: { name: req.extra.name, version: req.extra.version, chainId: req.chain.id, verifyingContract: req.asset }, types: EIP2612_TYPES, primaryType: "Permit", message: { owner: signer.address, spender: PERMIT2, value: max, nonce: pn, deadline } });
+      } catch (e) {
+        throw new X402Error("sign_rejected", e?.shortMessage ?? e?.message ?? "Signature rejected.");
+      }
+      extensions = { eip2612GasSponsoring: { info: { from: signer.address, asset: req.asset, spender: PERMIT2, amount: max.toString(), nonce: pn.toString(), deadline: deadline.toString(), signature: ps, version: "1" } } };
+    }
+  }
+  const permit2Authorization = { from: signer.address, permitted: { token: req.asset, amount: req.amount }, spender: UPTO_PROXY, nonce: nonce.toString(), deadline: deadline.toString(), witness: { to: req.payTo, facilitator: fac, validAfter: "0" } };
+  return { name: "PAYMENT-SIGNATURE", value: b64encode(JSON.stringify({ x402Version: 2, resource, accepted: req.raw, payload: { signature, permit2Authorization }, ...extensions ? { extensions } : {} })), deadline: Number(deadline) };
+}
 var WAFERMAP_TOKEN = "0xfda080f64d84c989cfc50ff18253542cfe502db3";
 var PERMIT2 = "0x000000000022D473030F116dDEE9F6B43aC78BA3";
 var DEAD = "0x000000000000000000000000000000000000dEaD";
@@ -443,12 +502,19 @@ async function readQuote(res) {
   const accepts = [];
   const offered = [];
   let token;
+  const metered = [];
   for (const r of body.accepts) {
     offered.push(`${r.scheme ?? "?"}/${r.network ?? "?"}`);
     if (r?.scheme === TOKEN_SCHEME) {
       token ??= tokenOption(r);
       continue;
     }
+    if (r?.scheme === "upto" && version === 2) {
+      const ch = chainOf(r.network);
+      if (ch && ch.vm === "evm" && String(r.asset ?? "").toLowerCase() === ch.stable.toLowerCase() && /^\d+$/.test(String(r.amount)) && /^0x[0-9a-fA-F]{40}$/.test(String(r.extra?.facilitatorAddress ?? "")) && /^0x[0-9a-fA-F]{40}$/.test(String(r.payTo ?? "")))
+        metered.push({ version, chain: ch, amount: String(r.amount), usd: Number(r.amount) / 1e6, payTo: r.payTo, asset: r.asset, maxTimeoutSeconds: Number(r.maxTimeoutSeconds) || 120, extra: r.extra?.name && r.extra?.version ? { name: String(r.extra.name), version: String(r.extra.version) } : ch.domain, raw: r });
+      continue;
+    }
     const chain = chainOf(r.network);
     if (!chain || r.scheme !== "exact") continue;
     if (chain.vm === "evm" ? String(r.asset ?? "").toLowerCase() !== chain.stable.toLowerCase() : r.asset !== chain.stable) continue;
@@ -462,7 +528,10 @@ async function readQuote(res) {
     accepts.push({ version, chain, amount, usd: Number(amount) / 1e6, payTo: r.payTo, asset: r.asset, maxTimeoutSeconds: Number(r.maxTimeoutSeconds) || 120, extra, raw: r });
   }
   const inputError = body.inputError?.message ? { code: String(body.inputError.code ?? "invalid_input"), message: String(body.inputError.message) } : void 0;
-  return { version, resource: body.resource ?? null, accepts, offered, inputError, ...token ? { token } : {} };
+  const m = body.metered;
+  const meterInfo = m && Number.isFinite(Number(m.ceilingUsd)) ? { inputPer1kTokensUsd: Number(m.inputPer1kTokensUsd), outputPer1kTokensUsd: Number(m.outputPer1kTokensUsd), ceilingUsd: Number(m.ceilingUsd), minimumUsd: Number(m.minimumUsd) } : void 0;
+  const gasless = !!body.extensions?.eip2612GasSponsoring;
+  return { version, resource: body.resource ?? null, accepts, offered, inputError, ...token ? { token } : {}, ...metered.length ? { metered: metered.map((q) => ({ ...q, gasless })) } : {}, ...meterInfo ? { meterInfo } : {} };
 }
 function choose(q, prefer = CHAIN_KEYS) {
   for (const k of prefer) {
@@ -546,6 +615,20 @@ async function x402fetch(url, init, opts) {
     const res2 = await f(url, { ...init, headers: headers2 });
     return { res: res2, paid: { ...signed2, tx: readSettlement(res2)?.tx ?? null } };
   }
+  if (opts.meter) {
+    const pref = (opts.prefer ?? CHAIN_KEYS).filter((k) => k !== "solana");
+    const req2 = pref.map((k) => quote.metered?.find((q) => q.chain.key === k)).find(Boolean);
+    if (!req2) throw new X402Error("metered_not_offered", quote.metered?.length ? `Metered calls are offered on ${quote.metered.map((q) => q.chain.name).join(", ")}; pick one of those networks.` : "This call is not offered as a metered (pay per token) call. Pay the flat price instead.");
+    if (opts.approve) await opts.approve(req2);
+    const signer2 = typeof opts.signer === "function" ? await opts.signer() : opts.signer;
+    const header2 = await signUptoPayment(signer2, req2, quote.resource, { reader: opts.reader, gasless: !!req2.gasless });
+    const signed2 = { req: req2, from: signer2.address, metered: { ceiling: req2.amount, deadline: header2.deadline } };
+    opts.onSigned?.(signed2);
+    const headers2 = new Headers(init.headers);
+    headers2.set(header2.name, header2.value);
+    const res2 = await f(url, { ...init, headers: headers2 });
+    return { res: res2, paid: { ...signed2, tx: readSettlement(res2)?.tx ?? null } };
+  }
   const req = choose(quote, (opts.prefer ?? CHAIN_KEYS).filter((k) => k !== "solana" || opts.solana));
   if (opts.approve) await opts.approve(req);
   const svm = req.chain.vm === "svm";
@@ -797,7 +880,15 @@ var Wafermap = class {
     this.queue = prev.then(() => held);
     return prev.then(() => release);
   }
-  async paidFetch(kind, what, url, init, network, payIn) {
+  /** Chain reads for a metered payment's EIP-2612 permit: Permit2 allowance and the token's permit nonce. */
+  reader() {
+    const nonces = [{ type: "function", name: "nonces", stateMutability: "view", inputs: [{ name: "owner", type: "address" }], outputs: [{ type: "uint256" }] }];
+    return {
+      allowance: (chain, owner, token) => this.client(chain.key).readContract({ address: token, abi: erc20Abi2, functionName: "allowance", args: [owner, PERMIT2] }),
+      permitNonce: (chain, owner, token) => this.client(chain.key).readContract({ address: token, abi: nonces, functionName: "nonces", args: [owner] })
+    };
+  }
+  async paidFetch(kind, what, url, init, network, payIn, meter) {
     let id = null;
     let release = null;
     const unlock = () => {
@@ -811,10 +902,12 @@ var Wafermap = class {
         prefer: this.prefer(network),
         fetch: this.fetch,
         payIn,
+        meter,
+        reader: meter ? this.reader() : void 0,
         tokenPriceUsd: this.tokenPriceUsd,
         approve: async (req) => {
           release = await this.acquire();
-          await this.gate({ kind, what, usd: req.usd, network: req.chain.key, detail: req.asset === WAFERMAP_TOKEN ? "in $WAFERMAP at 50% off, burned" : `${req.chain.symbol} to ${req.payTo}` });
+          await this.gate({ kind, what, usd: req.usd, network: req.chain.key, detail: req.asset === WAFERMAP_TOKEN ? "in $WAFERMAP at 50% off, burned" : meter ? `at most ${req.chain.symbol} ${req.usd}, charged for the tokens used, to ${req.payTo}` : `${req.chain.symbol} to ${req.payTo}` });
         },
         onSigned: (s) => {
           id = this.booked(kind, what, s);
@@ -902,11 +995,12 @@ var Wafermap = class {
   }
   async call(id, input = {}, o = {}) {
     const inToken = o.payIn === "wafermap";
+    if (o.metered && inToken) throw new WafermapError("bad_options", "A metered call is paid in USDC; it cannot also be paid in $WAFERMAP.");
     const stream = !!o.onDelta && !inToken;
     if (inToken && id.startsWith("m/")) throw new WafermapError("token_not_offered", "Marketplace listings are paid in USDG or USDC to their seller, not in $WAFERMAP.");
     if (inToken && !await this.wafermapApproved().catch(() => true)) throw new WafermapError("permit2_not_approved", "Paying in $WAFERMAP needs a one-time approval of Permit2. Run `wafermap approve-wafermap` (one transaction on Robinhood Chain, paid in ETH), then call again.");
     const pass = id.startsWith("m/") ? null : await this.holderPass();
-    const go = () => this.paidFetch("resource", id, `${this.baseUrl}/v1/${id}`, { method: "POST", headers: { "content-type": "application/json", "x-wafermap-payer": this.address, ...stream ? { accept: "text/event-stream" } : {}, ...pass ? { [PASS_HEADER]: pass } : {} }, body: JSON.stringify(input) }, o.network, inToken ? "wafermap" : void 0);
+    const go = () => this.paidFetch("resource", id, `${this.baseUrl}/v1/${id}`, { method: "POST", headers: { "content-type": "application/json", "x-wafermap-payer": this.address, ...stream ? { accept: "text/event-stream" } : {}, ...pass ? { [PASS_HEADER]: pass } : {} }, body: JSON.stringify(input) }, o.network, inToken ? "wafermap" : void 0, o.metered);
     const settle = (r2, out2) => {
       if (!r2.paid || !r2.id) return;
       const status = r2.res.status === 402 ? "refused" : r2.res.ok && !out2?.streamError ? "ok" : "failed";
@@ -1026,6 +1120,103 @@ var Wafermap = class {
     }
   }
 };
+
+// src/statement.ts
+import { createPublicClient as createPublicClient2, getAddress as getAddress3, http as http2, isAddress as isAddress3, parseAbiItem as parseAbiItem2, toEventSelector as toEventSelector2 } from "viem";
+import { arbitrum as arbitrum2, arc as arc2, base as base2, polygon as polygon2, robinhood as robinhood2, soneium as soneium2 } from "viem/chains";
+var EVM = { "eip155:4663": robinhood2, "eip155:8453": base2, "eip155:42161": arbitrum2, "eip155:137": polygon2, "eip155:5042": arc2, "eip155:1868": soneium2 };
+var ENV_RPC = { "eip155:4663": "WAFERMAP_RPC_ROBINHOOD", "eip155:8453": "WAFERMAP_RPC_BASE", "eip155:42161": "WAFERMAP_RPC_ARBITRUM", "eip155:137": "WAFERMAP_RPC_POLYGON", "eip155:5042": "WAFERMAP_RPC_ARC", "eip155:1868": "WAFERMAP_RPC_SONEIUM", solana: "WAFERMAP_RPC_SOLANA" };
+var TRANSFER = toEventSelector2(parseAbiItem2("event Transfer(address indexed from, address indexed to, uint256 value)"));
+var topicAddr = (t) => t ? getAddress3(`0x${t.slice(-40)}`) : null;
+async function fetchStatement(wallets, month, opts = {}) {
+  const url = `${(opts.baseUrl ?? "https://wafermap.xyz").replace(/\/$/, "")}/api/statement?wallet=${encodeURIComponent(wallets.join(","))}&month=${encodeURIComponent(month)}${opts.csv ? "&format=csv" : ""}`;
+  const r = await fetch(url, { signal: AbortSignal.timeout(opts.timeoutMs ?? 6e4) });
+  if (!r.ok) {
+    const j = await r.json().catch(() => null);
+    throw new Error(j?.error?.message ?? `Statement request failed (${r.status}).`);
+  }
+  return opts.csv ? r.text() : await r.json();
+}
+function parseStatement(text) {
+  let s;
+  try {
+    s = JSON.parse(text);
+  } catch {
+    throw new Error("That file is not JSON. Download the JSON statement (not the CSV) to verify it.");
+  }
+  if (s?.kind !== "wafermap-statement" || !Array.isArray(s.lines)) throw new Error("That file is not a Wafermap statement.");
+  return s;
+}
+function defaultClients(env = process.env) {
+  const cache = /* @__PURE__ */ new Map();
+  return {
+    evm: (network) => {
+      const chain = EVM[network];
+      if (!chain) return null;
+      if (!cache.has(network)) cache.set(network, createPublicClient2({ chain, transport: http2(env[ENV_RPC[network]] || void 0, { timeout: 3e4 }) }));
+      return cache.get(network);
+    },
+    solana: (method, params) => solanaRpc(env.WAFERMAP_RPC_SOLANA || SOLANA_PUBLIC_RPC, method, params)
+  };
+}
+async function verifyLine(l, clients) {
+  try {
+    if (!/^\d+$/.test(l.amountUnits)) return "mismatch";
+    const want = BigInt(l.amountUnits);
+    if (l.network.startsWith("solana:")) {
+      const tx = await clients.solana("getTransaction", [l.tx, { encoding: "jsonParsed", maxSupportedTransactionVersion: 0, commitment: "finalized" }]);
+      if (!tx) return "not_found";
+      if (tx.meta?.err) return "failed";
+      const delta = (owner) => {
+        const sum = (xs) => (xs ?? []).filter((b) => b.owner === owner && b.mint === l.token).reduce((a, b) => a + BigInt(b.uiTokenAmount?.amount ?? "0"), 0n);
+        return sum(tx.meta?.postTokenBalances) - sum(tx.meta?.preTokenBalances);
+      };
+      return delta(l.from) === -want && delta(l.to) === want ? "ok" : "mismatch";
+    }
+    const client = clients.evm(l.network);
+    if (!client) return "unsupported";
+    if (!/^0x[0-9a-fA-F]{64}$/.test(l.tx) || !isAddress3(l.token) || !isAddress3(l.from) || !isAddress3(l.to)) return "mismatch";
+    const receipt = await client.getTransactionReceipt({ hash: l.tx }).catch((e) => /not.*found|could not be found/i.test(String(e?.message)) ? null : Promise.reject(e));
+    if (!receipt) return "not_found";
+    if (receipt.status !== "success") return "failed";
+    const hit = receipt.logs.some(
+      (g) => g.address.toLowerCase() === l.token.toLowerCase() && g.topics[0] === TRANSFER && topicAddr(g.topics[1]) === getAddress3(l.from) && topicAddr(g.topics[2]) === getAddress3(l.to) && BigInt(g.data) === want
+    );
+    return hit ? "ok" : "mismatch";
+  } catch {
+    return "error";
+  }
+}
+async function verifyStatement(s, clients = defaultClients(), onLine) {
+  const results = new Array(s.lines.length);
+  let next = 0;
+  await Promise.all(
+    Array.from({ length: 4 }, async () => {
+      while (next < s.lines.length) {
+        const i = next++;
+        results[i] = await verifyLine(s.lines[i], clients);
+        onLine?.(i, results[i]);
+      }
+    })
+  );
+  const usd = (pick) => Math.round(s.lines.reduce((a, l, i) => a + (pick(results[i]) ? Number(l.amountUsd) : 0), 0) * 1e6) / 1e6;
+  const count = (r) => results.filter((x) => x === r).length;
+  const linesUsd = usd(() => true);
+  return {
+    results,
+    lines: s.lines.length,
+    ok: count("ok"),
+    mismatch: count("mismatch"),
+    failed: count("failed"),
+    notFound: count("not_found"),
+    unsupported: count("unsupported"),
+    error: count("error"),
+    confirmedUsd: usd((r) => r === "ok"),
+    linesUsd,
+    // The totals block must add up to the lines it sits next to.
+    totalsMatch: s.totals?.calls === s.lines.length && Math.abs((s.totals?.usd ?? NaN) - linesUsd) < 1e-6
+  };
+}
 export {
   DEFAULT_LIMITS,
   DEFAULT_TIMEOUT_MS,
@@ -1048,15 +1239,19 @@ export {
   decodeSwap,
   encodePass,
   executeSwap,
+  fetchStatement,
   holderInfo,
   listResources,
   makePass,
   mergeLog,
+  parseStatement,
   passMessage,
   quoteSwap,
   readQuote,
   signPayment,
   signTokenPayment,
+  verifyLine,
+  verifyStatement,
   wafermapPriceUsd,
   x402fetch
 };

package/dist/types/shared/x402client.d.ts

@@ -46,6 +46,8 @@ export type Requirement = {
     };
     /** The requirement exactly as the server sent it (echoed back in the payment). */
     raw: any;
+    /** Metered quotes only: the server announced eip2612GasSponsoring, so a missing Permit2 approval can be signed. */
+    gasless?: boolean;
 };
 export type Quote = {
     version: 1 | 2;
@@ -57,7 +59,33 @@ export type Quote = {
         message: string;
     };
     token?: TokenRequirement;
+    metered?: Requirement[];
+    meterInfo?: MeterInfo;
 };
+export declare const UPTO_PROXY = "0x4020A4f3b7b90ccA423B9fabCc0CE57C6C240002";
+/** The longest a metered authorization stays valid: long answers settle after the model finishes. */
+export declare const MAX_METERED_SECONDS = 300;
+export type MeterInfo = {
+    inputPer1kTokensUsd: number;
+    outputPer1kTokensUsd: number;
+    ceilingUsd: number;
+    minimumUsd: number;
+};
+/** Reads the client needs for an EIP-2612 permit: the owner's Permit2 allowance and its permit nonce on the token. */
+export type ChainReader = {
+    allowance: (chain: Chain, owner: Hex, token: Hex) => Promise<bigint>;
+    permitNonce: (chain: Chain, owner: Hex, token: Hex) => Promise<bigint>;
+};
+/** Signs a metered payment for at most `req.amount` (the ceiling). Adds an EIP-2612 permit when the Permit2
+ *  allowance is short and the server announced eip2612GasSponsoring. */
+export declare function signUptoPayment(signer: Signer, req: Requirement, resource: any, opts?: {
+    reader?: ChainReader;
+    gasless?: boolean;
+}): Promise<{
+    name: string;
+    value: string;
+    deadline: number;
+}>;
 export declare const WAFERMAP_TOKEN = "0xfda080f64d84c989cfc50ff18253542cfe502db3";
 export declare const PERMIT2 = "0x000000000022D473030F116dDEE9F6B43aC78BA3";
 export declare const DEAD = "0x000000000000000000000000000000000000dEaD";
@@ -123,6 +151,10 @@ export type SignedSol = {
 export type Signed = {
     req: Requirement;
     from: string;
+    metered?: {
+        ceiling: string;
+        deadline: number;
+    };
     auth?: SignedAuth;
     sol?: SignedSol;
     token?: {
@@ -151,4 +183,6 @@ export declare function x402fetch(url: string, init: RequestInit, opts: {
     fetch?: typeof fetch;
     payIn?: "stablecoin" | "wafermap";
     tokenPriceUsd?: () => Promise<number>;
+    meter?: boolean;
+    reader?: ChainReader;
 }): Promise<PaidCall>;

package/dist/types/src/core.d.ts

@@ -142,6 +142,8 @@ export declare class Wafermap {
     private body;
     private queue;
     private acquire;
+    /** Chain reads for a metered payment's EIP-2612 permit: Permit2 allowance and the token's permit nonce. */
+    private reader;
     private paidFetch;
     resources(): Promise<any[]>;
     private passCache;
@@ -161,6 +163,7 @@ export declare class Wafermap {
         network?: Net;
         payIn?: "stablecoin" | "wafermap";
         onDelta?: (text: string) => void;
+        metered?: boolean;
     }): Promise<{
         resource: string;
         result: any;
@@ -173,6 +176,13 @@ export declare class Wafermap {
             payer: string;
             tx: string;
             ms: number;
+            metered?: {
+                inputTokens: number;
+                outputTokens: number;
+                estimated: boolean;
+                ceilingUsd: number;
+                chargedUsd: number;
+            };
         } | null;
         free?: {
             wallet: string;

package/dist/types/src/index.d.ts

@@ -6,3 +6,5 @@ export { quoteSwap, executeSwap, decodeSwap, KYBER_ROUTER, SwapError } from "../
 export type { Requirement, Quote, Signed, SignedAuth, SignedSol, Signer } from "../shared/x402client";
 export { checkSolanaPayment, SOLANA_PUBLIC_RPC } from "../shared/solana";
 export type { SolanaCheck } from "../shared/solana";
+export { fetchStatement, parseStatement, verifyStatement, verifyLine } from "./statement.js";
+export type { Statement, StatementLine, LineCheck } from "./statement.js";

package/dist/types/src/statement.d.ts

@@ -0,0 +1,58 @@
+import { type PublicClient } from "viem";
+export type StatementLine = {
+    date: string;
+    resource: string;
+    network: string;
+    asset: string;
+    amountUsd: string;
+    token: string;
+    amountUnits: string;
+    from: string;
+    to: string;
+    tx: string;
+    explorer?: string | null;
+};
+export type Statement = {
+    kind: "wafermap-statement";
+    version: number;
+    month: string;
+    wallets: string[];
+    totals: {
+        calls: number;
+        usd: number;
+    };
+    lines: StatementLine[];
+    truncated?: boolean;
+};
+export type LineCheck = "ok" | "mismatch" | "failed" | "not_found" | "unsupported" | "error";
+/** Downloads a statement. `csv` returns the CSV text, otherwise the parsed JSON. */
+export declare function fetchStatement(wallets: string[], month: string, opts?: {
+    baseUrl?: string;
+    csv?: boolean;
+    timeoutMs?: number;
+}): Promise<Statement | string>;
+/** Reads and sanity-checks a statement file's content. Throws on anything that is not a statement. */
+export declare function parseStatement(text: string): Statement;
+type Clients = {
+    evm: (network: string) => Pick<PublicClient, "getTransactionReceipt"> | null;
+    solana: (method: string, params: unknown[]) => Promise<any>;
+};
+/** Clients from env RPCs (WAFERMAP_RPC_<NET>) or the chains' public RPCs. */
+export declare function defaultClients(env?: Record<string, string | undefined>): Clients;
+/** Checks one line against its chain. */
+export declare function verifyLine(l: StatementLine, clients: Clients): Promise<LineCheck>;
+/** Checks every line, four at a time (public RPCs refuse bursts), and adds up what the chain confirms. */
+export declare function verifyStatement(s: Statement, clients?: Clients, onLine?: (i: number, r: LineCheck) => void): Promise<{
+    results: LineCheck[];
+    lines: number;
+    ok: number;
+    mismatch: number;
+    failed: number;
+    notFound: number;
+    unsupported: number;
+    error: number;
+    confirmedUsd: number;
+    linesUsd: number;
+    totalsMatch: boolean;
+}>;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wafermapxyz/cli",
-  "version": "0.4.10",
+  "version": "0.4.12",
   "description": "Wafermap for agents: an encrypted local wallet that pays x402 resources, discovers and pays third-party x402 services (USDG on Robinhood Chain; USDC on Solana, Base, Arbitrum, Polygon, Arc, Soneium), and swaps on Robinhood Chain and Base. CLI, SDK and MCP server.",
   "type": "module",
   "bin": {