@hypawave/mcp 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+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.1.0] - 2026-07-02
+
+### Added
+
+- Initial release: local stdio MCP server exposing the Hypawave accountless paths (3a/3b) as 15 tools.
+- Buyer tools: `search_offers`, `get_offer`, `buy_offer`, `confirm_payment`, `download_files`, `pay_invoice`, `get_receipt`, `check_payment`.
+- Seller tools: `create_offer`, `attach_file`, `manage_offer`, `create_invoice`, `my_offers`, `list_sales`.
+- Utility: `wallet_status`.
+- NWC (Nostr Wallet Connect) payment support with automatic preimage capture; manual bolt11 fallback when no wallet is configured.
+- Operator spending cap enforced in code with bolt11 amount cross-check: `HYPAWAVE_MAX_SPEND_SATS`, defaulting to the platform's live `max_invoice_usd` (converted at the current BTC price) when unset.
+- secp256k1 pubkey-signature auth (llms.txt spec, verified against the published test vector); identity auto-generated to `~/.hypawave/identity.json`.
+- Client-side AES-256-GCM encrypt/decrypt with `ciphertext_sha256` content-commitment verification.
+- Activation settlement handling: after paying an activation/renewal fee, seller tools wait on `activation_window_end` (the authoritative payability signal) and nudge the settlement fallback if the payment webhook is slow — results report `activated` + `activation_window_end`.

package/LICENSE

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

package/README.md

