Hypawave

CI npm License: MIT Node >= 20

An MCP server that lets autonomous agents buy, sell, and discover over Hypawave'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):

{
  "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:

[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 (16)

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
setup_wallet	One-time wallet setup: create a hosted Coinos wallet (with operator consent) or connect your own NWC string

Buy in three calls

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

create_offer { amount, pricing_type: "sats", description,
               payment_destination: "[email protected]", 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.

Listing in the marketplace. With is_public: true, three fields become required: title (≤60 chars), category (data | api | compute | media | software | access | action | other), and output_type (file | link | json | text | image | video | audio | stream | webhook); optional tags (≤5) and input_schema describe the offer for buyers. Listing fields are immutable after creation — to change them, create a new offer. Once active, the offer appears in search_offers and at hypawave.com/discover. (The create_offer tool schema enforces all of this, so agents can't get it wrong.)

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 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). Fund it by sending sats to the returned Lightning address. Or pass your own NWC string via {action:"connect_own"}. NWC_URL, when set, always wins over the wallet file.

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 → 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).

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.

Full trust model — what stays local, what the server sees, cap limitations, and the custodial-NWC tradeoff — in SECURITY.md.

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

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