@wafermapxyz/cli 0.4.3 → 0.4.4

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.4.4 (2 Nov 2026)
+
+**$WAFERMAP holder tiers.**
+
+- **Pro free calls.** A wallet holding 1,000,000 $WAFERMAP on Robinhood Chain gets 10 free calls a day (UTC) to Wafermap resources listed at $0.01 or less. `call()` (CLI `wafermap call`, MCP `wafermap_call`) sends a **holder pass** to Wafermap with each call; when the call is free, the result comes back with `receipt: null` and `free: {left, perDay}`, no payment is signed and nothing is recorded as spending. Otherwise the call is quoted and paid as before.
+- **Holder pass.** A message the wallet signs (`personal_sign`: no transaction, no cost) that proves it holds the wallet, valid for 24 hours and reused until its last 10 minutes (`Wafermap.holderPass()`). It goes to Wafermap only: never with `pay()` to third-party services, and never to marketplace listings (`m/...`). The SDK exports `PASS_HEADER`, `passMessage`, `encodePass`, `decodePass`, `makePass`.
+- **`wafermap holder`** shows what the wallet's $WAFERMAP unlocks: holder price, tier, free calls left today, x402 Tracker Pro. Needs no password (`holderInfo()` in the SDK).
+- **`wafermap pass`** prints a pass for scripts, e.g. the x402 Tracker Pro API (`/api/x402/pro/movers`, `/api/x402/pro/export`, for wallets holding 100,000 $WAFERMAP).
+
 ## 0.4.3 (2 Nov 2026)
 
 The two open points from the third public review by @whoiskn0why (8/10), thank you.

package/README.md

@@ -82,7 +82,9 @@ Pass `approve: (a) => boolean` to confirm each payment or swap yourself, and `le
 
 ## $WAFERMAP holder discount
 
-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). 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…
+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). 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`.
+
+With 1,000,000 $WAFERMAP the wallet is **Pro**: 10 free calls a day (UTC) to resources listed at $0.01 or less. `wafermap call` sends a holder pass (a signed message, no transaction, valid 24 hours) to Wafermap only; when a call is free, nothing is signed for payment and it prints `✓ Free call`. Holders of 100,000 also unlock x402 Tracker Pro: `wafermap pass` prints a pass for its API. Details: https://wafermap.xyz/docs#holders
 
 ## Where the limits live
 

package/dist/cli.js

@@ -437,6 +437,47 @@ var init_x402client = __esm({
   }
 });
 
