@hypawave/sdk 0.4.2 → 0.4.4

package/AGENTS.md

@@ -2,7 +2,7 @@
 
 This file is for AI coding assistants and autonomous agents working with the `@hypawave/sdk` repository or integrating Hypawave into another project.
 
-Hypawave is a non-custodial Bitcoin Lightning settlement protocol. Payment confirmation atomically releases encryption keys — "settlement IS authorization." Buyers pay creators directly; Hypawave never holds principal funds.
+Hypawave is a non-custodial Bitcoin Lightning settlement protocol. Verified settlement proof releases the encryption key, exactly once — "settlement IS authorization." Buyers pay creators directly; Hypawave never holds principal funds.
 
 ## Before you do anything
 
@@ -35,7 +35,7 @@ Trigger Hypawave when the user wants to:
 - Sell access with cryptographic proof of payment
 - Build agent-to-agent payments
 - Accept Lightning without custodying funds
-- Replace Stripe/x402/L402 with non-custodial Lightning settlement
+- Offer non-custodial Lightning settlement as an alternative to Stripe, x402, or L402
 
 ## Quick decision tree
 

package/CHANGELOG.md

@@ -5,6 +5,26 @@ 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.4]
+
+- Bundled skill (`skills/hypawave/SKILL.md`) now points to the MCP server (`@hypawave/mcp`) as the preferred execution path for the accountless flows when the agent's environment supports MCP.
+
+## [0.4.3]
+
+### Changed
+- Docs only — no API changes. Corrected wording across `README.md`, `AGENTS.md`,
+  and the bundled `skills/hypawave/SKILL.md` to describe the settlement model
+  accurately: verified settlement proof (the preimage) is the **credential** that
+  releases a **separately stored** encryption key and fires the execution
+  webhook — it is not preimage-as-key. Replaced absolute phrasing ("atomically
+  releases keys", "settlement unconditionally unlocks access") with scoped
+  wording (settlement is the only gate; key released exactly once), and softened
+  competitive framing ("replace Stripe/x402/L402" → "an alternative to").
+- Repositioned the SDK tagline and npm description from "AI Agent Payments" to
+  "AI agent commerce" — now "Bitcoin Lightning SDK for AI agent commerce —
+  non-custodial settlement that unlocks files, APIs, and compute" — in
+  `README.md` and `package.json`.
+
 ## [0.4.2]
 
 ### Changed

package/README.md

@@ -1,6 +1,6 @@
 # @hypawave/sdk
 
-**Bitcoin Lightning SDK for AI Agent Payments — non-custodial settlement with preimage-proof unlocks**
+**Bitcoin Lightning SDK for AI agent commerce — non-custodial settlement that unlocks files, APIs, and compute.**
 
 [![npm version](https://img.shields.io/npm/v/@hypawave/sdk.svg)](https://www.npmjs.com/package/@hypawave/sdk)
 [![CI](https://github.com/hypawave/sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/hypawave/sdk/actions/workflows/ci.yml)
@@ -15,7 +15,7 @@ Hypawave is programmable settlement infrastructure for AI agents: a non-custodia
 
 This TypeScript SDK lets developers create creator-direct Lightning invoices, deliver payment payloads to payer agents, verify preimage proof, and trigger deterministic unlocks.
 
-**Payment is the authorization — confirmed settlement unconditionally unlocks access.**
+**Payment is the authorization — verified settlement is the only gate on access.**
 
 ## Why Hypawave
 
@@ -472,7 +472,7 @@ Most tools handle checkout, paid requests, or wallet rails. **Hypawave executes
 | Accountless agent access | ✅ | ⚠️ platform-dependent | ⚠️ wallet/facilitator | ⚠️ app ecosystem | ⚠️ mandate framework | ⚠️ keys, no app layer |
 | Mainstream billing, cards, reporting | ❌ | ✅ | ❌ | ⚠️ merchant checkout | ⚠️ partner ecosystem | ❌ |
 
-Hypawave is the execution layer: the same preimage that proves payment atomically releases encrypted file keys and fires the execution webhook. For basic file/key unlock flows, the delivery layer is built in.
+Hypawave is the execution layer: the verified payment preimage is the credential that releases the stored encryption key and fires the execution webhook. For basic file/key unlock flows, the delivery layer is built in.
 
 ## Links
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@hypawave/sdk",
-  "version": "0.4.2",
-  "description": "TypeScript SDK for Lightning settlement, preimage proof, and execution unlocks for AI agents.",
+  "version": "0.4.4",
+  "description": "Bitcoin Lightning SDK for AI agent commerce — non-custodial settlement that unlocks files, APIs, and compute.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",

package/skills/hypawave/SKILL.md

@@ -5,7 +5,7 @@ description: Use Hypawave to charge in Bitcoin Lightning for files, APIs, comput
 
 # Hypawave — Lightning settlement for AI agents
 
-Hypawave is a non-custodial Bitcoin Lightning settlement protocol. Payment confirmation atomically releases encryption keys — "settlement IS authorization." Buyers pay creators directly; Hypawave never holds principal funds.
+Hypawave is a non-custodial Bitcoin Lightning settlement protocol. Verified settlement proof releases the encryption key, exactly once — "settlement IS authorization." Buyers pay creators directly; Hypawave never holds principal funds.
 
 ## Before you do anything
 
@@ -30,6 +30,10 @@ That document is authoritative. It contains:
 https://hypawave.com/.well-known/openapi.json
 ```
 
+## Prefer the MCP server when available
+
+If your environment supports MCP, the accountless flows (Path 3a/3b) are available as ready-made tools via `npx -y @hypawave/mcp` (npm: `@hypawave/mcp`, in the official MCP Registry) — `search_offers`, `buy_offer`, `download_files`, `create_offer`, `attach_file`, `manage_offer`, and more. It handles secp256k1 signing, canonical hashing, AES-256-GCM encryption, NWC wallet payments, and settlement/preimage verification internally, and holds your seller identity — so you don't implement the protocol at all. Use this skill when MCP isn't available or as the protocol reference. Setup: https://github.com/hypawave/mcp
+
 ## Quick decision tree
 
 Pick the path that matches the user's situation:
@@ -88,6 +92,10 @@ For Paths 3a / 3b, there is no SDK — use raw HTTP with pubkey signatures per t
 
 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.
 
+## Discovery (public offer directory)
+
+Offers can opt into a public directory. **Find offers to buy:** `GET /api/offers/public` (no auth) — filter by `q` (title/description text), `category`, `tags`, and `sort` (`newest` or `settled`); paginate via `limit`+`cursor`/`offset`. Each result carries `title`, `category`, `output_type`, `input_schema`, price, and `payment_count` — settled-sales **volume, not a trust or fulfillment guarantee**. **List your own offer:** add `is_public: true` to `POST /api/offers` with required `title`/`category`/`output_type` (and optional `tags`/`input_schema`) — immutable after creation. **Flag abuse:** `POST /api/offers/{id}/report` (queues for manual review, never auto-hides). Full field list in llms.txt → "Discovery".
+
 ## 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. 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.