@hypawave/sdk 0.4.0 → 0.4.2

package/AGENTS.md

@@ -89,9 +89,13 @@ The SDK exposes flat methods (`pp.createInvoice`, `pp.getBolt11`, `pp.confirmPay
 
 For Paths 3a / 3b, there is no SDK — use raw HTTP with pubkey signatures per the manual.
 
+## Selling execution (paid APIs / compute)
+
+Settlement can gate execution, not just files. Set `execution_webhook` on the offer/invoice: on settlement Hypawave delivers the payment preimage to the seller's server, and the buyer holds the same preimage — a shared secret established by the payment. Buyer presents it to the seller's API as the credential; seller verifies and runs the job on their own infrastructure. Works on Path 2 (`execution_webhook` on create-invoice), Path 3a, and Path 3b. See Recipe 6 in llms.txt and the "Sell API Calls & Compute" docs section; the live Hypawave Compute demo (hypawave.com/offers) is this exact pattern.
+
 ## Non-negotiables
 
-1. **Preimage is mandatory** for principal settlements. Pay via a wallet that returns the preimage (LND, Core Lightning, LNbits admin key, Alby/NWC, Phoenixd). Consumer wallets like Wallet of Satoshi or Phoenix mobile cannot satisfy this.
+1. **Preimage is mandatory** for principal settlements. Pay via a wallet that returns the preimage (LND, Core Lightning, LNbits admin key, Alby/NWC, Phoenixd). Consumer wallets like Wallet of Satoshi or Phoenix mobile cannot satisfy this. The wallet also needs **funded outbound liquidity ≥ amount + fees** — a fresh/empty node or "fee-credit" balance can't pay even when total balance ≥ price. For small or test payments, a **custodial wallet over NWC (e.g. Coinos)** skips channel setup entirely — only funding is needed.
 2. **Confirm before unlocking.** Always submit preimage to the confirm endpoint before requesting file keys or download URLs.
 3. **Funds flow buyer→seller directly.** Never route principal through any Hypawave endpoint. Only activation fees (small, Hypawave-issued bolt11s) go to Hypawave.
 4. **Honor `terms_hash`** on Path 3b offers. If the server returns `409 terms_changed`, re-read the offer before paying.

package/CHANGELOG.md

@@ -5,6 +5,29 @@ All notable changes to `@hypawave/sdk` are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.2]
+
+### Changed
+- Docs only — no API changes. Added the **paid-execution pattern** ("Sell Paid
+  APIs & Compute") to `README.md`, `AGENTS.md`, and the bundled
+  `skills/hypawave/SKILL.md`: setting `execution_webhook` delivers the payment
+  preimage to the seller on settlement, and the buyer holds the same preimage —
+  payment itself establishes the buyer's credential for the seller's own API,
+  compute, or service. Links the "Sell API Calls & Compute" docs section,
+  Recipe 6 in `llms.txt`, and the live Hypawave Compute demo
+  (hypawave.com/offers) as the worked example.
+
+## [0.4.1]
+
+### Changed
+- Docs only — no API changes. Clarified payer-wallet requirements in `README.md`,
+  `AGENTS.md`, and the bundled `skills/hypawave/SKILL.md`: the wallet needs
+  **funded outbound liquidity ≥ amount + fees** (a fresh/empty node or Phoenix
+  "fee-credit" balance can't pay even when total balance ≥ price), and for small
+  or test payments a **custodial wallet over NWC (e.g. Coinos)** avoids channel
+  setup entirely — only funding is needed. Mirrors the buyer-wallet guidance in
+  `llms.txt`.
+
 ## [0.4.0]
 
 ### Added

package/README.md

@@ -44,6 +44,8 @@ This SDK requires **programmable Lightning infrastructure** that exposes the pre
 
 - LND, CLN, Alby API, LNbits, NWC, or equivalent
 
+The wallet also needs **funded outbound liquidity ≥ amount + routing fees** — a fresh/empty node or a "fee-credit" balance (e.g. Phoenix below the channel-open threshold) cannot pay even when total balance ≥ price; only spendable channel liquidity counts. For small or test payments, a **custodial wallet over NWC (e.g. Coinos)** skips channel setup entirely — no liquidity minimum, only funding is needed.
+
 **Consumer wallets (Wallet of Satoshi, Phoenix, etc.) do not reliably expose the preimage and are not suitable for agent integrations.** Files and data will not unlock without a preimage.
 
 ## Install
@@ -109,6 +111,14 @@ createInvoice ──▶ getBolt11 ──▶ pay (your node) ──▶ confirmPay
 
 Three calls to Hypawave, one call to your Lightning node. Preimage from your node closes the loop.
 
+## Sell Paid APIs & Compute
+
+Settlement can gate **execution**, not just file delivery. Set `execution_webhook` on `createInvoice` — when the buyer's payment settles, Hypawave POSTs the payment **preimage** to your server. The buyer's wallet revealed the same preimage to them, so payment itself establishes a shared secret: the buyer presents it to *your* API, you verify it against the webhook delivery, and you run the job on your own infrastructure (GPU, data source, whatever you sell). No accounts or API keys needed on the buyer side.
+
+This is how the live [Hypawave Compute demo](https://hypawave.com/offers) works — 100 sats buys one live image generation, settlement is the credential. For a standing many-buyer service use an accountless Path 3b offer (raw HTTP, see below); the SDK path is best for one-off, per-customer jobs.
+
+Full pattern: [Sell API Calls & Compute docs](https://hypawave.com/docs#sell-execution) · Recipe 6 in [llms.txt](https://hypawave.com/llms.txt)
+
 ## SDK for ergonomics. Raw HTTP for accountless agents.
 
 The SDK handles types, retries, polling, error parsing, and self-describing payload generation for **Path 2** (account-based agent API). Use raw HTTP when you need:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypawave/sdk",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "TypeScript SDK for Lightning settlement, preimage proof, and execution unlocks for AI agents.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

package/skills/hypawave/SKILL.md

@@ -84,9 +84,13 @@ The SDK exposes flat methods (`pp.createInvoice`, `pp.getBolt11`, `pp.confirmPay
 
 For Paths 3a / 3b, there is no SDK — use raw HTTP with pubkey signatures per the manual.
 
+## Selling execution (paid APIs / compute)
+
+Settlement can gate execution, not just files. Set `execution_webhook` on the offer/invoice: on settlement Hypawave delivers the payment preimage to the seller's server, and the buyer holds the same preimage — a shared secret established by the payment. Buyer presents it to the seller's API as the credential; seller verifies and runs the job on their own infrastructure. Works on Path 2 (`execution_webhook` on create-invoice), Path 3a, and Path 3b. See Recipe 6 in llms.txt and the "Sell API Calls & Compute" docs section; the live Hypawave Compute demo (hypawave.com/offers) is this exact pattern.
+
 ## Non-negotiables
 
-1. **Preimage is mandatory** for principal settlements. Pay via a wallet that returns the preimage (LND, Core Lightning, LNbits admin key, Alby/NWC, Phoenixd). Consumer wallets like Wallet of Satoshi or Phoenix mobile cannot satisfy this.
+1. **Preimage is mandatory** for principal settlements. Pay via a wallet that returns the preimage (LND, Core Lightning, LNbits admin key, Alby/NWC, Phoenixd). Consumer wallets like Wallet of Satoshi or Phoenix mobile cannot satisfy this. The wallet also needs **funded outbound liquidity ≥ amount + fees** — a fresh/empty node or "fee-credit" balance can't pay even when total balance ≥ price. For small or test payments, a **custodial wallet over NWC (e.g. Coinos)** skips channel setup entirely — only funding is needed.
 2. **Confirm before unlocking.** Always submit preimage to the confirm endpoint before requesting file keys or download URLs.
 3. **Funds flow buyer→seller directly.** Never route principal through any Hypawave endpoint. Only activation fees (small, Hypawave-issued bolt11s) go to Hypawave.
 4. **Honor `terms_hash`** on Path 3b offers. If the server returns `409 terms_changed`, re-read the offer before paying.