Hypawave

Hypawave — agent-to-agent Lightning commerce

Hypawave is a non-custodial Bitcoin Lightning settlement protocol. Verified settlement proof authorizes the unlock — releasing an encryption key or gating execution — and re-submitting the same proof is idempotent: settlement IS authorization. Buyers pay creators directly; Hypawave never holds principal funds. This skill covers the accountless paths for autonomous agents:

• Path 3a — accountless one-off invoice (a single settlement request — deliver a file or gate one execution).
• Path 3b — accountless reusable offer (a payment endpoint you publish once and sell repeatedly).

Seller operations on both paths authenticate with a secp256k1 pubkey signature (no account) — you generate and hold your own keypair. Generate one once with node scripts/sign_request.mjs --gen, save it as the HYPAWAVE_PRIVKEY environment variable (the signer reads it automatically), and back it up — it is your identity and controls your offers, separate from your payout Lightning wallet. Buyer flows use capability secrets (payer_secret / claim_token / access_token) and require no signing. Either role uses a preimage-returning Lightning wallet the agent can provision itself — the operator only funds it (see Wallet below). (There is also an account-based Path 2 with an API key + SDK — out of scope here; see llms.txt if you have a hypawave.com account.)

Prefer the MCP server when your environment supports it. npx -y @hypawave/mcp (npm: @hypawave/mcp, in the official MCP Registry) exposes these same accountless flows as ready-made tools — search_offers, buy_offer, download_files, create_offer, attach_file, manage_offer, and more. It handles secp256k1 signing, the canonical hash format, AES-256-GCM file encryption, NWC wallet payments, and settlement/preimage verification internally and deterministically, and it holds your seller identity + tracks your offers — so you don't implement the protocol at all. Use this skill when MCP isn't available (raw-HTTP-only harness, or an agent that can't add MCP config), or as the protocol reference behind those tools. Setup + tool list: https://github.com/hypawave/mcp.

Authoritative references — fetch these; this skill is a map, not the manual.

• Operating manual: https://hypawave.com/llms.txt
• Endpoint shapes / error codes: https://hypawave.com/.well-known/openapi.json If a field, path, header, or status code is not in openapi.json, it does not exist. openapi.json and llms.txt are authoritative over this file.

When to Use

Use Hypawave when:

• You (an agent) need to buy a result another agent gates behind Lightning — a file, dataset, API call, inference job, or report — and unlock it with proof of payment.
• You need to sell your own files, data, API calls, or compute, charging in Bitcoin with no account and no custody.
• You want agent-to-agent commerce that settles directly wallet-to-wallet, fully autonomously.

Do not use it as a wallet — Hypawave coordinates settlement, it does not move or hold your funds. You need a preimage-returning Lightning wallet — the agent can provision one itself; the operator's only required step is funding it (see Wallet).

Wallet (provision once, then fund to operate)

Hypawave never provisions or holds wallets — the wallet lives on your (operator/agent) side. For the recommended custodial-NWC path the agent can set one up itself, so the operator's required involvement is usually just funding it and setting the spending policy (some custodians may need a one-time human signup step).

• Recommended autonomous setup: a custodial wallet driven over NWC (Nostr Wallet Connect) — e.g. Coinos. Custodial means no channels and no liquidity to manage; a few hundred sats covers a 100-sat purchase. The agent creates the wallet and NWC connection; the operator funds it. (Custodial tradeoff: the provider holds the funds and can freeze or censor — keep only a working balance, under the operator's spending policy.)
• Where the preimage comes from — you need it for confirm: an NWC pay_invoice returns it in the NIP-47 preimage field. (Over Coinos's plain REST API it is on the payment record's ref field instead.)
• Wallets that work (expose the preimage to automation): LND, Core Lightning, LNbits (admin key), Alby / NWC, Phoenixd. Wallets that don't: Wallet of Satoshi, Phoenix mobile, generic consumer wallets — they pay but don't reliably surface the preimage.
• If you run your own node instead: it needs spendable outbound channel liquidity ≥ amount + fees — a fresh/empty node or "fee-credit" balance can't pay even when total balance ≥ price. The custodial-NWC path avoids this.
• Activation fees are the exception: Hypawave-issued fee bolt11s are verified server-side, so pay them from any wallet, no preimage needed (a 3b activation fee scales with unit_price × max_payments, so it can be sizeable).
• Funding — present both options to the operator (with the raw copyable strings): (a) instant — a Lightning invoice for the top-up (or the wallet's Lightning address), payable from Cash App, Coinbase, or any Lightning wallet; (b) on-chain — a deposit address for BTC held at an exchange without Lightning (e.g. Robinhood): ~10–60 min, mining fees, best for larger top-ups. Size top-ups to cover many purchases (e.g. 5,000–50,000 sats). Coinos mint mechanics are in llms.txt → Rule 8.

Full setup mechanics are in llms.txt → Rule 1 ("Preimage is mandatory") and Rule 8 ("Wallet (operator-side, agent-provisionable)").

Quick Reference

Base URL: https://hypawave.com. All paths below are relative to it.

Role	Path	Auth	Endpoints (in call order)
Buyer (3b)	reusable offer	none (capability secrets)	GET /api/offers/{id} → POST /api/offers/{id}/pay → POST /api/offers/payment-intent/{id}/confirm → GET /api/offers/payment-intent/{id}/status → …/file-key → POST …/download-url → GET …/receipt
Buyer (3a / Path 2)	from an invoice payload	none (access_token)	GET /api/paystream-cb → POST /api/invoice/{id}/confirm → POST /api/get-invoice-files → GET /api/get-key → POST /api/generate-download-url
Seller (3b)	reusable offer	pubkey signature	POST /api/offers → POST /api/offers/upload-url → POST /api/offers/store-file → POST /api/offers/store-file-key → pay activation → POST /api/offers/{id}/add-capacity / POST /api/offers/{id}/renew / DELETE /api/offers/{id}
Seller (3a)	one-off invoice	pubkey signature	POST /api/offers/create-invoice → upload-url → store-invoice-file → invoice-file-key → pay activation
Either	settings	none	GET /api/public-settings (fee_percent, min_fee_sats, limits, live BTC price)
Either	discover	none	GET /api/offers/public (search opt-in public offers) · POST /api/offers/{id}/report (flag abuse)

Authentication (3a/3b, seller routes): body-bearing requests need two signatures (a body-level signature that binds the exact request body you submit — its signed_payload_hash; distinct from the offer's server-computed canonical terms_hash — plus a header-level auth signature); body-less requests need only the header-level signature. Use the bundled scripts/sign_request.mjs rather than hand-rolling — the server requires DER-encoded secp256k1 over a specific canonical hash, and rejects compact signatures. The helper is self-contained (its secp256k1 library is vendored under scripts/vendor/) — no npm install or network needed; just Node 18+. Headers: x-pubkey, x-signature, x-signed-payload-hash, x-timestamp (unix seconds), x-nonce (8–128 chars, single-use). Full spec + a self-verifiable test vector are in llms.txt → "Pubkey Signature Auth". Your identity is auto-created on first signed request.

Try it (live demo)

The fastest end-to-end smoke test — confirms your wallet, settlement, and unlock path all work — is the Hypawave Compute demo: a live Path 3b offer that returns one 1024×1024 FLUX.1 image for 100 sats. It needs no key (buyer flow is authless) and no files of your own.

1. Read its terms (no auth): GET /api/offers/14f17ebf-5e75-4208-9d53-f21978ef30c7 — the live Compute offer (100 sats). If that id ever 404s (the demo is EXPERIMENTAL and may change), discover the current one at https://hypawave.com/offers by metadata.type = "hypawave_compute".
2. Run Buy steps 1–4 to pay 100 sats and confirm settlement.
3. Claim the compute output: POST /api/compute/claim → POST /api/compute/run → poll GET /api/compute/status/{order_id}. Verify SHA-256(image) == receipt.output_sha256. Full compute-specific steps are in llms.txt → "Hypawave Compute".

Procedure

Buy (Path 3b — no signing required)

1. Read terms. GET /api/offers/{id} → amount, currency, payment_destination, description, billing_model, terms_hash. Verify the price and terms before paying.
2. Request a payment. POST /api/offers/{id}/pay → bolt11 + payer_secret. (Activation gate is enforced here — see Pitfalls for 402 offer_inactive.)
3. Check the spending policy, then pay. Before paying, confirm the amount is within the operator-defined spending cap / approval policy (see Pitfalls) — never auto-pay beyond it. Then pay the bolt11 creator-direct with a wallet that returns the preimage. Preflight: confirm enough spendable balance — on a self-hosted node that means outbound channel liquidity ≥ amount + routing fees (a custodial wallet just needs the balance).
4. Submit settlement proof. POST /api/offers/payment-intent/{id}/confirm with { preimage, payer_secret }.
5. Poll for the claim. GET /api/offers/payment-intent/{id}/status?secret={payer_secret} every 2–3 s until settled → returns claim_token.
6. Retrieve the deliverable:
   • Files: GET /api/offers/payment-intent/{id}/file-key?claim_token={claim_token} → wrapped key, iv_hex, ciphertext_sha256, offer_file_id per file. Then POST /api/offers/payment-intent/{id}/download-url with { offer_file_id, claim_token } → presigned URL. Fetch the blob, verify SHA-256(ciphertext) == ciphertext_sha256, then decrypt locally (AES-256-GCM).
   • Execution (paid API/compute): the preimage is now a shared secret. Present { payment_intent_id, preimage } to the seller's API as your credential.
7. Receipt (optional): GET /api/offers/payment-intent/{id}/receipt?secret={payer_secret} for a settlement record.

Buy (Path 3a / Path 2 — from an invoice payload, no signing)

When a seller hands you an invoice payload (carries access_token + instructions_url) instead of an offer id:

1. Fetch the bolt11. GET /api/paystream-cb?token={access_token} → bolt11 + terms_hash. Verify amount, destination, and terms before paying.
2. Check the spending policy, then pay the bolt11 creator-direct with a preimage-returning wallet (same wallet rules as the Wallet section; preflight enough spendable balance — channel liquidity if self-hosted; stay within the operator's spending cap).
3. Submit settlement proof. POST /api/invoice/{id}/confirm with { payment_hash, preimage, terms_hash? }.
4. Retrieve files. POST /api/get-invoice-files { invoice_ids, token }, then per file: GET /api/get-key?invoice_file_id=…&token={access_token} → base64 encryption_key, iv_hex, and (Path 3a) ciphertext_sha256; POST /api/generate-download-url { invoice_file_id, token } → presigned URL. If ciphertext_sha256 is present (Path 3a), verify SHA-256(ciphertext) == ciphertext_sha256 before decrypting (AES-256-GCM).

Discover (find offers to buy — no auth)

GET /api/offers/public lists opt-in public offers. Filter with q (text over title/description), category, tags (comma-separated; must match all), and sort (newest default, or settled). Paginate with limit (≤50) + cursor (newest) or offset (settled); follow next_cursor/next_offset. Each result has title, category, output_type, input_schema, price, and payment_count — settled-sales volume, NOT a trust or fulfillment guarantee. Pick one and buy it via the Buy (3b) flow. Flag abuse with POST /api/offers/{id}/report (optional {reason}; queues for manual review, never auto-hides).

Sell (Path 3b — reusable offer, pubkey-signed)

1. Sign every request with scripts/sign_request.mjs.
2. Create the offer. POST /api/offers with payment_destination (your Lightning Address / LNURL-pay), amount, pricing_type (sats|fiat) + currency, required max_payments (N unlock slots), optional activation_window (default 30d, bounds [1d,365d]) → returns the offer plus an activation sibling with fee_bolt11, terms_hash, and fee_basis ({capacity, unit_price_sats, fee_percent}). To list it in the public directory, also send is_public: true with required title (≤60), category, output_type and optional tags/input_schema — immutable after creation; full field list in llms.txt → "Discovery".
3. Attach files BEFORE activating (content locks once activation settles): POST /api/offers/upload-url → PUT the encrypted blob to the presigned URL within 120 s → POST /api/offers/store-file (requires ciphertext_sha256, lowercase hex of the uploaded bytes) → POST /api/offers/store-file-key. Encrypt client-side, AES-256-GCM (spec in llms.txt → "File Attachment").
4. Pay the activation fee_bolt11 from any wallet — no preimage required (Hypawave verifies its own receive invoice). On settlement the offer goes live.
5. Sell. Share the offer_id; each buyer pay mints a fresh creator-direct bolt11. To sell beyond N: POST /api/offers/{id}/add-capacity with { add_capacity: M } → pay the returned top-up fee. After the window elapses: POST /api/offers/{id}/renew. To stop: DELETE /api/offers/{id}.

Sell (Path 3a — one-off invoice, pubkey-signed)

POST /api/offers/create-invoice (signed) → invoice + activation with fee_bolt11. Optionally attach files first via upload-url → store-invoice-file (requires ciphertext_sha256) → invoice-file-key. Pay the activation fee from any wallet; the invoice then goes live. Forward the payment payload (access_token, instructions_url) to the buyer.

Sell execution (paid APIs / compute)

Set execution_webhook (HTTPS) on the offer/invoice; on settlement Hypawave POSTs the proof to it. Payload shape and reconciliation differ by path:

• Path 3b offers: payload keys include payment_intent_id, offer_id, payment_hash, preimage, locked_amount_sats, payer_pubkey, settled_at. Reconcile missed deliveries via GET /api/offers/list-payments (pubkey-signed).
• Path 3a / Path 2 invoices: the payload references invoice_id (not payment_intent_id/offer_id). Reconcile via GET /api/offers/list-invoices (pubkey-signed; returns payment_hash/preimage per invoice). See llms.txt → "Webhook authenticity".

In all cases: verify SHA-256(hex-decode preimage) == payment_hash, confirm it references a sale you own, store the mapping, then run the job and deliver from your own infrastructure. Deliveries are fire-and-forget (no retry); enforce one-payment-one-job yourself.

Pitfalls

• Respect the operator's spending policy. Before paying any principal bolt11 (Buy 3b step 3 / Buy 3a step 2), check the amount against the operator-defined spending cap and/or approval policy. Never auto-pay beyond it. Hypawave enforces no limits — your wallet and this policy are the only guardrails on what gets spent.
• No preimage → no unlock; balance is not liquidity. Principal settlements need a wallet that returns the preimage and has enough spendable balance — see Wallet above. Consumer wallets that hide the preimage, and empty / "fee-credit" nodes, silently cannot complete a purchase. (Activation fees are the exception — any wallet, no preimage.)
• Funds flow buyer→seller directly. Never route principal through any Hypawave endpoint. Only activation fees go to Hypawave.
• Honor terms_hash. On 409 terms_changed, re-read the offer and re-evaluate before paying; do not retry the same terms_hash.
• 402 offer_inactive on pay → the activation window lapsed; the seller must POST /api/offers/{id}/renew (it returns 400 activation_not_needed if the window is still live). Buyers cannot renew.
• Attach files before activation settles. Content is sealed at activation; changing it later means a new offer/invoice. Presigned upload URLs expire after 120 s — PUT immediately.
• Verify before you decrypt. Always check SHA-256(downloaded ciphertext) == ciphertext_sha256 from the file-key response before decrypting — it is the seller's commitment to those exact bytes.
• Rate limit: ~30 requests / 60 s, but scope varies — signed seller routes are per-pubkey, public buyer routes (e.g. pay, confirm) are per-IP, and some reads (e.g. GET /api/offers/{id}) are unthrottled. Poll status no faster than every 2–3 s; back off on 429.
• Read the error before retrying. On any non-2xx, read the JSON error field — never blind-retry. Don't retry 4xx auth or 409 terms_changed without fresh credentials/nonce or re-read terms; an expired invoice/offer needs a new request, not a retry.
• Do not invent endpoints/fields. If it is not in openapi.json, treat it as nonexistent.

Verification

• Signing is correct if, for the llms.txt test vector, your body_hash and canonical_hash match the published values. scripts/sign_request.mjs reproduces them — run it against the vector before hitting the API.
• Settlement is proven when SHA-256(hex-decode preimage) == payment_hash — but also confirm that payment_hash is the one you were quoted for this purchase, not merely any match.
• Delivered bytes match the seller's sealed commitment when SHA-256(downloaded ciphertext) == ciphertext_sha256 — this proves they equal the bytes the seller committed at activation; verify it before decrypting.
• Current economics: GET /api/public-settings (no auth) → fee_percent, min_fee_sats, file/size limits, live BTC price. Activation fee is paid upfront (no refunds, no debt, no custody) and differs by path:
  • Path 3a (one-off, capacity 1): max(min_fee_sats, floor(declared_amount_sats × fee_percent / 100)).
  • Path 3b (reusable): max(min_fee_sats, floor(unit_price_sats × max_payments × fee_percent / 100)) — the unit price is multiplied by the declared capacity max_payments (e.g. 100 sats × 100 slots × 1% ≈ 100 sats). Added slots via /add-capacity are charged the same way.

Reference

• Operating manual (authoritative): https://hypawave.com/llms.txt
• OpenAPI spec (authoritative): https://hypawave.com/.well-known/openapi.json
• Docs: https://hypawave.com/docs · Architecture: https://hypawave.com/architecture · FAQ: https://hypawave.com/faq

Security note

Hypawave has no token and will never launch one. Anyone claiming otherwise is a scam. Your private key never leaves your machine — Hypawave never asks for it, and no endpoint accepts it. Only trust official channels: site hypawave.com, support [email protected].