@@ -0,0 +1,133 @@
+# @hypawave/mcp
+
+[![CI](https://github.com/hypawave/mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/hypawave/mcp/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/%40hypawave%2Fmcp.svg)](https://www.npmjs.com/package/@hypawave/mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/hypawave/mcp/blob/main/LICENSE)
+[![Node >= 20](https://img.shields.io/badge/Node-%3E%3D20-brightgreen.svg)](https://nodejs.org)
+
+An MCP server that lets autonomous agents **buy, sell, and discover** over [Hypawave](https://hypawave.com)'s accountless Bitcoin Lightning paths. Agents can search the public offer directory and list their own offers in it — or sell privately, agent-to-agent, by sharing an offer id — and settle directly wallet-to-wallet: a **non-custodial marketplace, not a hub**. Buyers pay creators directly; a verified Lightning preimage is the proof that unlocks the result (files, data, API access, compute). Hypawave never holds principal funds.
+
+Works with any MCP-capable agent: Claude Code, Claude Desktop, Codex, Cursor, Windsurf, custom agents. Runs locally — your keys and wallet credentials never leave your machine.
+
+## Install
+
+The server command is the same everywhere: `npx -y @hypawave/mcp`. Only the config file differs per client.
+
+**Claude Code** — `.mcp.json` in your project (or `claude mcp add hypawave -- npx -y @hypawave/mcp`):
+
+```json
+{
+  "mcpServers": {
+    "hypawave": {
+      "command": "npx",
+      "args": ["-y", "@hypawave/mcp"],
+      "env": {
+        "NWC_URL": "nostr+walletconnect://...",
+        "HYPAWAVE_MAX_SPEND_SATS": "10000"
+      }
+    }
+  }
+}
+```
+
+**Claude Desktop** — same JSON block under `mcpServers` in `claude_desktop_config.json`.
+
+**Codex** — `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.hypawave]
+command = "npx"
+args = ["-y", "@hypawave/mcp"]
+env = { NWC_URL = "nostr+walletconnect://...", HYPAWAVE_MAX_SPEND_SATS = "10000" }
+```
+
+**Cursor** — same JSON block in `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global).
+
+All env vars are optional — with no `NWC_URL` the server runs in manual mode (see Wallet below).
+
+## Tools (15)
+
+| Tool | What it does |
+|---|---|
+| **Discover & buy** | |
+| `search_offers` | Search the public marketplace directory (text, category, tags, sort, pagination) |
+| `get_offer` | Read an offer's full terms before buying |
+| `buy_offer` | Buy an offer end-to-end: pay via NWC, confirm with preimage, poll to settled → `claim_token` |
+| `confirm_payment` | Submit a preimage for a bolt11 you paid manually (no-NWC mode) |
+| `download_files` | Fetch keys, verify the seller's `ciphertext_sha256` commitment, decrypt locally, save to disk |
+| `pay_invoice` | Settle a one-off invoice payload a seller handed you (Path 2/3a), incl. file retrieval |
+| `get_receipt` | Durable settlement receipt for a past purchase |
+| `check_payment` | Status/unlock check for payment intents or invoices |
+| **Sell** | |
+| `create_offer` | Create a reusable offer — private by default, or `is_public: true` to list it in the marketplace |
+| `attach_file` | Encrypt a local file client-side (AES-256-GCM), upload, register with content commitment |
+| `manage_offer` | Offer status / renew the activation window / buy more capacity / deactivate |
+| `create_invoice` | One-off invoice for a single buyer (Path 3a) |
+| `my_offers` | List the offers owned by your seller identity |
+| `list_sales` | List your settled sales (payments/invoices) — reconcile missed webhooks |
+| **Utility** | |
+| `wallet_status` | Wallet balance, seller pubkey, spending cap, live platform fees/limits |
+
+## Buy in three calls
+
+```text
+search_offers { q: "market data" }            → pick an offer id
+get_offer     { offer_id }                    → check price + terms
+buy_offer     { offer_id }                    → paid, settled, claim_token returned
+download_files{ payment_intent_id, claim_token, output_dir }   (file offers)
+```
+
+For execution offers (paid APIs/compute), `buy_offer` returns the preimage — present `{payment_intent_id, preimage}` to the seller's API as your credential.
+
+## Sell in four calls
+
+```text
+create_offer { amount, pricing_type: "sats", description,
+               payment_destination: "you@getalby.com", max_payments: 100,
+               is_public: true, title, category, output_type }   → offer + activation fee bolt11
+attach_file  { offer_id, file_path }                             → encrypted + committed (BEFORE activation!)
+manage_offer { offer_id, action: "renew", pay_fee: true }        → pays the pending fee via NWC (or pay the bolt11 from any wallet)
+my_offers    {}                                                  → confirm it's active; share or let buyers find it
+```
+
+No files to attach? Skip the middle steps: `create_offer` with `pay_activation_fee: true` creates, pays, and activates in one call. Either way the tool waits for settlement and returns `activated: true` with the live window end — typically within seconds.
+
+Selling needs **no special wallet** — payouts go straight to your Lightning Address. Omit `is_public` to keep an offer private and share the `offer_id` directly, agent-to-agent. The one-time activation fee (`unit_price × max_payments × fee%`) is Hypawave's only charge; principal never touches Hypawave.
+
+## Wallet (buyers)
+
+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 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. |
+| `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`). |
+
+## Safety model
+
+- **Spending cap**: every principal/fee payment is checked against the effective cap before paying — `HYPAWAVE_MAX_SPEND_SATS` if set, otherwise the platform's own `max_invoice_usd` converted at the live BTC price. The bolt11 amount is cross-checked against the server quote. Per-purchase bounds via `expected_max_sats`.
+- **Content integrity**: downloaded files are verified against the seller's `ciphertext_sha256` commitment before decrypting; encryption/decryption is local AES-256-GCM — Hypawave never sees plaintext.
+- **Non-custodial**: principal flows buyer→seller wallet-to-wallet. Settlement is final — no refunds. `payment_count` on marketplace offers is sales volume, not a trust score.
+
+## Authoritative references
+
+- Operating manual: https://hypawave.com/llms.txt
+- OpenAPI spec: https://hypawave.com/.well-known/openapi.json
+- Docs: https://hypawave.com/docs · Architecture: https://hypawave.com/architecture
+
+## Development
+
+```bash
+npm install
+npm test          # vitest unit suite (signer verified against the published llms.txt test vector)
+npm run build     # tsup → dist/
+node scripts/smoke.mjs   # LIVE end-to-end purchase of the 100-sat compute demo (spends real sats; needs NWC_URL)
+```
+
+MIT

package/SECURITY.md

@@ -0,0 +1,45 @@
+# Security
+
+## What this package is
+
+A **local stdio MCP server** for Hypawave's accountless Lightning paths (3a/3b). It runs on the operator's machine as a subprocess of their agent client. There is **no hosted component and no custody here** — the server is a pure client of the public Hypawave API; buyers pay creators directly over Lightning.
+
+## Trust model
+
+**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.
+- **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.
+
+## Spending guardrails (and their limits)
+
+- **Per-payment cap, enforced in code before paying:** `HYPAWAVE_MAX_SPEND_SATS` if set, otherwise derived live from the platform's own maximum invoice size. The bolt11 amount is additionally cross-checked against the server's quote; undecodable or zero-amount invoices are refused.
+- Tools accept a per-call `expected_max_sats` bound for tighter, task-level limits.
+- **What the cap does NOT do:** it is per-payment, not a daily budget — a compromised or misbehaving agent could make many cap-sized payments. Bound total exposure at the wallet layer: fund the wallet with a working balance only, and use your wallet's own NWC budget controls (e.g. a connection-level `max_amount`) as the outer wall.
+- Hypawave enforces no spending limits server-side. The cap, your wallet balance, and your wallet's NWC budget are the only guardrails.
+
+## Payment and delivery integrity
+
+- **Settlement is the only gate.** A verified Lightning preimage (`SHA-256(preimage) == payment_hash`) is the proof that unlocks a purchase. Settlement is final — there are no refunds.
+- **Content commitment verified before decrypt.** Downloaded ciphertext is checked against the seller's `ciphertext_sha256` commitment; a mismatch aborts before decryption. Server-supplied filenames are sanitized before writing to disk.
+- **`payment_count` on marketplace offers is settled-sales volume, not a trust score.** Settlement releases delivery regardless of buyer satisfaction — evaluate offer terms before paying.
+
+## Custodial-wallet tradeoff
+
+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.
+
+## 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.
+
+## Verifying
+
+```bash
+npm test    # 32 unit tests, including the signer against Hypawave's published llms.txt test vector
+```
+
+## Reporting a vulnerability
+
+Email **security@hypawave.com** (or support@hypawave.com). Please do not open a public issue for security-sensitive reports. We aim to acknowledge within a few business days.

package/dist/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/index.js

@@ -0,0 +1,958 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/tools/discover.ts
+import { z } from "zod";
+
+// src/config.ts
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+import { randomBytes } from "crypto";
+import { secp256k1 } from "@noble/curves/secp256k1";
+import { bytesToHex } from "@noble/hashes/utils";
+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");
+function getNwcUrl() {
+  return process.env.NWC_URL || process.env.HYPAWAVE_NWC_URL || void 0;
+}
+function getMaxSpendSatsEnv() {
+  const raw = process.env.HYPAWAVE_MAX_SPEND_SATS;
+  if (!raw) return null;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n <= 0) return null;
+  return Math.floor(n);
+}
+function getPrivKey() {
+  const env = process.env.HYPAWAVE_PRIVKEY;
+  if (env) {
+    if (!/^[0-9a-fA-F]{64}$/.test(env)) {
+      throw new Error("HYPAWAVE_PRIVKEY must be a 32-byte hex string (64 chars)");
+    }
+    return env.toLowerCase();
+  }
+  if (existsSync(KEY_FILE)) {
+    const saved = JSON.parse(readFileSync(KEY_FILE, "utf8"));
+    if (typeof saved.privkey === "string" && /^[0-9a-f]{64}$/.test(saved.privkey)) {
+      return saved.privkey;
+    }
+    throw new Error(`Corrupt identity file at ${KEY_FILE} \u2014 restore it or set $HYPAWAVE_PRIVKEY`);
+  }
+  const privkey = generatePrivKey();
+  mkdirSync(KEY_DIR, { recursive: true, mode: 448 });
+  writeFileSync(KEY_FILE, JSON.stringify({ privkey, created_at: (/* @__PURE__ */ new Date()).toISOString() }, null, 2), {
+    mode: 384
+  });
+  return privkey;
+}
+function getPubKey() {
+  return bytesToHex(secp256k1.getPublicKey(getPrivKey(), true));
+}
+function generatePrivKey() {
+  for (; ; ) {
+    const candidate = randomBytes(32);
+    try {
+      secp256k1.getPublicKey(candidate, true);
+      return bytesToHex(candidate);
+    } catch {
+    }
+  }
+}
+
+// src/signer.ts
+import { createHash, randomBytes as randomBytes2 } from "crypto";
+import { secp256k1 as secp256k12 } from "@noble/curves/secp256k1";
+import { bytesToHex as bytesToHex2, hexToBytes } from "@noble/hashes/utils";
+var sha256Hex = (input) => createHash("sha256").update(input).digest("hex");
+function signRequest({
+  body,
+  privKey,
+  timestamp,
+  nonce
+}) {
+  const pubKey = bytesToHex2(secp256k12.getPublicKey(privKey, true));
+  let fullBody = body;
+  let termsHash = null;
+  if (body) {
+    termsHash = sha256Hex(JSON.stringify(body));
+    const termsSig = secp256k12.sign(hexToBytes(termsHash), privKey, { lowS: true });
+    fullBody = { ...body, signed_payload_hash: termsHash, signature: termsSig.toDERHex() };
+  }
+  const bodyStr = fullBody ? JSON.stringify(fullBody) : "";
+  const bodyHash = sha256Hex(bodyStr);
+  const ts = timestamp ?? Math.floor(Date.now() / 1e3).toString();
+  const nce = nonce ?? randomBytes2(16).toString("hex");
+  const canonicalHash = sha256Hex(`${bodyHash}:${ts}:${nce}`);
+  const authSig = secp256k12.sign(hexToBytes(canonicalHash), privKey, { lowS: true });
+  return {
+    headers: {
+      "Content-Type": "application/json",
+      "x-pubkey": pubKey,
+      "x-signature": authSig.toDERHex(),
+      "x-signed-payload-hash": bodyHash,
+      "x-timestamp": ts,
+      "x-nonce": nce
+    },
+    body: bodyStr || void 0,
+    debug: { pubKey, termsHash, bodyHash, canonicalHash }
+  };
+}
+
+// src/api.ts
+var HypawaveApiError = class extends Error {
+  constructor(status, code, message) {
+    super(message);
+    this.status = status;
+    this.code = code;
+    this.name = "HypawaveApiError";
+  }
+  status;
+  code;
+};
+async function hw(path, opts = {}) {
+  const method = opts.method ?? (opts.body !== void 0 ? "POST" : "GET");
+  const url = new URL(path, API_BASE);
+  for (const [k, v] of Object.entries(opts.query ?? {})) {
+    if (v !== void 0) url.searchParams.set(k, String(v));
+  }
+  let headers = { "Content-Type": "application/json" };
+  let bodyStr;
+  if (opts.signed) {
+    const signed = signRequest({ body: opts.body ?? null, privKey: getPrivKey() });
+    headers = signed.headers;
+    bodyStr = signed.body;
+  } else if (opts.body !== void 0 && opts.body !== null) {
+    bodyStr = JSON.stringify(opts.body);
+  }
+  const res = await fetch(url, { method, headers, body: bodyStr });
+  const text = await res.text();
+  let json;
+  try {
+    json = text ? JSON.parse(text) : void 0;
+  } catch {
+    json = void 0;
+  }
+  if (!res.ok) {
+    const code = json?.error || `http_${res.status}`;
+    const message = json?.message || text.slice(0, 300) || res.statusText;
+    throw new HypawaveApiError(res.status, code, message);
+  }
+  return json ?? {};
+}
+function isApiError(e, code) {
+  return e instanceof HypawaveApiError && (code === void 0 || e.code === code);
+}
+
+// src/util.ts
+import { basename } from "path";
+
+// src/bolt11.ts
+var HRP_RE = /^ln(?:bcrt|tbs|tb|bc)(\d+)([munp]?)1/i;
+var MULTIPLIER_SATS = {
+  // 1 BTC = 1e8 sats; m=1e-3 BTC, u=1e-6, n=1e-9, p=1e-12
+  "": 1e8,
+  m: 1e5,
+  u: 100,
+  n: 0.1,
+  p: 1e-4
+};
+function bolt11AmountSats(bolt11) {
+  const m = HRP_RE.exec(bolt11.trim());
+  if (!m) return null;
+  const value = Number(m[1]);
+  if (!Number.isFinite(value)) return null;
+  return Math.ceil(value * MULTIPLIER_SATS[m[2].toLowerCase()]);
+}
+
+// src/util.ts
+var cachedDerivedCap = null;
+var DERIVED_CAP_TTL_MS = 5 * 6e4;
+async function getSpendCapSats() {
+  const envCap = getMaxSpendSatsEnv();
+  if (envCap !== null) return { cap: envCap, source: "HYPAWAVE_MAX_SPEND_SATS" };
+  if (cachedDerivedCap && Date.now() - cachedDerivedCap.fetchedAt < DERIVED_CAP_TTL_MS) {
+    return { cap: cachedDerivedCap.value, source: "platform max_invoice_usd (cached)" };
+  }
+  try {
+    const s = await hw("/api/public-settings");
+    if (s.max_invoice_usd && s.btc_usd_price && s.btc_usd_price > 0) {
+      const cap = Math.ceil(s.max_invoice_usd / s.btc_usd_price * 1e8);
+      cachedDerivedCap = { value: cap, fetchedAt: Date.now() };
+      return { cap, source: `platform max_invoice_usd ($${s.max_invoice_usd} @ $${s.btc_usd_price}/BTC)` };
+    }
+  } catch {
+  }
+  return { cap: FALLBACK_SPEND_CAP_SATS, source: "static fallback (platform settings unreachable)" };
+}
+async function assertWithinSpendCap(amountSats, context) {
+  if (amountSats === null) {
+    throw new Error(
+      `${context}: could not determine the invoice amount \u2014 refusing to auto-pay. Pay manually and use confirm_payment.`
+    );
+  }
+  const { cap, source } = await getSpendCapSats();
+  if (amountSats > cap) {
+    throw new Error(
+      `${context}: amount ${amountSats} sats exceeds the spending cap of ${cap} sats (${source}). Not paid. Raise HYPAWAVE_MAX_SPEND_SATS or pay manually and use confirm_payment.`
+    );
+  }
+}
+function effectiveAmountSats(bolt11, quotedSats) {
+  const decoded = bolt11AmountSats(bolt11);
+  if (decoded !== null && quotedSats !== void 0 && Math.abs(decoded - quotedSats) > 1) {
+    throw new Error(
+      `bolt11 amount (${decoded} sats) does not match the quoted amount (${quotedSats} sats) \u2014 refusing to pay`
+    );
+  }
+  return decoded ?? quotedSats ?? null;
+}
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+async function pollUntil(fn, { timeoutMs = 6e4, intervalMs = 2500 } = {}) {
+  const deadline = Date.now() + timeoutMs;
+  for (; ; ) {
+    const result = await fn();
+    if (result !== null) return result;
+    if (Date.now() + intervalMs > deadline) return null;
+    await sleep(intervalMs);
+  }
+}
+function safeFilename(name, fallback) {
+  const base = basename(name || "").replace(/[\x00-\x1f\x7f]/g, "").trim();
+  if (!base || base === "." || base === "..") return fallback;
+  return base;
+}
+function jsonResult(data) {
+  return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+}
+
+// src/tools/discover.ts
+function registerDiscoverTools(server2) {
+  server2.registerTool(
+    "search_offers",
+    {
+      title: "Search the Hypawave public offer directory",
+      description: "Browse opt-in public offers (data, APIs, compute, files) purchasable over Bitcoin Lightning. Returns id, title, category, tags, output_type, input_schema, price, and payment_count (settled-sales volume \u2014 NOT a trust or quality guarantee). Buy a result with buy_offer. Note: many offers are private (agent-to-agent by direct offer_id) and never appear here.",
+      inputSchema: {
+        q: z.string().optional().describe("Free-text search over title/description"),
+        category: z.enum(["data", "api", "compute", "media", "software", "access", "action", "other"]).optional(),
+        tags: z.string().optional().describe("Comma-separated tags; results must match all"),
+        sort: z.enum(["newest", "settled"]).optional().describe("Default newest"),
+        limit: z.number().int().min(1).max(50).optional(),
+        cursor: z.string().optional().describe("Pagination cursor from next_cursor (newest sort)"),
+        offset: z.number().int().min(0).optional().describe("Pagination offset (settled sort)")
+      }
+    },
+    async (args) => jsonResult(await hw("/api/offers/public", { query: { ...args } }))
+  );
+  server2.registerTool(
+    "get_offer",
+    {
+      title: "Read a Hypawave offer's terms",
+      description: "Fetch an offer's full terms before buying: amount, currency, pricing_type, description, creator_pubkey, status, file_count, remaining capacity (max_payments vs payment_count), and metadata. Always read and evaluate the terms before paying.",
+      inputSchema: {
+        offer_id: z.string().uuid().describe("The offer id")
+      }
+    },
+    async ({ offer_id }) => jsonResult(await hw(`/api/offers/${offer_id}`))
+  );
+}
+
+// src/tools/buy.ts
+import { mkdirSync as mkdirSync2, writeFileSync as writeFileSync2 } from "fs";
+import { join as join2, resolve } from "path";
+import { z as z2 } from "zod";
+
+// src/crypto.ts
+import { createCipheriv, createDecipheriv, createHash as createHash2, randomBytes as randomBytes3 } from "crypto";
+function sha256HexOf(data) {
+  return createHash2("sha256").update(data).digest("hex");
+}
+function encryptFile(plaintext) {
+  const key = randomBytes3(32);
+  const iv = randomBytes3(12);
+  const cipher = createCipheriv("aes-256-gcm", key, iv);
+  const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final(), cipher.getAuthTag()]);
+  return {
+    ciphertext,
+    keyB64: key.toString("base64"),
+    ivHex: iv.toString("hex"),
+    ciphertextSha256: sha256HexOf(ciphertext)
+  };
+}
+function decryptFile(ciphertext, keyB64, ivHex) {
+  if (ciphertext.length < 16) throw new Error("ciphertext too short \u2014 missing GCM auth tag");
+  const key = Buffer.from(keyB64, "base64");
+  if (key.length !== 32) throw new Error("encryption key must be 32 bytes (AES-256)");
+  const iv = Buffer.from(ivHex, "hex");
+  const tag = ciphertext.subarray(ciphertext.length - 16);
+  const data = ciphertext.subarray(0, ciphertext.length - 16);
+  const decipher = createDecipheriv("aes-256-gcm", key, iv);
+  decipher.setAuthTag(tag);
+  return Buffer.concat([decipher.update(data), decipher.final()]);
+}
+function verifyCommitment(ciphertext, expectedSha256) {
+  if (!expectedSha256) return;
+  const actual = sha256HexOf(ciphertext);
+  if (actual !== expectedSha256.toLowerCase()) {
+    throw new Error(
+      `content mismatch \u2014 downloaded bytes (sha256 ${actual}) do not match the seller's commitment (${expectedSha256}); aborting before decrypt`
+    );
+  }
+}
+function paymentHashFromPreimage(preimageHex) {
+  if (!/^[0-9a-fA-F]{64}$/.test(preimageHex)) {
+    throw new Error("preimage must be a 32-byte hex string (64 chars)");
+  }
+  return createHash2("sha256").update(Buffer.from(preimageHex, "hex")).digest("hex");
+}
+
+// src/nwc.ts
+var clientPromise = null;
+function nwcConfigured() {
+  return Boolean(getNwcUrl());
+}
+async function getClient() {
+  if (!clientPromise) {
+    clientPromise = (async () => {
+      const url = getNwcUrl();
+      if (!url) throw new Error("NWC_URL is not set \u2014 wallet payments unavailable (manual mode only)");
+      if (typeof globalThis.WebSocket === "undefined") {
+        const ws = await import("ws");
+        globalThis.WebSocket = ws.default;
+      }
+      const { nwc } = await import("@getalby/sdk");
+      return new nwc.NWCClient({ nostrWalletConnectUrl: url });
+    })();
+    clientPromise.catch(() => {
+      clientPromise = null;
+    });
+  }
+  return clientPromise;
+}
+async function payBolt11(bolt11) {
+  const client = await getClient();
+  const result = await client.payInvoice({ invoice: bolt11 });
+  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"
+    );
+  }
+  return { preimage: result.preimage.toLowerCase() };
+}
+async function getBalanceSats() {
+  const client = await getClient();
+  const { balance } = await client.getBalance();
+  return Math.floor(balance / 1e3);
+}
+
+// src/tools/buy.ts
+async function confirmAndClaim(paymentIntentId, preimage, payerSecret) {
+  const confirm = await hw(`/api/offers/payment-intent/${paymentIntentId}/confirm`, {
+    body: { preimage, payer_secret: payerSecret }
+  });
+  const settled = await pollUntil(async () => {
+    const s = await hw(`/api/offers/payment-intent/${paymentIntentId}/status`, {
+      query: { secret: payerSecret }
+    });
+    return s.status === "settled" ? s : null;
+  });
+  return { confirm, settled };
+}
+function registerBuyTools(server2) {
+  server2.registerTool(
+    "buy_offer",
+    {
+      title: "Buy a Hypawave offer (pay over Lightning)",
+      description: "Purchase an offer end-to-end. With an NWC wallet configured (NWC_URL): fetches a creator-direct bolt11, enforces the operator spending cap, pays it, submits the settlement preimage, and polls until settled \u2014 returns a claim_token for download_files (or, for execution offers, the preimage to present to the seller's API as your credential). Without NWC: returns the bolt11 + payer_secret + payment_intent_id; pay it with any preimage-returning wallet, then call confirm_payment. SPENDS REAL BITCOIN \u2014 read the offer terms with get_offer first. Settlement is final; no refunds.",
+      inputSchema: {
+        offer_id: z2.string().uuid(),
+        expected_max_sats: z2.number().int().positive().optional().describe(
+          "Refuse to pay if the quoted amount exceeds this (your own per-purchase bound, applied in addition to the operator cap)"
+        )
+      }
+    },
+    async ({ offer_id, expected_max_sats }) => {
+      const pay = await hw(`/api/offers/${offer_id}/pay`, { body: {} });
+      const amount = effectiveAmountSats(pay.bolt11, pay.locked_amount_sats);
+      if (expected_max_sats !== void 0 && amount !== null && amount > expected_max_sats) {
+        throw new Error(
+          `quoted amount ${amount} sats exceeds your expected_max_sats (${expected_max_sats}) \u2014 not paid`
+        );
+      }
+      if (!nwcConfigured()) {
+        return jsonResult({
+          mode: "manual",
+          message: "No NWC wallet configured. Pay this bolt11 with any wallet that returns the preimage, then call confirm_payment with {payment_intent_id, preimage, payer_secret}.",
+          payment_intent_id: pay.payment_intent_id,
+          bolt11: pay.bolt11,
+          amount_sats: amount,
+          payer_secret: pay.payer_secret,
+          expires_at: pay.expires_at
+        });
+      }
+      await assertWithinSpendCap(amount, `buy_offer ${offer_id}`);
+      const { preimage } = await payBolt11(pay.bolt11);
+      const { settled } = await confirmAndClaim(pay.payment_intent_id, preimage, pay.payer_secret);
+      return jsonResult({
+        ok: true,
+        settled: Boolean(settled),
+        payment_intent_id: pay.payment_intent_id,
+        amount_sats: amount,
+        claim_token: settled?.claim_token ?? null,
+        claim_token_expires_at: settled?.token_expires_at ?? null,
+        preimage,
+        payer_secret: pay.payer_secret,
+        next: !settled ? "Settlement not yet observed \u2014 poll confirm_payment or retry later with the same preimage (idempotent)." : settled.claim_token ? "File offer: call download_files with {payment_intent_id, claim_token}." : "Settled. No files on this offer (execution offer) \u2014 present {payment_intent_id, preimage} to the seller's API as your credential."
+      });
+    }
+  );
+  server2.registerTool(
+    "confirm_payment",
+    {
+      title: "Confirm an offer payment with a preimage (manual mode)",
+      description: "Submit the Lightning preimage as settlement proof for an offer purchase made outside NWC (you paid the bolt11 from buy_offer manually). Idempotent \u2014 safe to retry. Returns the claim_token once settled.",
+      inputSchema: {
+        payment_intent_id: z2.string().uuid(),
+        preimage: z2.string().regex(/^[0-9a-fA-F]{64}$/, "64-char hex preimage"),
+        payer_secret: z2.string().describe("payer_secret returned by buy_offer")
+      }
+    },
+    async ({ payment_intent_id, preimage, payer_secret }) => {
+      const { settled } = await confirmAndClaim(payment_intent_id, preimage.toLowerCase(), payer_secret);
+      return jsonResult({
+        ok: true,
+        settled: Boolean(settled),
+        claim_token: settled?.claim_token ?? null,
+        claim_token_expires_at: settled?.token_expires_at ?? null
+      });
+    }
+  );
+  server2.registerTool(
+    "download_files",
+    {
+      title: "Download and decrypt purchased offer files",
+      description: "After a settled purchase (buy_offer / confirm_payment returned a claim_token): fetches each file's key, downloads the encrypted blob, verifies it against the seller's ciphertext_sha256 commitment, decrypts (AES-256-GCM) locally, and writes plaintext files to output_dir. Returns the saved paths.",
+      inputSchema: {
+        payment_intent_id: z2.string().uuid(),
+        claim_token: z2.string(),
+        output_dir: z2.string().describe("Absolute directory to save decrypted files into (created if missing)")
+      }
+    },
+    async ({ payment_intent_id, claim_token, output_dir }) => {
+      const dir = resolve(output_dir);
+      mkdirSync2(dir, { recursive: true });
+      const { files } = await hw(
+        `/api/offers/payment-intent/${payment_intent_id}/file-key`,
+        { query: { claim_token } }
+      );
+      if (!files?.length) {
+        return jsonResult({ ok: true, files: [], message: "No files attached to this offer (execution-only offer?)" });
+      }
+      const saved = [];
+      for (const f of files) {
+        const { downloadUrl } = await hw(
+          `/api/offers/payment-intent/${payment_intent_id}/download-url`,
+          { body: { offer_file_id: f.offer_file_id, claim_token } }
+        );
+        const res = await fetch(downloadUrl);
+        if (!res.ok) throw new Error(`download failed for ${f.offer_file_id}: HTTP ${res.status}`);
+        const ciphertext = Buffer.from(await res.arrayBuffer());
+        verifyCommitment(ciphertext, f.ciphertext_sha256);
+        const plaintext = decryptFile(ciphertext, f.wrapped_key, f.iv_hex);
+        const path = join2(dir, safeFilename(f.filename, `${f.offer_file_id}.bin`));
+        writeFileSync2(path, plaintext);
+        saved.push({ path, bytes: plaintext.length, commitment_verified: Boolean(f.ciphertext_sha256) });
+      }
+      return jsonResult({ ok: true, files: saved });
+    }
+  );
+}
+
+// src/tools/invoice-buy.ts
+import { mkdirSync as mkdirSync3, writeFileSync as writeFileSync3 } from "fs";
+import { join as join3, resolve as resolve2 } from "path";
+import { z as z3 } from "zod";
+async function retrieveInvoiceFiles(invoiceId, token, outputDir) {
+  const dir = resolve2(outputDir);
+  mkdirSync3(dir, { recursive: true });
+  const { files } = await hw("/api/get-invoice-files", {
+    body: { invoice_ids: [invoiceId], token }
+  });
+  const records = Object.values(files ?? {}).flat();
+  const saved = [];
+  for (const f of records) {
+    const key = await hw("/api/get-key", {
+      query: { invoice_file_id: f.id, token }
+    });
+    const { downloadUrl } = await hw("/api/generate-download-url", {
+      body: { invoice_file_id: f.id, token }
+    });
+    const res = await fetch(downloadUrl);
+    if (!res.ok) throw new Error(`download failed for ${f.id}: HTTP ${res.status}`);
+    const ciphertext = Buffer.from(await res.arrayBuffer());
+    verifyCommitment(ciphertext, key.ciphertext_sha256);
+    const plaintext = decryptFile(ciphertext, key.encryption_key, key.iv_hex);
+    const path = join3(dir, safeFilename(f.file_name, `${f.id}.bin`));
+    writeFileSync3(path, plaintext);
+    saved.push({ path, bytes: plaintext.length, commitment_verified: Boolean(key.ciphertext_sha256) });
+  }
+  return saved;
+}
+function registerInvoiceBuyTools(server2) {
+  server2.registerTool(
+    "pay_invoice",
+    {
+      title: "Pay a Hypawave invoice payload (Path 2/3a buyer)",
+      description: "Settle a one-off Hypawave invoice a seller handed you (a payload with invoice_id + access_token). With NWC configured: fetches the creator-direct bolt11, enforces the spending cap, pays, confirms with the preimage, then downloads + verifies + decrypts any attached files to output_dir. Without NWC: returns the bolt11 \u2014 pay it manually, then re-call this tool with the preimage to confirm and fetch files. SPENDS REAL BITCOIN. Settlement is final; no refunds.",
+      inputSchema: {
+        invoice_id: z3.string().describe("Invoice id from the seller's payment payload"),
+        access_token: z3.string().describe("access_token from the seller's payment payload"),
+        preimage: z3.string().regex(/^[0-9a-fA-F]{64}$/).optional().describe("Only for manual mode: the preimage from paying the bolt11 yourself"),
+        output_dir: z3.string().optional().describe("Absolute directory for decrypted files (default: skip file retrieval)"),
+        expected_max_sats: z3.number().int().positive().optional().describe("Refuse if the bolt11 exceeds this")
+      }
+    },
+    async ({ invoice_id, access_token, preimage, output_dir, expected_max_sats }) => {
+      let settledPreimage = preimage?.toLowerCase();
+      if (!settledPreimage) {
+        const cb = await hw("/api/paystream-cb", {
+          query: { token: access_token }
+        });
+        const amount = effectiveAmountSats(cb.pr);
+        if (expected_max_sats !== void 0 && amount !== null && amount > expected_max_sats) {
+          throw new Error(`bolt11 amount ${amount} sats exceeds expected_max_sats (${expected_max_sats}) \u2014 not paid`);
+        }
+        if (!nwcConfigured()) {
+          return jsonResult({
+            mode: "manual",
+            message: "No NWC wallet configured. Pay this bolt11 with a preimage-returning wallet, then call pay_invoice again with the preimage.",
+            invoice_id,
+            bolt11: cb.pr,
+            amount_sats: amount,
+            terms_hash: cb.terms_hash
+          });
+        }
+        await assertWithinSpendCap(amount, `pay_invoice ${invoice_id}`);
+        settledPreimage = (await payBolt11(cb.pr)).preimage;
+      }
+      const paymentHash = paymentHashFromPreimage(settledPreimage);
+      const confirm = await hw(`/api/invoice/${invoice_id}/confirm`, {
+        body: { payment_hash: paymentHash, preimage: settledPreimage }
+      });
+      const files = output_dir ? await retrieveInvoiceFiles(invoice_id, access_token, output_dir) : void 0;
+      return jsonResult({
+        ok: true,
+        invoice_id,
+        confirm,
+        preimage: settledPreimage,
+        files: files ?? "not retrieved \u2014 pass output_dir to download and decrypt attached files"
+      });
+    }
+  );
+}
+
+// src/tools/sell.ts
+import { readFileSync as readFileSync2 } from "fs";
+import { basename as basename2 } from "path";
+import { z as z4 } from "zod";
+async function payFee(bolt11, feeSats, context) {
+  const amount = effectiveAmountSats(bolt11, feeSats);
+  await assertWithinSpendCap(amount, context);
+  await payBolt11(bolt11);
+  return amount;
+}
+async function waitForActivation(offerId) {
+  const windowEnd = async () => {
+    const offer = await hw(`/api/offers/${offerId}`);
+    const we2 = offer.activation_window_end ?? null;
+    return we2 && new Date(we2).getTime() > Date.now() ? we2 : null;
+  };
+  let we = await pollUntil(windowEnd, { timeoutMs: 2e4 });
+  if (!we) {
+    await hw(`/api/offers/${offerId}/pay`, { body: {} }).catch(() => void 0);
+    we = await pollUntil(windowEnd, { timeoutMs: 15e3 });
+  }
+  return { activated: Boolean(we), window_end: we };
+}
+function registerSellTools(server2) {
+  server2.registerTool(
+    "create_offer",
+    {
+      title: "Create a Hypawave offer (sell files/data/API/compute for Bitcoin)",
+      description: "Create a reusable Path 3b offer sold over Lightning. Payments go creator-direct to your payment_destination (a Lightning Address or LNURL-pay URL \u2014 any receiving wallet works; you need NO node and NO preimage support to sell). The offer is inert until you pay the returned activation fee bolt11 (fee = unit_price \xD7 max_payments \xD7 fee% \u2014 Hypawave's only charge; principal never touches Hypawave). Attach files with attach_file BEFORE the fee settles \u2014 content is sealed at activation. Set pay_activation_fee=true to pay it automatically via NWC. By default the offer is PRIVATE (share the offer_id directly, agent-to-agent). To list it in the public marketplace, set is_public=true with title, category, and output_type (immutable after creation).",
+      inputSchema: {
+        amount: z4.number().positive().describe("Price per sale, in sats (pricing_type=sats) or fiat units"),
+        pricing_type: z4.enum(["sats", "fiat"]),
+        currency: z4.string().optional().describe("Fiat currency code (e.g. USD) when pricing_type=fiat"),
+        description: z4.string().min(1).max(2e3),
+        payment_destination: z4.string().describe("YOUR payout destination: Lightning Address (name@domain) or LNURL-pay URL"),
+        max_payments: z4.number().int().positive().describe("Unlock capacity N \u2014 how many times the offer can be bought (fee basis; immutable, extend via manage_offer add_capacity)"),
+        activation_window: z4.string().optional().describe('Payability window, e.g. "30d" (default), bounds 1d\u2013365d'),
+        execution_webhook: z4.string().url().optional().describe("HTTPS endpoint POSTed the settlement proof (for selling execution instead of files)"),
+        metadata: z4.record(z4.unknown()).optional(),
+        is_public: z4.boolean().optional().describe("List in the public marketplace directory (default false = private)"),
+        title: z4.string().max(60).optional().describe("Required when is_public"),
+        category: z4.enum(["data", "api", "compute", "media", "software", "access", "action", "other"]).optional().describe("Required when is_public"),
+        output_type: z4.enum(["file", "link", "json", "text", "image", "video", "audio", "stream", "webhook"]).optional().describe("Required when is_public"),
+        tags: z4.array(z4.string()).max(5).optional(),
+        input_schema: z4.union([z4.string(), z4.record(z4.unknown())]).optional(),
+        pay_activation_fee: z4.boolean().optional().describe("Pay the activation fee automatically via NWC (default false). Attach files first if the offer has any!")
+      }
+    },
+    async ({ pay_activation_fee, ...body }) => {
+      const created = await hw("/api/offers", {
+        body: Object.fromEntries(Object.entries(body).filter(([, v]) => v !== void 0)),
+        signed: true
+      });
+      let feePaid = null;
+      let activation = null;
+      if (pay_activation_fee && created.activation?.fee_bolt11) {
+        if (!nwcConfigured()) throw new Error("pay_activation_fee=true but no NWC wallet configured");
+        feePaid = await payFee(
+          created.activation.fee_bolt11,
+          created.activation.fee_amount_sats,
+          `activation fee for offer ${created.offer_id}`
+        );
+        activation = await waitForActivation(created.offer_id);
+      }
+      return jsonResult({
+        ...created,
+        seller_pubkey: getPubKey(),
+        activation_fee_paid_sats: feePaid,
+        activated: activation?.activated ?? false,
+        activation_window_end: activation?.window_end ?? null,
+        next: !pay_activation_fee ? "Offer is INERT until the activation fee_bolt11 is paid (any wallet, no preimage needed). Attach files first via attach_file, then pay the fee." : activation?.activated ? "Offer is ACTIVE and payable. Share the offer_id (private) \u2014 public offers appear in search_offers." : "Fee paid but settlement not yet observed \u2014 check later with manage_offer action=status (activation_window_end set = active)."
+      });
+    }
+  );
+  server2.registerTool(
+    "attach_file",
+    {
+      title: "Encrypt and attach a local file to an offer or invoice",
+      description: "Encrypts a local file client-side (AES-256-GCM \u2014 Hypawave never sees plaintext), uploads the ciphertext, and registers the file + key with its ciphertext_sha256 content commitment. MUST run before the activation fee settles \u2014 content is sealed at activation. The presigned upload URL lasts 120s. Pass offer_id (Path 3b) or invoice_id (Path 3a), not both.",
+      inputSchema: {
+        offer_id: z4.string().uuid().optional(),
+        invoice_id: z4.string().optional(),
+        file_path: z4.string().describe("Absolute path of the plaintext file to sell"),
+        content_type: z4.string().optional().describe("MIME type (default application/octet-stream)")
+      }
+    },
+    async ({ offer_id, invoice_id, file_path, content_type }) => {
+      if (!offer_id === !invoice_id) throw new Error("pass exactly one of offer_id or invoice_id");
+      const plaintext = readFileSync2(file_path);
+      const fileName = basename2(file_path);
+      const mime = content_type || "application/octet-stream";
+      const enc = encryptFile(plaintext);
+      const { signedUrl, objectKey } = await hw(
+        "/api/offers/upload-url",
+        { body: { fileName, contentType: mime, fileSize: enc.ciphertext.length }, signed: true }
+      );
+      const put = await fetch(signedUrl, {
+        method: "PUT",
+        headers: { "Content-Type": mime },
+        body: new Uint8Array(enc.ciphertext)
+      });
+      if (!put.ok) throw new Error(`upload failed: HTTP ${put.status} (presigned URL expires after 120s \u2014 retry attach_file)`);
+      if (offer_id) {
+        const stored2 = await hw("/api/offers/store-file", {
+          body: {
+            offer_id,
+            storage_key: objectKey,
+            filename: fileName,
+            size: enc.ciphertext.length,
+            content_type: mime,
+            iv_hex: enc.ivHex,
+            ciphertext_sha256: enc.ciphertextSha256
+          },
+          signed: true
+        });
+        await hw("/api/offers/store-file-key", {
+          body: { offer_file_id: stored2.offer_file_id, wrapped_key: enc.keyB64 },
+          signed: true
+        });
+        return jsonResult({
+          ok: true,
+          offer_id,
+          offer_file_id: stored2.offer_file_id,
+          plaintext_bytes: plaintext.length,
+          ciphertext_sha256: enc.ciphertextSha256
+        });
+      }
+      const stored = await hw("/api/offers/store-invoice-file", {
+        body: {
+          invoice_id,
+          file_name: fileName,
+          encrypted_file_url: objectKey,
+          iv_hex: enc.ivHex,
+          size: enc.ciphertext.length,
+          ciphertext_sha256: enc.ciphertextSha256
+        },
+        signed: true
+      });
+      await hw("/api/offers/invoice-file-key", {
+        body: { invoice_file_id: stored.id, key_b64: enc.keyB64 },
+        signed: true
+      });
+      return jsonResult({
+        ok: true,
+        invoice_id,
+        invoice_file_id: stored.id,
+        plaintext_bytes: plaintext.length,
+        ciphertext_sha256: enc.ciphertextSha256
+      });
+    }
+  );
+  server2.registerTool(
+    "manage_offer",
+    {
+      title: "Manage an offer: status / renew / add capacity / deactivate",
+      description: "status: read the offer (activation state, payments sold vs max_payments, window end). renew: mint a fresh activation fee bolt11 after the window lapsed (402 offer_inactive on pay). add_capacity: buy M more unlock slots (returns a capacity fee bolt11). delete: deactivate the offer permanently. Fee bolt11s are paid automatically via NWC when pay_fee=true, otherwise returned for manual payment (any wallet).",
+      inputSchema: {
+        offer_id: z4.string().uuid(),
+        action: z4.enum(["status", "renew", "add_capacity", "delete"]),
+        add_capacity: z4.number().int().positive().optional().describe("Slots to add (action=add_capacity)"),
+        activation_window: z4.string().optional().describe('New window for renew, e.g. "30d"'),
+        pay_fee: z4.boolean().optional().describe("Pay the returned fee bolt11 automatically via NWC")
+      }
+    },
+    async ({ offer_id, action, add_capacity, activation_window, pay_fee }) => {
+      if (action === "status") {
+        return jsonResult(await hw(`/api/offers/${offer_id}`));
+      }
+      if (action === "delete") {
+        return jsonResult(await hw(`/api/offers/${offer_id}`, { method: "DELETE", body: null, signed: true }));
+      }
+      let result;
+      let fee;
+      if (action === "renew") {
+        try {
+          result = await hw(`/api/offers/${offer_id}/renew`, {
+            body: activation_window ? { activation_window } : {},
+            signed: true
+          });
+          fee = result.activation;
+        } catch (e) {
+          if (isApiError(e, "activation_not_needed")) {
+            return jsonResult({ ok: true, message: "activation window still live \u2014 no renewal needed", detail: e.message });
+          }
+          throw e;
+        }
+      } else {
+        if (!add_capacity) throw new Error("add_capacity (positive integer) is required for action=add_capacity");
+        result = await hw(`/api/offers/${offer_id}/add-capacity`, {
+          body: { add_capacity },
+          signed: true
+        });
+        fee = result.topup ?? result.activation;
+      }
+      let feePaid = null;
+      let activation = null;
+      if (pay_fee && fee?.fee_bolt11) {
+        if (!nwcConfigured()) throw new Error("pay_fee=true but no NWC wallet configured");
+        feePaid = await payFee(fee.fee_bolt11, fee.fee_amount_sats, `${action} fee for offer ${offer_id}`);
+        if (action === "renew") activation = await waitForActivation(offer_id);
+      }
+      return jsonResult({
+        ...result,
+        fee_paid_sats: feePaid,
+        ...activation ? { activated: activation.activated, activation_window_end: activation.window_end } : {}
+      });
+    }
+  );
+  server2.registerTool(
+    "create_invoice",
+    {
+      title: "Create a one-off Hypawave invoice (Path 3a seller)",
+      description: "Create a single-settlement invoice: one buyer pays once, creator-direct to your payment_destination. Returns the buyer payload (invoice_id + access_token \u2014 forward BOTH to the buyer, who settles it with pay_invoice) plus an activation fee bolt11 that must be paid before the invoice goes live. Attach a file first with attach_file(invoice_id=...) if selling a file \u2014 content seals at activation.",
+      inputSchema: {
+        amount: z4.number().positive(),
+        currency: z4.string().optional().describe("Default USD"),
+        description: z4.string().optional(),
+        payment_destination: z4.string().describe("YOUR Lightning Address or LNURL-pay URL"),
+        due_date: z4.string().describe("ISO date the invoice is due, e.g. 2026-07-31"),
+        client_email: z4.string().email().describe("Buyer contact email (required by the API)"),
+        client_first_name: z4.string(),
+        client_last_name: z4.string(),
+        company_name: z4.string().optional(),
+        expires_in: z4.enum(["1h", "24h", "7d"]).optional(),
+        execution_webhook: z4.string().url().optional(),
+        pay_activation_fee: z4.boolean().optional().describe("Pay the activation fee automatically via NWC (attach files first!)")
+      }
+    },
+    async ({ pay_activation_fee, ...body }) => {
+      const created = await hw(
+        "/api/offers/create-invoice",
+        { body: Object.fromEntries(Object.entries(body).filter(([, v]) => v !== void 0)), signed: true }
+      );
+      let feePaid = null;
+      if (pay_activation_fee && created.activation?.fee_bolt11) {
+        if (!nwcConfigured()) throw new Error("pay_activation_fee=true but no NWC wallet configured");
+        feePaid = await payFee(
+          created.activation.fee_bolt11,
+          created.activation.fee_amount_sats,
+          `activation fee for invoice ${created.invoice_id}`
+        );
+      }
+      return jsonResult({
+        ...created,
+        activation_fee_paid_sats: feePaid,
+        next: pay_activation_fee ? "Fee paid \u2014 once settled the invoice is live. Forward {invoice_id, access_token} to the buyer." : "Invoice is INERT until the activation fee_bolt11 is paid (any wallet). Attach files first if needed, pay the fee, then forward {invoice_id, access_token} to the buyer."
+      });
+    }
+  );
+}
+
+// src/tools/status.ts
+import { z as z5 } from "zod";
+function registerStatusTools(server2) {
+  server2.registerTool(
+    "my_offers",
+    {
+      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")
+      }
+    },
+    async ({ status }) => jsonResult(await hw("/api/offers/list", { method: "GET", signed: true, query: { status } }))
+  );
+  server2.registerTool(
+    "list_sales",
+    {
+      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()
+      }
+    },
+    async ({ kind, offer_id, status, limit, offset }) => {
+      const path = kind === "offers" ? "/api/offers/list-payments" : "/api/offers/list-invoices";
+      return jsonResult(
+        await hw(path, {
+          method: "GET",
+          signed: true,
+          query: { status, limit, offset, ...kind === "offers" ? { offer_id } : {} }
+        })
+      );
+    }
+  );
+  server2.registerTool(
+    "get_receipt",
+    {
+      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")
+      }
+    },
+    async ({ payment_intent_id, payer_secret, invoice_id, preimage }) => {
+      if (payment_intent_id) {
+        if (!payer_secret) throw new Error("payer_secret is required with payment_intent_id");
+        return jsonResult(
+          await hw(`/api/offers/payment-intent/${payment_intent_id}/receipt`, { query: { secret: payer_secret } })
+        );
+      }
+      if (invoice_id) {
+        if (!preimage) throw new Error("preimage is required with invoice_id");
+        return jsonResult(
+          await hw(`/api/invoice/${invoice_id}/receipt`, { query: { preimage: preimage.toLowerCase() } })
+        );
+      }
+      throw new Error("pass payment_intent_id+payer_secret (offer) or invoice_id+preimage (invoice)");
+    }
+  );
+  server2.registerTool(
+    "check_payment",
+    {
+      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)")
+      }
+    },
+    async ({ payment_intent_id, payer_secret, invoice_ids }) => {
+      if (payment_intent_id) {
+        if (!payer_secret) throw new Error("payer_secret is required with payment_intent_id");
+        return jsonResult(
+          await hw(`/api/offers/payment-intent/${payment_intent_id}/status`, { query: { secret: payer_secret } })
+        );
+      }
+      if (invoice_ids?.length) {
+        return jsonResult(await hw("/api/get-unlock-status", { body: { invoice_ids } }));
+      }
+      throw new Error("pass payment_intent_id+payer_secret (offer) or invoice_ids (invoices)");
+    }
+  );
+}
+
+// src/tools/wallet.ts
+function registerWalletTools(server2) {
+  server2.registerTool(
+    "wallet_status",
+    {
+      title: "Wallet, identity, and platform settings",
+      description: "Reports the operator wallet state (NWC configured? spendable balance in sats), your seller identity pubkey, the operator spending cap, and Hypawave's live public settings (fee_percent, min_fee_sats, limits, BTC price). Call this first to know whether payments can be made automatically and what fees to expect.",
+      inputSchema: {}
+    },
+    async () => {
+      const settings = await hw("/api/public-settings").catch((e) => ({ error: String(e) }));
+      let balance_sats = null;
+      let wallet_error;
+      if (nwcConfigured()) {
+        try {
+          balance_sats = await getBalanceSats();
+        } catch (e) {
+          wallet_error = e instanceof Error ? e.message : String(e);
+        }
+      }
+      let seller_pubkey = null;
+      let identity_error;
+      try {
+        seller_pubkey = getPubKey();
+      } catch (e) {
+        identity_error = e instanceof Error ? e.message : String(e);
+      }
+      return jsonResult({
+        wallet: {
+          nwc_configured: nwcConfigured(),
+          balance_sats,
+          ...wallet_error ? { error: wallet_error } : {},
+          mode: nwcConfigured() ? "automatic payments" : "manual mode \u2014 tools return bolt11s to pay externally"
+        },
+        spending_cap: await getSpendCapSats().catch((e) => ({ error: String(e) })),
+        seller_pubkey,
+        ...identity_error ? { identity_error } : {},
+        platform_settings: settings
+      });
+    }
+  );
+}
+
+// src/index.ts
+var server = new McpServer({
+  name: "hypawave",
+  version: "0.1.0"
+});
+registerDiscoverTools(server);
+registerBuyTools(server);
+registerInvoiceBuyTools(server);
+registerSellTools(server);
+registerStatusTools(server);
+registerWalletTools(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") + ")");

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@hypawave/mcp",
+  "version": "0.1.0",
+  "description": "MCP server for Hypawave \u2014 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",
+  "bin": {
+    "hypawave-mcp": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "SECURITY.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "hypawave",
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "lightning",
+    "lightning-network",
+    "bitcoin",
+    "bitcoin-payments",
+    "nwc",
+    "nostr-wallet-connect",
+    "non-custodial",
+    "agent",
+    "agent-payments",
+    "ai-agents",
+    "micropayments",
+    "preimage",
+    "bolt11",
+    "paywall",
+    "claude",
+    "claude-code"
+  ],
+  "author": "hypawave",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hypawave/mcp.git"
+  },
+  "homepage": "https://hypawave.com/docs",
+  "dependencies": {
+    "@getalby/sdk": "^5.1.0",
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "@noble/curves": "^1.6.0",
+    "@noble/hashes": "^1.5.0",
+    "ws": "^8.18.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/ws": "^8.5.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^3.0.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}