+// shared/pass.ts
+function passMessage(address, iat, exp) {
+  return [
+    "wafermap.xyz holder pass",
+    "",
+    `Wallet: ${address}`,
+    `Issued: ${new Date(iat * 1e3).toISOString()}`,
+    `Expires: ${new Date(exp * 1e3).toISOString()}`,
+    "",
+    "Proves you hold this wallet, so Wafermap can apply what your $WAFERMAP unlocks. It costs nothing and moves no funds."
+  ].join("\n");
+}
+function decodePass(s) {
+  if (!s || s.length > 1e3 || !/^[A-Za-z0-9_-]+$/.test(s)) return null;
+  try {
+    const p = JSON.parse(unb64url(s));
+    if (p?.v !== 1 || typeof p.address !== "string" || !/^0x[0-9a-fA-F]{40}$/.test(p.address)) return null;
+    if (!Number.isInteger(p.iat) || !Number.isInteger(p.exp) || typeof p.sig !== "string" || !/^0x[0-9a-fA-F]{130}$/.test(p.sig)) return null;
+    return { v: 1, address: p.address, iat: p.iat, exp: p.exp, sig: p.sig };
+  } catch {
+    return null;
+  }
+}
+async function makePass(signer, seconds = PASS_MAX_SECONDS, now = Math.floor(Date.now() / 1e3)) {
+  const iat = now;
+  const exp = now + Math.min(Math.max(60, seconds), PASS_MAX_SECONDS);
+  const sig = await signer.signMessage({ message: passMessage(signer.address, iat, exp) });
+  return { v: 1, address: signer.address, iat, exp, sig };
+}
+var PASS_HEADER, PASS_MAX_SECONDS, b64url, unb64url, encodePass;
+var init_pass = __esm({
+  "shared/pass.ts"() {
+    "use strict";
+    PASS_HEADER = "x-wafermap-pass";
+    PASS_MAX_SECONDS = 86400;
+    b64url = (s) => btoa(unescape(encodeURIComponent(s))).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+    unb64url = (s) => decodeURIComponent(escape(atob(s.replace(/-/g, "+").replace(/_/g, "/"))));
+    encodePass = (p) => b64url(JSON.stringify(p));
+  }
+});
+
 // src/core.ts
 var core_exports = {};
 __export(core_exports, {
@@ -446,6 +487,7 @@ __export(core_exports, {
   Wafermap: () => Wafermap,
   WafermapError: () => WafermapError,
   checkPayment: () => checkPayment,
+  holderInfo: () => holderInfo,
   isNet: () => isNet,
   listResources: () => listResources,
   mergeLog: () => mergeLog
@@ -473,6 +515,15 @@ async function checkPayment(e, rpc) {
     return "error";
   }
 }
+async function holderInfo(address, baseUrl = "https://wafermap.xyz", timeoutMs = DEFAULT_TIMEOUT_MS) {
+  const host = new URL(baseUrl).host;
+  const r = await fetch(`${baseUrl.replace(/\/$/, "")}/api/holder?address=${encodeURIComponent(address)}`, { signal: AbortSignal.timeout(timeoutMs) }).catch((e) => {
+    throw timedOut(e) ? new WafermapError("timeout", `${host} did not answer within ${Math.round(timeoutMs / 1e3)} s.`) : new WafermapError("network_error", `${host}: ${e?.message ?? "request failed"}`);
+  });
+  const j = await r.json().catch(() => null);
+  if (!r.ok || !j) throw new WafermapError(j?.error?.code ?? "network_error", j?.error?.message ?? `${host} answered HTTP ${r.status}.`);
+  return j;
+}
 async function listResources(baseUrl = "https://wafermap.xyz", timeoutMs = DEFAULT_TIMEOUT_MS) {
   const host = new URL(baseUrl).host;
   const gaveUp = () => new WafermapError("timeout", `${host} did not answer within ${Math.round(timeoutMs / 1e3)} s. Nothing was paid.`);
@@ -494,6 +545,7 @@ var init_core = __esm({
     init_swap();
     init_solana();
     init_x402client();
+    init_pass();
     NETS = CHAIN_KEYS;
     isNet = (v) => NETS.includes(v);
     isSwapNet = (v) => v === "robinhood" || v === "base";
@@ -649,8 +701,19 @@ var init_core = __esm({
       async resources() {
         return listResources(this.baseUrl, this.timeoutMs);
       }
+      passCache = null;
+      /** A holder pass (shared/pass.ts) signed by this wallet, valid 24 h and reused until its last 10 minutes. It
+       *  proves the wallet to Wafermap for what its $WAFERMAP unlocks (Pro free calls, x402 Tracker Pro). Signing
+       *  a message moves no funds. */
+      async holderPass() {
+        const p = decodePass(this.passCache);
+        if (this.passCache && p && p.exp - 600 > Date.now() / 1e3) return this.passCache;
+        this.passCache = encodePass(await makePass({ address: this.account.address, signMessage: (a) => this.account.signMessage(a) }));
+        return this.passCache;
+      }
       async call(id, input = {}, o = {}) {
-        const go = () => this.paidFetch("resource", id, `${this.baseUrl}/v1/${id}`, { method: "POST", headers: { "content-type": "application/json", "x-wafermap-payer": this.address }, body: JSON.stringify(input) }, o.network);
+        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, ...pass ? { [PASS_HEADER]: pass } : {} }, body: JSON.stringify(input) }, o.network);
         const settle = (r2, out2) => {
           if (!r2.paid || !r2.id) return;
           const status = r2.res.status === 402 ? "refused" : r2.res.ok ? "ok" : "failed";
@@ -960,7 +1023,7 @@ var VERSION;
 var init_version = __esm({
   "src/version.ts"() {
     "use strict";
-    VERSION = "0.4.3";
+    VERSION = "0.4.4";
   }
 });
 
@@ -1515,6 +1578,8 @@ Wallet
 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 holder                       what this wallet's $WAFERMAP unlocks: holder price, Pro free calls left today
+  wafermap pass                         print a holder pass (X-Wafermap-Pass) for scripts and x402 Tracker Pro
   wafermap discover <words>             search third-party x402 services
   wafermap pay <url> [field=value ...]  call any x402 URL and pay it       (--post to send a JSON body)
 
@@ -1630,6 +1695,26 @@ async function main() {
   Caps: $0.10 per payment, $1 per day, $25 per swap. Change with \`wafermap limits\`.`);
       return;
     }
+    case "holder": {
+      const addr = keystoreAddress() ?? die("No wallet yet. Run `wafermap init`.");
+      const j = await holderInfo(addr, process.env.WAFERMAP_URL, Number(process.env.WAFERMAP_TIMEOUT_MS) || void 0);
+      if (!j.active) return console.log("The $WAFERMAP holder program is off.");
+      const n = (v) => Math.floor(v).toLocaleString("en-US");
+      const k = j.perks;
+      console.log(`${addr}
+  holds     ${n(j.balance)} $WAFERMAP on Robinhood Chain`);
+      console.log(`  tier      ${j.tier === "pro" ? "Pro" : j.tier === "holder" ? "Holder" : "none"}`);
+      console.log(`  price     ${j.holder ? `${j.percent}% off Wafermap resources on EVM networks` : `regular (hold ${n(j.minTokens)} for ${j.percent}% off)`}`);
+      if (k) console.log(`  free      ${j.tier === "pro" ? `${k.freeLeftToday ?? "?"} of ${k.freeCallsPerDay} free calls left today (resources up to $${k.freeMaxUsd}); \`wafermap call\` uses them first` : `hold ${n(k.proMinTokens)} for ${k.freeCallsPerDay} free calls a day`}`);
+      return console.log(`  tracker   ${j.holder ? "x402 Tracker Pro unlocked: wafermap.xyz/x402 (or `wafermap pass` for the API)" : `x402 Tracker Pro needs ${n(j.minTokens)}`}`);
+    }
+    case "pass": {
+      const wm = openWallet(await password());
+      const v = await wm.holderPass();
+      console.error(`Holder pass for ${wm.address}, valid 24 hours. It proves you hold the wallet and moves no funds; anyone who has it can use your free calls until it expires, so keep it private. Send it as X-Wafermap-Pass:`);
+      console.error(`  curl -H "X-Wafermap-Pass: $(wafermap pass)" https://wafermap.xyz/api/x402/pro/movers`);
+      return console.log(v);
+    }
     case "address": {
       const evm = keystoreAddress() ?? die("No wallet yet. Run `wafermap init`.");
       let sol = keystoreSolana();
@@ -1711,6 +1796,7 @@ Total $${total.toFixed(4)} in ${pays.length} payments. From 0.3.3 every payment
       const wm = openWallet(await password(), approver(yes));
       const out = await wm.call(id, inputOf(a, 1), { network: net(a.flags.network) });
       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);
       return printResult(out.result);
     }

package/dist/index.js

@@ -407,6 +407,41 @@ async function x402fetch(url, init, opts) {
   return { res, paid: { ...signed, tx: readSettlement(res)?.tx ?? null } };
 }
 
+// shared/pass.ts
+var PASS_HEADER = "x-wafermap-pass";
+var PASS_MAX_SECONDS = 86400;
+function passMessage(address, iat, exp) {
+  return [
+    "wafermap.xyz holder pass",
+    "",
+    `Wallet: ${address}`,
+    `Issued: ${new Date(iat * 1e3).toISOString()}`,
+    `Expires: ${new Date(exp * 1e3).toISOString()}`,
+    "",
+    "Proves you hold this wallet, so Wafermap can apply what your $WAFERMAP unlocks. It costs nothing and moves no funds."
+  ].join("\n");
+}
+var b64url = (s) => btoa(unescape(encodeURIComponent(s))).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+var unb64url = (s) => decodeURIComponent(escape(atob(s.replace(/-/g, "+").replace(/_/g, "/"))));
+var encodePass = (p) => b64url(JSON.stringify(p));
+function decodePass(s) {
+  if (!s || s.length > 1e3 || !/^[A-Za-z0-9_-]+$/.test(s)) return null;
+  try {
+    const p = JSON.parse(unb64url(s));
+    if (p?.v !== 1 || typeof p.address !== "string" || !/^0x[0-9a-fA-F]{40}$/.test(p.address)) return null;
+    if (!Number.isInteger(p.iat) || !Number.isInteger(p.exp) || typeof p.sig !== "string" || !/^0x[0-9a-fA-F]{130}$/.test(p.sig)) return null;
+    return { v: 1, address: p.address, iat: p.iat, exp: p.exp, sig: p.sig };
+  } catch {
+    return null;
+  }
+}
+async function makePass(signer, seconds = PASS_MAX_SECONDS, now = Math.floor(Date.now() / 1e3)) {
+  const iat = now;
+  const exp = now + Math.min(Math.max(60, seconds), PASS_MAX_SECONDS);
+  const sig = await signer.signMessage({ message: passMessage(signer.address, iat, exp) });
+  return { v: 1, address: signer.address, iat, exp, sig };
+}
+
 // src/core.ts
 var NETS = CHAIN_KEYS;
 var isSwapNet = (v) => v === "robinhood" || v === "base";
@@ -442,6 +477,15 @@ async function checkPayment(e, rpc) {
 var DEFAULT_LIMITS = { perPayment: 0.1, perDay: 1, perSwap: 25 };
 var DEFAULT_TIMEOUT_MS = 6e4;
 var timedOut = (e) => e?.name === "TimeoutError" || e?.cause?.name === "TimeoutError";
+async function holderInfo(address, baseUrl = "https://wafermap.xyz", timeoutMs = DEFAULT_TIMEOUT_MS) {
+  const host = new URL(baseUrl).host;
+  const r = await fetch(`${baseUrl.replace(/\/$/, "")}/api/holder?address=${encodeURIComponent(address)}`, { signal: AbortSignal.timeout(timeoutMs) }).catch((e) => {
+    throw timedOut(e) ? new WafermapError("timeout", `${host} did not answer within ${Math.round(timeoutMs / 1e3)} s.`) : new WafermapError("network_error", `${host}: ${e?.message ?? "request failed"}`);
+  });
+  const j = await r.json().catch(() => null);
+  if (!r.ok || !j) throw new WafermapError(j?.error?.code ?? "network_error", j?.error?.message ?? `${host} answered HTTP ${r.status}.`);
+  return j;
+}
 async function listResources(baseUrl = "https://wafermap.xyz", timeoutMs = DEFAULT_TIMEOUT_MS) {
   const host = new URL(baseUrl).host;
   const gaveUp = () => new WafermapError("timeout", `${host} did not answer within ${Math.round(timeoutMs / 1e3)} s. Nothing was paid.`);
@@ -596,8 +640,19 @@ var Wafermap = class {
   async resources() {
     return listResources(this.baseUrl, this.timeoutMs);
   }
+  passCache = null;
+  /** A holder pass (shared/pass.ts) signed by this wallet, valid 24 h and reused until its last 10 minutes. It
+   *  proves the wallet to Wafermap for what its $WAFERMAP unlocks (Pro free calls, x402 Tracker Pro). Signing
+   *  a message moves no funds. */
+  async holderPass() {
+    const p = decodePass(this.passCache);
+    if (this.passCache && p && p.exp - 600 > Date.now() / 1e3) return this.passCache;
+    this.passCache = encodePass(await makePass({ address: this.account.address, signMessage: (a) => this.account.signMessage(a) }));
+    return this.passCache;
+  }
   async call(id, input = {}, o = {}) {
-    const go = () => this.paidFetch("resource", id, `${this.baseUrl}/v1/${id}`, { method: "POST", headers: { "content-type": "application/json", "x-wafermap-payer": this.address }, body: JSON.stringify(input) }, o.network);
+    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, ...pass ? { [PASS_HEADER]: pass } : {} }, body: JSON.stringify(input) }, o.network);
     const settle = (r2, out2) => {
       if (!r2.paid || !r2.id) return;
       const status = r2.res.status === 402 ? "refused" : r2.res.ok ? "ok" : "failed";
@@ -711,6 +766,7 @@ export {
   DEFAULT_TIMEOUT_MS,
   KYBER_ROUTER,
   MAX_VALIDITY_SECONDS,
+  PASS_HEADER,
   PAY_CHAINS,
   SwapError,
   Wafermap,
@@ -718,10 +774,15 @@ export {
   X402Error,
   checkPayment,
   choose,
+  decodePass,
   decodeSwap,
+  encodePass,
   executeSwap,
+  holderInfo,
   listResources,
+  makePass,
   mergeLog,
+  passMessage,
   quoteSwap,
   readQuote,
   signPayment,

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

@@ -0,0 +1,21 @@
+export declare const PASS_HEADER = "x-wafermap-pass";
+export declare const PASS_MAX_SECONDS = 86400;
+export type Pass = {
+    v: 1;
+    address: string;
+    iat: number;
+    exp: number;
+    sig: string;
+};
+/** The exact text the wallet signs. */
+export declare function passMessage(address: string, iat: number, exp: number): string;
+export declare const encodePass: (p: Pass) => string;
+/** The pass's fields, or null when it is not a well-formed pass (the signature is not checked here). */
+export declare function decodePass(s: string | undefined | null): Pass | null;
+/** Signs a new pass with any signer that can personal_sign. Valid for `seconds` (at most a day). */
+export declare function makePass(signer: {
+    address: string;
+    signMessage: (a: {
+        message: string;
+    }) => Promise<string>;
+}, seconds?: number, now?: number): Promise<Pass>;

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

@@ -87,6 +87,8 @@ export declare function mergeLog(entries: SpendEntry[]): SpendEntry[];
 export declare function checkPayment(e: Pick<SpendEntry, "network" | "payer" | "nonce" | "validBefore">, rpc?: string): Promise<"used" | "unused" | "pending" | "unknown" | "error">;
 export declare const DEFAULT_LIMITS: Limits;
 export declare const DEFAULT_TIMEOUT_MS = 60000;
+/** What a wallet's $WAFERMAP unlocks (holder price, Pro free calls left today), from /api/holder. Needs no key. */
+export declare function holderInfo(address: string, baseUrl?: string, timeoutMs?: number): Promise<any>;
 /** Wafermap's resource catalog. Needs no wallet; gives up after `timeoutMs` like every other request. */
 export declare function listResources(baseUrl?: string, timeoutMs?: number): Promise<any[]>;
 export declare class Wafermap {
@@ -126,6 +128,11 @@ export declare class Wafermap {
     private acquire;
     private paidFetch;
     resources(): Promise<any[]>;
+    private passCache;
+    /** A holder pass (shared/pass.ts) signed by this wallet, valid 24 h and reused until its last 10 minutes. It
+     *  proves the wallet to Wafermap for what its $WAFERMAP unlocks (Pro free calls, x402 Tracker Pro). Signing
+     *  a message moves no funds. */
+    holderPass(): Promise<string>;
     call(id: string, input?: Record<string, unknown>, o?: {
         network?: Net;
     }): Promise<{
@@ -139,6 +146,11 @@ export declare class Wafermap {
             tx: string;
             ms: number;
         } | null;
+        free?: {
+            wallet: string;
+            left: number;
+            perDay: number;
+        };
     }>;
     discover(query: string, limit?: number): Promise<{
         url: string;

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

@@ -1,4 +1,5 @@
-export { Wafermap, WafermapError, DEFAULT_LIMITS, DEFAULT_TIMEOUT_MS, checkPayment, listResources, mergeLog } from "./core.js";
+export { Wafermap, WafermapError, DEFAULT_LIMITS, DEFAULT_TIMEOUT_MS, checkPayment, holderInfo, listResources, mergeLog } from "./core.js";
+export { PASS_HEADER, passMessage, encodePass, decodePass, makePass } from "../shared/pass";
 export type { Approval, Limits, Net, PaymentStatus, SpendEntry, SwapQuote, Token, WafermapOptions } from "./core.js";
 export { x402fetch, readQuote, choose, signPayment, PAY_CHAINS, MAX_VALIDITY_SECONDS, X402Error } from "../shared/x402client";
 export { quoteSwap, executeSwap, decodeSwap, KYBER_ROUTER, SwapError } from "../shared/swap";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wafermapxyz/cli",
-  "version": "0.4.3",
+  "version": "0.4.4",
   "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), and swaps on Robinhood Chain and Base. CLI, SDK and MCP server.",
   "type": "module",
   "bin": {