@hypawave/mcp 0.1.2 → 0.3.0

package/CHANGELOG.md

@@ -3,6 +3,26 @@
 All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [0.3.0] - 2026-07-22
+
+### Added
+
+- **Operator funding options** — `setup_wallet {action:"funding_options", amount_sats?}` returns operator-facing funding instructions to present verbatim: an exact-amount Lightning invoice (payable from Cash App, Coinbase, or any Lightning wallet) or the wallet's Lightning address, plus an on-chain deposit address for exchanges without Lightning (e.g. Robinhood; 300-sat Coinos dust minimum surfaced). Hosted-wallet creation now returns the same funding block, and insufficient-balance NWC payment errors point the agent at the action.
+- **Per-wallet NWC guidance** — `setup_wallet {action:"connect_own"}` without `nwc_url` now returns wallet-specific steps (Alby Hub, Coinos, Primal, LNbits, self-hosted node) for finding the connection string, instead of erroring; operator option 2 tells the agent to ask which wallet the operator uses.
+- Coinos registration JWT (no expiry) is persisted in `~/.hypawave/wallet.json` (`token`) to mint funding invoices and on-chain addresses later; new `createFundingInvoice()` / `getOnchainAddress()` client helpers (`POST /invoice`, types `lightning` / `bitcoin`).
+
+## [0.2.0] - 2026-07-06
+
+### Added
+
+- `setup_wallet` tool (16 tools total): agent-driven wallet provisioning. `create_hosted` registers a fresh Coinos account (registration auto-creates the NWC connection; requires explicit operator consent via `confirm: true`) and saves credentials to `~/.hypawave/wallet.json` (0600, local-only — Hypawave servers never receive them). `connect_own` saves an existing NWC string instead and live-verifies it with a balance probe. Called with no arguments, it returns operator-facing options to present verbatim.
+- `getNwcUrl()` now falls back to `~/.hypawave/wallet.json` when `NWC_URL` / `HYPAWAVE_NWC_URL` are unset (env always wins). `wallet_status` and the startup log report the config source; manual-mode messages point to `setup_wallet`.
+- `COINOS_API_URL` env var (default `https://coinos.io/api`).
+
+### Security
+
+- Wallet file is written 0600 and never overwritten while it exists (it may hold a funded wallet's only credentials); corrupt files degrade to manual mode instead of throwing.
+
 ## [0.1.2] - 2026-07-02
 
 ### Added

package/README.md

@@ -45,7 +45,7 @@ env = { NWC_URL = "nostr+walletconnect://...", HYPAWAVE_MAX_SPEND_SATS = "10000"
 
 All env vars are optional — with no `NWC_URL` the server runs in manual mode (see Wallet below).
 
-## Tools (15)
+## Tools (16)
 
 | Tool | What it does |
 |---|---|
@@ -67,6 +67,7 @@ All env vars are optional — with no `NWC_URL` the server runs in manual mode (
 | `list_sales` | List your settled sales (payments/invoices) — reconcile missed webhooks |
 | **Utility** | |
 | `wallet_status` | Wallet balance, seller pubkey, spending cap, live platform fees/limits |
+| `setup_wallet` | One-time wallet setup: create a hosted Coinos wallet (with operator consent) or connect your own NWC wallet (with per-wallet steps to find the string); also serves operator funding options (Lightning + on-chain) |
 
 ## Buy in three calls
 
@@ -100,13 +101,18 @@ Selling needs **no special wallet** — payouts go straight to your Lightning Ad
 
 Paying requires a wallet that returns the settlement **preimage**. Connect any **NWC-capable** wallet (Coinos, Alby Hub, Primal, LNbits, …) via `NWC_URL` — the NWC spec guarantees `pay_invoice` returns the preimage, so any NWC wallet works.
 
+**No wallet yet? `setup_wallet`.** With explicit operator consent it registers a fresh hosted wallet at coinos.io (custodial — keep only small amounts) and saves the credentials to `~/.hypawave/wallet.json` (0600, local only; Hypawave's servers never receive them — **back this file up: it holds the only copy**). Or `{action:"connect_own"}` connects a wallet you already use — called without an NWC string it returns per-wallet steps (Alby Hub, Coinos, Primal, LNbits, self-hosted node) for finding it. `NWC_URL`, when set, always wins over the wallet file.
+
+**Funding the wallet (the human's only job).** `setup_wallet {action:"funding_options", amount_sats?}` returns operator-facing instructions the agent presents verbatim, with two paths: **instant** — an exact-amount Lightning invoice (payable from Cash App, Coinbase, or any Lightning wallet) or the wallet's Lightning address; **on-chain** — a deposit address for exchanges without Lightning support (e.g. Robinhood; ~10–60 min, mining fees, 300-sat minimum — best for larger top-ups). Low-balance payment failures point the agent at this action automatically. No bitcoin at all? Any of those apps sells it.
+
 **No wallet configured? Manual mode.** `buy_offer` / `pay_invoice` return the bolt11; pay it with any preimage-returning wallet and submit the preimage via `confirm_payment` (or re-call `pay_invoice` with it).
 
 ## Environment variables
 
 | Variable | Required | Meaning |
 |---|---|---|
-| `NWC_URL` | no | Nostr Wallet Connect string for automatic payments. Absent → manual mode. |
+| `NWC_URL` | no | Nostr Wallet Connect string for automatic payments. Absent → falls back to `~/.hypawave/wallet.json` (from `setup_wallet`), else manual mode. |
+| `COINOS_API_URL` | no | Coinos API base for `setup_wallet` (default `https://coinos.io/api`). |
 | `HYPAWAVE_MAX_SPEND_SATS` | no | Per-payment cap enforced in code. Unset → derived live from the platform's `max_invoice_usd` at the current BTC price (so the default never blocks a platform-allowed amount). Payments above it are refused. |
 | `HYPAWAVE_PRIVKEY` | no | 64-char hex secp256k1 key = your seller identity. Auto-generated to `~/.hypawave/identity.json` (0600) if unset. **Back it up — it controls your offers.** |
 | `HYPAWAVE_API_URL` | no | API base (default `https://hypawave.com`). |

package/SECURITY.md

@@ -8,7 +8,7 @@ A **local stdio MCP server** for Hypawave's accountless Lightning paths (3a/3b).
 
 **What stays on your machine (never transmitted):**
 - **Your seller signing key** — `HYPAWAVE_PRIVKEY` or the auto-generated `~/.hypawave/identity.json` (written with `0600` permissions). Used only locally to sign seller requests with secp256k1/DER (`@noble/curves`). No Hypawave endpoint accepts a private key. **Back it up — it IS your identity and controls your offers.**
-- **Your wallet credentials** — the `NWC_URL` connection string. The server speaks NIP-47 directly to your wallet over its Nostr relay; the string is never sent to Hypawave.
+- **Your wallet credentials** — the `NWC_URL` connection string, and `~/.hypawave/wallet.json` when `setup_wallet` provisions a wallet (written `0600`). The server speaks NIP-47 directly to your wallet over its Nostr relay; neither the string nor the file contents are ever sent to Hypawave. For a hosted wallet, `wallet.json` holds the **only copy** of the Coinos username/password — back it up, and never delete it while the wallet holds funds.
 - **Plaintext files** — encryption and decryption are local AES-256-GCM. Hypawave stores only ciphertext.
 
 **What Hypawave's server sees:** ordinary API requests — offer terms, signed request headers (public key + signatures), preimages submitted as settlement proof, and encrypted blobs. Nothing that lets anyone spend from your wallet or impersonate your identity.
@@ -30,6 +30,8 @@ A **local stdio MCP server** for Hypawave's accountless Lightning paths (3a/3b).
 
 The recommended buyer setup (a custodial NWC wallet such as Coinos) means the wallet provider holds those funds and can freeze or censor them. Keep only a small working balance there. Sellers are unaffected: payouts go directly to whatever Lightning Address you control.
 
+`setup_wallet` automates exactly this setup: with explicit operator consent (`confirm: true`) it registers a Coinos account in the operator's name and stores the credentials locally. Hypawave is not the custodian — Coinos is — and Hypawave's servers never receive the credentials. The tool refuses to run without consent and refuses to overwrite an existing wallet file. The only network destination it adds is `coinos.io` (or `COINOS_API_URL`).
+
 ## Dependencies
 
 Runtime dependencies are pinned, widely-used libraries: `@modelcontextprotocol/sdk` (MCP transport), `@getalby/sdk` (NIP-47 client), `@noble/curves`/`@noble/hashes` (audited cryptography), `zod`, `ws`. The only network destinations at runtime are the Hypawave API over HTTPS, your wallet's Nostr relay, and presigned storage URLs returned by the API.

package/dist/index.js

@@ -18,8 +18,36 @@ var API_BASE = process.env.HYPAWAVE_API_URL || "https://hypawave.com";
 var FALLBACK_SPEND_CAP_SATS = 5e4;
 var KEY_DIR = join(homedir(), ".hypawave");
 var KEY_FILE = join(KEY_DIR, "identity.json");
+var WALLET_FILE = join(KEY_DIR, "wallet.json");
 function getNwcUrl() {
-  return process.env.NWC_URL || process.env.HYPAWAVE_NWC_URL || void 0;
+  return process.env.NWC_URL || process.env.HYPAWAVE_NWC_URL || readWalletFile()?.nwc_url;
+}
+function getNwcSource() {
+  if (process.env.NWC_URL || process.env.HYPAWAVE_NWC_URL) return "env";
+  if (readWalletFile()) return "wallet_file";
+  return null;
+}
+function readWalletFile() {
+  try {
+    if (!existsSync(WALLET_FILE)) return void 0;
+    const parsed = JSON.parse(readFileSync(WALLET_FILE, "utf8"));
+    if (typeof parsed?.nwc_url === "string" && parsed.nwc_url.startsWith("nostr+walletconnect://")) {
+      return parsed;
+    }
+  } catch {
+  }
+  return void 0;
+}
+function saveWalletFile(wallet) {
+  mkdirSync(KEY_DIR, { recursive: true, mode: 448 });
+  writeFileSync(WALLET_FILE, JSON.stringify(wallet, null, 2), { mode: 384 });
+  return WALLET_FILE;
+}
+function walletFileExists() {
+  return existsSync(WALLET_FILE);
+}
+function walletFilePath() {
+  return WALLET_FILE;
 }
 function getMaxSpendSatsEnv() {
   const raw = process.env.HYPAWAVE_MAX_SPEND_SATS;
@@ -336,7 +364,18 @@ async function getClient() {
 }
 async function payBolt11(bolt11) {
   const client = await getClient();
-  const result = await client.payInvoice({ invoice: bolt11 });
+  let result;
+  try {
+    result = await client.payInvoice({ invoice: bolt11 });
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    if (/insufficient|balance|not enough|exceeds.*budget|quota/i.test(msg)) {
+      throw new Error(
+        `${msg} \u2014 the agent wallet balance is too low. Call setup_wallet {action:"funding_options", amount_sats:<needed>} and present the funding options to your operator.`
+      );
+    }
+    throw e;
+  }
   if (!result?.preimage || !/^[0-9a-fA-F]{64}$/.test(result.preimage)) {
     throw new Error(
       "wallet paid (or attempted) but returned no valid preimage \u2014 cannot prove settlement; check the payment in your wallet before retrying"
@@ -807,8 +846,255 @@ function registerSellTools(server2) {
   );
 }
 
-// src/tools/status.ts
+// src/tools/setup-wallet.ts
 import { z as z5 } from "zod";
+
+// src/coinos.ts
+import { randomBytes as randomBytes4 } from "crypto";
+var COINOS_API = process.env.COINOS_API_URL || "https://coinos.io/api";
+async function coinos(path, opts = {}) {
+  const res = await fetch(`${COINOS_API}${path}`, {
+    method: opts.body ? "POST" : "GET",
+    headers: {
+      "content-type": "application/json",
+      ...opts.token ? { authorization: `Bearer ${opts.token}` } : {}
+    },
+    body: opts.body ? JSON.stringify(opts.body) : void 0
+  });
+  const text = await res.text();
+  if (!res.ok) {
+    throw new Error(`coinos ${path}: HTTP ${res.status}${text ? ` \u2014 ${text.slice(0, 200)}` : ""}`);
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new Error(`coinos ${path}: non-JSON response`);
+  }
+}
+async function createCoinosWallet() {
+  const username = `hw${randomBytes4(6).toString("hex")}`;
+  const password = randomBytes4(24).toString("base64url");
+  const { token } = await coinos("/register", {
+    body: { user: { username, password } }
+  });
+  if (!token) throw new Error("coinos /register returned no auth token");
+  const apps = await coinos("/apps", { token });
+  const nwc = apps?.find((a) => typeof a?.nwc === "string")?.nwc;
+  if (!nwc || !nwc.startsWith("nostr+walletconnect://")) {
+    throw new Error("coinos returned no NWC connection for the new account");
+  }
+  return {
+    provider: "coinos",
+    username,
+    password,
+    token,
+    nwc_url: nwc,
+    lightning_address: `${username}@${new URL(COINOS_API).host}`,
+    created_at: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+async function createFundingInvoice(token, amountSats) {
+  const inv = await coinos("/invoice", {
+    token,
+    body: { invoice: { type: "lightning", amount: Math.floor(amountSats) } }
+  });
+  if (!inv?.hash || !inv.hash.toLowerCase().startsWith("ln")) {
+    throw new Error("coinos returned no bolt11 for the funding invoice");
+  }
+  return inv.hash;
+}
+async function getOnchainAddress(token) {
+  const inv = await coinos("/invoice", {
+    token,
+    body: { invoice: { type: "bitcoin", amount: 0 } }
+  });
+  if (!inv?.hash || !/^(bc1|[13])[a-zA-Z0-9]{20,}$/.test(inv.hash)) {
+    throw new Error("coinos returned no on-chain deposit address");
+  }
+  return inv.hash;
+}
+async function getFundingOptions(amountSats) {
+  const wallet = readWalletFile();
+  if (!wallet || wallet.provider !== "coinos" || !wallet.token) {
+    return {
+      present_to_operator: [
+        "Fund the agent's Lightning wallet using its own receive/deposit flow (open the wallet app and create a receive invoice or address).",
+        "Instant options once you have an invoice: pay it from Cash App, Coinbase, or any Lightning wallet.",
+        wallet?.lightning_address ? `Or send sats to the wallet's Lightning address: ${wallet.lightning_address}` : ""
+      ].filter(Boolean).join("\n"),
+      ...wallet?.lightning_address ? { lightning_address: wallet.lightning_address } : {}
+    };
+  }
+  const result = { present_to_operator: "" };
+  const lines = [
+    amountSats ? `The agent wallet needs a top-up (~${amountSats} sats). Two ways to fund it:` : "Two ways to fund the agent wallet:"
+  ];
+  if (amountSats && amountSats >= 1) {
+    try {
+      result.lightning_invoice = await createFundingInvoice(wallet.token, amountSats);
+    } catch {
+    }
+  }
+  lines.push(
+    result.lightning_invoice ? `1. INSTANT \u2014 pay this Lightning invoice from Cash App, Coinbase, or any Lightning wallet (settles in seconds):
+${result.lightning_invoice}` : `1. INSTANT \u2014 send sats from any Lightning wallet to the agent's Lightning address: ${wallet.lightning_address}
+   (If your app needs an exact-amount invoice \u2014 Cash App, Coinbase \u2014 ask the agent for one: setup_wallet {action:'funding_options', amount_sats:N}.)`
+  );
+  result.lightning_address = wallet.lightning_address;
+  try {
+    result.onchain_address = await getOnchainAddress(wallet.token);
+    lines.push(
+      `2. FROM AN EXCHANGE WITHOUT LIGHTNING (e.g. Robinhood) \u2014 send BTC on-chain to:
+${result.onchain_address}
+   Arrives after confirmation (~10\u201360 min). Minimum 300 sats; mining fees apply, so best for larger top-ups.`
+    );
+  } catch {
+    lines.push(
+      "2. FROM AN EXCHANGE WITHOUT LIGHTNING (e.g. Robinhood) \u2014 an on-chain deposit address could not be fetched right now; log in at coinos.io to get one, or use the Lightning option."
+    );
+  }
+  lines.push("The agent will detect the funds and continue automatically.");
+  result.present_to_operator = lines.join("\n");
+  return result;
+}
+
+// src/tools/setup-wallet.ts
+var OPERATOR_OPTIONS = [
+  "To buy things automatically, your agent needs a Lightning wallet it can spend from. Three options:",
+  "1. CREATE ONE NOW (recommended for getting started) \u2014 creates a hosted wallet at coinos.io (think prepaid card: funds are held by that service, so keep only small amounts, e.g. $10\u201320 worth of sats; the operator spending cap applies to every payment). Credentials are generated and stored only on this machine \u2014 Hypawave's servers never receive them.",
+  "2. CONNECT YOUR OWN WALLET \u2014 if you already use an NWC-capable wallet (Alby Hub, Coinos, Primal, LNbits, your own node), tell the agent which one and it will walk you through copying its NWC connection string; no account is created anywhere. Note: self-hosted nodes need channel liquidity even for tiny payments.",
+  "3. SKIP \u2014 purchases will return a Lightning invoice to pay manually from any wallet (you'll also need the preimage from your wallet to confirm \u2014 fine for testing, clunky as a routine)."
+].join("\n");
+var NWC_WALLET_GUIDE = [
+  "Ask the operator which wallet they use, then give them the matching steps to copy its NWC connection string (starts with nostr+walletconnect://):",
+  "- Alby Hub: App Store (or Settings) \u2192 Connections \u2192 Add connection \u2192 set a budget \u2192 copy the connection secret.",
+  "- Coinos (existing account): coinos.io \u2192 Settings \u2192 Nostr Wallet Connect (Apps) \u2192 create/copy the connection string.",
+  "- Primal: Wallet \u2192 Settings \u2192 Connected apps \u2192 New connection \u2192 copy the string.",
+  "- LNbits: enable the NWC Service extension on your wallet \u2192 create a connection \u2192 copy the pairing URL.",
+  "- Self-hosted node (LND/CLN): run an NWC bridge (e.g. Alby Hub connected to the node) and create a connection there. Reminder: the node needs outbound channel liquidity.",
+  "Then re-call setup_wallet with {action:'connect_own', nwc_url:'<the string>'}."
+].join("\n");
+var NWC_URI_RE = /^nostr\+walletconnect:\/\/[0-9a-f]{64}\?/i;
+async function tryBalance() {
+  try {
+    const balance_sats = await Promise.race([
+      getBalanceSats(),
+      new Promise((_, reject) => setTimeout(() => reject(new Error("timed out after 15s")), 15e3))
+    ]);
+    return { balance_sats };
+  } catch (e) {
+    return { balance_sats: null, wallet_error: e instanceof Error ? e.message : String(e) };
+  }
+}
+function registerSetupWalletTools(server2) {
+  server2.registerTool(
+    "setup_wallet",
+    {
+      title: "Set up the agent's Lightning wallet",
+      description: "One-time wallet setup so purchases can pay automatically. Call with no arguments first: it returns the operator-facing options \u2014 present them to the operator verbatim and let them choose; do not choose for them. Then call {action:'create_hosted', confirm:true} ONLY after the operator explicitly agreed (creates a hosted custodial wallet at coinos.io; credentials are stored locally in ~/.hypawave/wallet.json and never sent to Hypawave), or {action:'connect_own'} to use an existing NWC wallet \u2014 without nwc_url it returns per-wallet steps to help the operator find their connection string. Also: {action:'funding_options', amount_sats?} returns operator-facing funding instructions for the configured wallet (instant Lightning invoice/address + on-chain deposit address for exchanges without Lightning, e.g. Robinhood) \u2014 present them verbatim whenever the wallet needs sats. The NWC_URL env var, when set, always takes precedence over anything configured here.",
+      inputSchema: {
+        action: z5.enum(["create_hosted", "connect_own", "funding_options"]).optional().describe("Omit to get the options to present to the operator"),
+        confirm: z5.boolean().optional().describe("Required true for create_hosted \u2014 set only after the operator explicitly agreed"),
+        nwc_url: z5.string().optional().describe("For connect_own: the wallet's NWC connection string"),
+        amount_sats: z5.number().int().positive().optional().describe("For funding_options: mint an exact-amount Lightning funding invoice for this many sats")
+      }
+    },
+    async ({ action, confirm, nwc_url, amount_sats }) => {
+      const envSet = Boolean(process.env.NWC_URL || process.env.HYPAWAVE_NWC_URL);
+      if (action === "funding_options") {
+        if (!getNwcUrl()) {
+          return jsonResult({
+            ok: false,
+            message: "No wallet configured yet \u2014 run setup_wallet first, then request funding options."
+          });
+        }
+        const funding2 = await getFundingOptions(amount_sats);
+        return jsonResult({ ok: true, ...funding2 });
+      }
+      if (!action) {
+        const configured = Boolean(getNwcUrl());
+        return jsonResult({
+          configured,
+          source: getNwcSource(),
+          ...configured ? { message: "A wallet is already configured \u2014 no setup needed. Call wallet_status for the balance." } : { present_to_operator: OPERATOR_OPTIONS }
+        });
+      }
+      if (envSet) {
+        return jsonResult({
+          ok: false,
+          message: "NWC_URL is set in the environment and always takes precedence \u2014 unset it in the MCP config first if you want a different wallet."
+        });
+      }
+      if (action === "connect_own") {
+        if (!nwc_url) {
+          return jsonResult({
+            ok: false,
+            needs_nwc_url: true,
+            present_to_operator: NWC_WALLET_GUIDE
+          });
+        }
+        if (!NWC_URI_RE.test(nwc_url) || !/[?&]secret=[0-9a-f]{64}/i.test(nwc_url)) {
+          throw new Error(
+            "connect_own requires a valid NWC connection string: nostr+walletconnect://<64-hex-pubkey>?relay=\u2026&secret=<64-hex>. Call {action:'connect_own'} without nwc_url for per-wallet steps to find it."
+          );
+        }
+        if (walletFileExists()) {
+          throw new Error(
+            `${walletFilePath()} already exists and may hold a funded wallet's only credentials \u2014 back it up and remove it manually first.`
+          );
+        }
+        const path2 = saveWalletFile({
+          provider: "custom",
+          nwc_url,
+          created_at: (/* @__PURE__ */ new Date()).toISOString()
+        });
+        const check = await tryBalance();
+        return jsonResult({
+          ok: true,
+          provider: "custom",
+          saved_to: path2,
+          connection_verified: check.balance_sats !== null,
+          ...check,
+          next: check.balance_sats !== null ? "Wallet connected \u2014 purchases now pay automatically under the spending cap." : "Saved, but the connection could not be verified yet \u2014 check the NWC string and wallet, then call wallet_status."
+        });
+      }
+      if (walletFileExists()) {
+        const existing = readWalletFile();
+        return jsonResult({
+          ok: true,
+          already_exists: true,
+          provider: existing?.provider ?? "unknown",
+          lightning_address: existing?.lightning_address ?? null,
+          credentials_file: walletFilePath(),
+          message: "A wallet file already exists \u2014 reusing it. Fund it or remove the file manually to start over."
+        });
+      }
+      if (!confirm) {
+        return jsonResult({
+          ok: false,
+          needs_confirmation: true,
+          present_to_operator: OPERATOR_OPTIONS,
+          message: "create_hosted opens a custodial account at coinos.io in the operator's name. Present the options above, and retry with confirm:true only after the operator explicitly chose option 1."
+        });
+      }
+      const wallet = await createCoinosWallet();
+      const path = saveWalletFile(wallet);
+      const funding = await getFundingOptions().catch(() => null);
+      return jsonResult({
+        ok: true,
+        provider: "coinos",
+        lightning_address: wallet.lightning_address,
+        credentials_file: path,
+        ...funding ? { funding } : {},
+        next: `Fund it now (start small \u2014 5,000\u201350,000 sats): present the funding options above to the operator verbatim \u2014 instant via Lightning (Cash App, Coinbase, or any Lightning wallet), or on-chain from an exchange without Lightning (e.g. Robinhood; slower, mining fees). Then wallet_status shows the balance and purchases pay automatically under the spending cap.`,
+        important: `Custodial wallet \u2014 coinos.io holds the funds; keep only small amounts. ${path} contains the ONLY copy of the credentials: back it up, and never delete it while the wallet holds funds.`
+      });
+    }
+  );
+}
+
+// src/tools/status.ts
+import { z as z6 } from "zod";
 function registerStatusTools(server2) {
   server2.registerTool(
     "my_offers",
@@ -816,7 +1102,7 @@ function registerStatusTools(server2) {
       title: "List your own offers (seller)",
       description: "List all offers created by this server's seller identity (pubkey-signed). Shows each offer's status, capacity usage, and activation window \u2014 use manage_offer for details/renewal.",
       inputSchema: {
-        status: z5.string().optional().describe("Filter by offer status")
+        status: z6.string().optional().describe("Filter by offer status")
       }
     },
     async ({ status }) => jsonResult(await hw("/api/offers/list", { method: "GET", signed: true, query: { status } }))
@@ -827,11 +1113,11 @@ function registerStatusTools(server2) {
       title: "List your sales (seller reconciliation)",
       description: "List settled/pending sales for this seller identity (pubkey-signed). kind=offers \u2192 Path 3b payment intents (via /api/offers/list-payments, filterable by offer_id); kind=invoices \u2192 Path 3a invoices (via /api/offers/list-invoices). Returns payment_hash/preimage per sale \u2014 the authoritative way to reconcile missed execution_webhook deliveries.",
       inputSchema: {
-        kind: z5.enum(["offers", "invoices"]),
-        offer_id: z5.string().uuid().optional().describe("Filter to one offer (kind=offers only)"),
-        status: z5.string().optional(),
-        limit: z5.number().int().min(1).max(100).optional(),
-        offset: z5.number().int().min(0).optional()
+        kind: z6.enum(["offers", "invoices"]),
+        offer_id: z6.string().uuid().optional().describe("Filter to one offer (kind=offers only)"),
+        status: z6.string().optional(),
+        limit: z6.number().int().min(1).max(100).optional(),
+        offset: z6.number().int().min(0).optional()
       }
     },
     async ({ kind, offer_id, status, limit, offset }) => {
@@ -851,10 +1137,10 @@ function registerStatusTools(server2) {
       title: "Fetch a settlement receipt for a past purchase",
       description: "Retrieve the durable settlement record for a purchase you made. For an offer purchase (Path 3b) pass payment_intent_id + payer_secret (both returned by buy_offer). For an invoice (Path 2/3a) pass invoice_id + preimage (pay_invoice returned the preimage).",
       inputSchema: {
-        payment_intent_id: z5.string().uuid().optional(),
-        payer_secret: z5.string().optional().describe("Required with payment_intent_id"),
-        invoice_id: z5.string().optional(),
-        preimage: z5.string().regex(/^[0-9a-fA-F]{64}$/).optional().describe("Required with invoice_id")
+        payment_intent_id: z6.string().uuid().optional(),
+        payer_secret: z6.string().optional().describe("Required with payment_intent_id"),
+        invoice_id: z6.string().optional(),
+        preimage: z6.string().regex(/^[0-9a-fA-F]{64}$/).optional().describe("Required with invoice_id")
       }
     },
     async ({ payment_intent_id, payer_secret, invoice_id, preimage }) => {
@@ -879,9 +1165,9 @@ function registerStatusTools(server2) {
       title: "Check settlement/unlock status of a purchase",
       description: "Non-destructive status check. For an offer purchase (Path 3b) pass payment_intent_id + payer_secret \u2014 returns status and the claim_token once settled. For invoices (Path 2/3a) pass invoice_ids \u2014 returns unlock status per invoice.",
       inputSchema: {
-        payment_intent_id: z5.string().uuid().optional(),
-        payer_secret: z5.string().optional().describe("Required with payment_intent_id"),
-        invoice_ids: z5.array(z5.string()).optional().describe("Invoice ids to check (Path 2/3a)")
+        payment_intent_id: z6.string().uuid().optional(),
+        payer_secret: z6.string().optional().describe("Required with payment_intent_id"),
+        invoice_ids: z6.array(z6.string()).optional().describe("Invoice ids to check (Path 2/3a)")
       }
     },
     async ({ payment_intent_id, payer_secret, invoice_ids }) => {
@@ -929,9 +1215,10 @@ function registerWalletTools(server2) {
       return jsonResult({
         wallet: {
           nwc_configured: nwcConfigured(),
+          source: getNwcSource(),
           balance_sats,
           ...wallet_error ? { error: wallet_error } : {},
-          mode: nwcConfigured() ? "automatic payments" : "manual mode \u2014 tools return bolt11s to pay externally"
+          mode: nwcConfigured() ? "automatic payments" : "manual mode \u2014 tools return bolt11s to pay externally; call setup_wallet to configure a wallet"
         },
         spending_cap: await getSpendCapSats().catch((e) => ({ error: String(e) })),
         seller_pubkey,
@@ -945,7 +1232,7 @@ function registerWalletTools(server2) {
 // src/index.ts
 var server = new McpServer({
   name: "hypawave",
-  version: "0.1.2"
+  version: "0.2.0"
 });
 registerDiscoverTools(server);
 registerBuyTools(server);
@@ -953,6 +1240,10 @@ registerInvoiceBuyTools(server);
 registerSellTools(server);
 registerStatusTools(server);
 registerWalletTools(server);
+registerSetupWalletTools(server);
 var transport = new StdioServerTransport();
 await server.connect(transport);
-console.error("hypawave-mcp ready (15 tools; NWC " + (process.env.NWC_URL || process.env.HYPAWAVE_NWC_URL ? "configured" : "not configured \u2014 manual mode") + ")");
+var nwcSource = getNwcSource();
+console.error(
+  "hypawave-mcp ready (16 tools; NWC " + (nwcSource ? `configured via ${nwcSource}` : "not configured \u2014 manual mode; setup_wallet available") + ")"
+);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypawave/mcp",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "mcpName": "io.github.hypawave/mcp",
   "description": "MCP server for Hypawave — agents buy, sell, and discover over Bitcoin Lightning: search the public offer marketplace, list offers in it or sell agent-to-agent, and settle non-custodially wallet-to-wallet. Verified preimage unlocks files, data, APIs, and compute.",
   "type": "module",