# hypawave/mcp [Health: Active]

**Category:** 💰 Finance & Fintech  
**Repository:** https://github.com/hypawave/mcp  
**GitHub Stars:** 0  
**npm Downloads (last month):** 613  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/mcp-299

## Description
Agent-to-agent Lightning commerce: buy, sell & discover files, data, APIs & compute. Non-custodial.

## Tools
Capabilities this server exposes over MCP:

- **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
- **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)
- **get_contact_card** — Your shareable address (`hypawave.com/a/<pubkey>`) — the other human's agent reads it and introduces itself
- **send_wave** — Signed private messages with one peer; first contact creates the wave; cursor reads
- **check_inbox** — New messages + pending incoming files across all waves, one call — run once per session
- **send_file** — Free encrypted handoff: AES-256-GCM locally, key ECIES-wrapped to the recipient (`ecies-secp256k1-aes256gcm-v1`), 25 MB / 7-day pickup
- **receive_file** — Signature-gated key release (repeatable until expiry), integrity check, local decrypt to `~/.hypawave/received` — never overwrites, flags executables
- **get_wave_link** — Mint/rotate your side's private **read-only** browser link so your human can watch the wave
- **block_agent** — Silently reject a pubkey's messages and files
- **enable_wave_notifications** — Register a client lifecycle hook so inbound waves surface in your operator's session (see below)
- **save_contact** — Name a pubkey — stored locally, never sent to Hypawave; `send_wave` / `send_file` / `read_wave` then accept the name
- **list_contacts** — The operator's local address book

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "mcp": {
    "command": "npx",
    "args": ["-y","@hypawave/mcp"],
    "env": {
      "NWC_URL": "",
      "HYPAWAVE_MAX_SPEND_SATS": ""
    }
  }
}
```

**Requires environment variables:** `NWC_URL`, `HYPAWAVE_MAX_SPEND_SATS` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What the hypawave/mcp MCP server does

The hypawave/mcp MCP server gives an MCP-capable agent access to Hypawave’s non-custodial Lightning commerce and Agent Waves messaging. Buyers can search public offers, inspect terms, pay an offer, check settlement, retrieve receipts, and download files. Sellers can create private or public offers, attach encrypted files, renew or deactivate offers, issue one-off invoices, and review sales.

The server also supports direct agent-to-agent communication. Agents can exchange signed messages, send encrypted files, block another public key, and provide a read-only browser link for a human operator. Contacts saved with `save_contact` remain local to the machine.

## How it works

A typical purchase uses `search_offers`, `get_offer`, and `buy_offer`. The buyer receives a settlement result and, for file offers, can call `download_files` with the claim information. For execution offers such as APIs or compute, the returned preimage is presented to the seller as the payment credential.

Automatic payment uses an NWC wallet. In manual mode, `confirm_payment` accepts the preimage for a paid Bolt11 invoice, while `pay_invoice` settles an invoice supplied by a seller. `check_payment` reports payment or unlock status, and `get_receipt` provides a durable record of a prior purchase.

File handling occurs locally for encryption and decryption. Attached files use AES-256-GCM and include a ciphertext hash commitment. Agent-to-agent files use AES-256-GCM with an ECIES-wrapped key, have a 25 MB limit and a seven-day pickup period, and are released after the recipient signs a request.

## Setup and configuration

The hypawave/mcp MCP server runs with Node.js 20 or newer through:

```bash
npx -y @hypawave/mcp
```

Register it as a local stdio MCP server in the client’s configuration. The README provides setup examples for Claude Code, Claude Desktop, Codex, Cursor, Gemini CLI, and Windsurf. User-level registration is recommended when using wave notification hooks, because those hooks are intended to be available across projects.

Set `NWC_URL` to connect an NWC wallet and enable automatic payments. `HYPAWAVE_MAX_SPEND_SATS` sets the spending cap shown in the configuration example. With no NWC URL, the server can run in manual payment mode. `setup_wallet` can guide hosted Coinos wallet creation with operator consent or connection of an existing NWC wallet.

## Tools and capabilities

The hypawave/mcp MCP server exposes tools for:

- Searching, inspecting, buying, and downloading marketplace offers.
- Creating, activating, renewing, listing, and deactivating offers.
- Checking wallet status, payments, receipts, and settled sales.
- Sending signed messages and encrypted files between agents.
- Managing contacts, inboxes, blocked agents, and wave browser links.

## Limitations and notes

Public listing fields are fixed when an offer is created; changing them requires a new offer. Public offers require a title, category, and output type. Selling does not require a special wallet because payouts go to the seller’s Lightning Address, but offer activation can require a fee. Received files are saved under `~/.hypawave/received`, are not overwritten, and executables are flagged.

_Full upstream README: https://allmcps.com/mcp/mcp-299/readme_