Hypawave: Settlement as Authorization
The Contrarian Bet
Most people think money sits at the edges of software, and that AI agents become useful mainly when they get smarter, cheaper, or better coordinated.
Hypawave bets the opposite: for agents, money is not the edge case. It is the state machine.
Autonomous economic action becomes possible when settlement is reliable and irreversible enough to function as a trusted control signal. When payment is final, software can act with certainty: release the file, return the data, execute the API call, trigger the workflow.
The missing primitive in the AI economy is not more intelligence. It is settlement that machines can trust enough to act on.
Today's internet runs on permissions — accounts, API keys, and platform approvals control access. As AI agents become economic actors, that model breaks. The next internet will run on settlement, where payment is authorization and action follows automatically.
Hypawave Protocol is a verification and authorization protocol for Bitcoin settlement. It binds payment terms, cryptographic proof, and execution into a single API-driven flow. Value moves directly between wallets via Lightning. Settlement is verified by preimage proof and triggers deterministic execution — files unlock, services activate, webhooks fire.
Hypawave is the application layer that turns verified settlement into an execution gate — linking payment to action so that files unlock, services activate, and machines coordinate without intermediaries, custody, or trust.
Together, they form the settlement infrastructure for the age of intelligent machines.
1. The Thesis
Every payment system in existence treats settlement as an event that happens after the decision to grant access. You pay, then someone (or something) decides whether to deliver. That gap — between payment and action — is where trust lives. And trust requires coordination, identity, permissions, and intermediaries.
Hypawave eliminates that gap.
Settlement becomes the trigger for deterministic execution under a predefined rule set. When payment is confirmed, Hypawave enforces the rule: settlement proof exists, therefore unlock executes. No human approval, no discretionary delivery logic, no manual coordination. Settlement alone does nothing — settlement plus enforcement equals authorization.
This is not an incremental improvement to payments. It is a structural shift:
- From permission-based access to settlement-based access
- From trust-dependent delivery to cryptographically enforced delivery
- From human-coordinated exchange to machine-native exchange
Bitcoin is uniquely permissionless and machine-verifiable at the settlement layer. No bank, government, or platform can freeze, reverse, or gate access to it. Hypawave Protocol makes it verifiable at machine speed. Hypawave makes it trigger execution.
2. The Problem
Money Moves. Nothing Else Does.
The global economy still assumes humans are at the center of every transaction. Money moves through institutions, permissions, and intermediaries. Each transaction requires identity, custody, and approval.
These assumptions collapse the moment machines replace people as economic actors.
Today, when a payment completes:
- Files are sent separately
- Access is granted manually
- Execution depends on trust
- Delivery requires coordination
This gap creates friction — for people and for machines.
Existing Systems Don't Solve This
Traditional finance is too slow. Clearing delays, chargebacks, fraud risks, and regulatory silos. Machines cannot wait three days for settlement or negotiate terms of trust.
Crypto wallets move money but don't control what happens after. A wallet can send sats, but it cannot enforce delivery, gate access, or trigger execution.
Lightning Network accelerated Bitcoin with instant, low-fee payments. But it remains a payment channel — it settles value without binding it to action.
Smart contracts introduced programmability, but many payment workflows still require on-chain state, oracle assumptions, bridge risk, higher latency, or higher execution cost.
Custodial platforms abstract complexity but operate closed systems where the platform controls keys, routing, and settlement. No programmability. No machine compatibility. No non-custodial guarantees.
What's missing is what the internet already solved for information: a transport protocol that separates what is sent from how it moves — and binds payment to outcome.
3. Hypawave Protocol: The Settlement-Gated Execution Protocol
Hypawave Protocol is not a blockchain, not a wallet, not a smart-contract system. It is an authorization and verification protocol for Bitcoin settlement — a layer that lets participants agree on terms, exchange cryptographic proof, and trigger deterministic execution when payment confirms.
The protocol is API-driven. Developers and agents integrate via standard HTTP request/response — no persistent connections, no streaming, no WebSockets required. Every guarantee is delivered through the API.
How It Works
- Create Payment Request — The creator calls the Agent API (Bearer token) or Offers API (secp256k1 keypair) to create an invoice or offer. A unique session ID (
stream_id) is generated. Terms (amount, currency, description, payment destination) are locked at creation time. - Payer Fetches Bolt11 — The payer calls
GET /api/paystream-cbto fetch the creator-issued Lightning bolt11. The response includes aterms_hash— a SHA-256 snapshot of the locked terms. The bolt11'spayment_hashis recorded in an attempt row, binding it to the specific invoice. - Payment — The payer pays the bolt11 via their programmable Lightning infrastructure (LND, CLN, Alby API, LNbits, NWC, etc.). Payment is direct, wallet-to-wallet, non-custodial. The payer extracts the
preimagefrom their node's payment response. - Settlement Confirmation — The payer submits
{payment_hash, preimage, terms_hash}to the confirm endpoint. Hypawave verifies: SHA256(preimage) == payment_hash, terms haven't changed, and the payment is bound to a recorded attempt. Settlement is recorded exactly once. - Execution — On verified settlement, execution fires deterministically: encryption keys are released, file access is granted, and the optional execution webhook notifies the creator. No human approval, no discretionary logic.
Settlement Proof
Settlement proof is defined as a matching payment hash and preimage pair where SHA256(preimage) == payment_hash. Proof is submitted by the payer to Hypawave through one of these paths:
- Invoices (Agent API / Offers API one-off): Payer submits
{payment_hash, preimage}toPOST /api/invoice/{id}/confirm. No API key or secret required — authorization is four-layer cryptographic binding: invoice ID, payment hash, preimage, and a matching unconsumed payment attempt row recorded when the bolt11 was fetched. - Persistent Offers (Offers API): Payer submits
{preimage, payer_secret}toPOST /api/offers/payment-intent/{id}/confirm. - Trusted integrations: Server-to-server submission via
POST /api/wallet-webhook(requiresWALLET_WEBHOOK_SECRET).
For topups and platform fees (the only flows that use managed-receive), proof arrives via an LNbits webhook (secret URL token + server-side API verification) with a polling fallback for missed deliveries. Principal buyer → creator payments never use this path. In all cases Hypawave records the proof exactly once per payment hash. No other signal — partial payment, pending status, or external claim — constitutes settlement proof.
Requirement: The payer side requires programmable Lightning infrastructure (LND, CLN, Alby API, LNbits, NWC, etc.) that exposes the preimage after payment. Consumer wallets (Wallet of Satoshi, Phoenix, etc.) do not reliably expose the preimage.
State Machine
Every payment request follows a defined state machine:
States: created → settled → unlocked | expired
Transitions:
created → settled— Lightning settlement proof recorded. The payer submits the preimage via the confirm endpoint; Hypawave verifies and persists the proof.settled → unlocked— Settlement proof recorded; execution fires (key release, file delivery). Unlock is unconditional once settlement is confirmed — the payer always receives what they paid for, regardless of creator balance state.created → expired— TTL exceeded without settlement
No other transitions are valid. The state machine is deterministic: given the same inputs (settlement proof), the same output is guaranteed. Balance state is not part of the execution state machine — it affects only whether the creator can create new payment requests, never whether a settled payment delivers.
Execution Invariants
- No settlement proof → no unlock. Files, keys, and execution remain locked until settlement proof is recorded.
- Verified proof → exactly-once settlement → exactly-once key release. A verified preimage produces one settlement record and one delivery event. No duplicates, no partial releases.
- Idempotent finalization. Settlement is keyed by payment hash and session ID. Retries, webhook replays, and network failures cannot produce duplicate outcomes.
Core Design Principles
- Non-Custodial — Hypawave never holds, controls, or routes principal funds. Payments flow directly between wallets.
- Replay Protection — Each bolt11 is recorded as a unique payment attempt row. The preimage can only settle the specific invoice it was fetched for. Cross-invoice and cross-transaction replay is blocked by unique constraints.
- Atomic Settlement — Only a complete, cryptographically verified proof (SHA256(preimage) == payment_hash + matching attempt row) triggers execution. Partial or unverified claims are rejected.
- Authorization vs. Settlement — Hypawave Protocol separates authorization (terms agreement via terms_hash, identity verification) from settlement (Lightning payment + preimage confirmation). This mirrors the financial industry's separation of credit authorization and clearing — but without the intermediaries.
- End-to-End Encryption — Files are encrypted client-side with AES-256-GCM. Decryption keys are released only after verified settlement. Hypawave never has access to plaintext content.
Where Hypawave Protocol Sits
| Layer | Role | Trust Model | Analogy |
|---|---|---|---|
| Bitcoin (L1) | Final settlement | Global consensus, on-chain | Battery |
| Lightning (L2) | Payment channels | Channel/liquidity state | Transformer |
| Hypawave Protocol | Authorization & verification | No custody, no global state | Grid |
Hypawave Protocol does not replace Lightning — it extends it. Lightning is the settlement rail. Hypawave Protocol is the authorization and verification layer that binds settlement to action.
Hypawave Protocol Execution Model
Every Hypawave payment runs through the same execution model: create a payment session (stream_id), lock terms, fetch bolt11, pay, submit preimage, verify, and unlock. The execution gate (settlement proof → deterministic unlock) applies uniformly across all paths. The API delivers every protocol guarantee through standard HTTP request/response — no persistent connections required.
4. Hypawave: The Execution Gate
Hypawave is where Hypawave Protocol meets the world. It is the application layer that transforms verified settlement into deterministic action.
When a payment completes through Hypawave:
- Funds arrive directly in the recipient's Bitcoin wallet
- Settlement is instant and final
- Files, links, or permissions unlock automatically
- No coordination, no screenshots, no manual approval
Payment becomes the execution gate.
Two Ways In
Hypawave provides two paths to settlement-triggered execution, depending on how the developer or agent authenticates:
| Path | Who | Authentication | Fee Model | Primitive |
|---|---|---|---|---|
| Agent API | Developer-managed agents | Bearer token (sk_live_...) | Postpaid (service fee at settlement) | One-off payment requests |
| Offers API | Autonomous agents | secp256k1 keypair signature | Upfront activation fee (paid per offer or per one-off invoice) | Persistent offers · One-time custom payments |
Both paths converge on the same execution gate: verified Lightning settlement triggers deterministic action. The difference is how participants authenticate and what primitives they use. The dashboard provides account management (API keys, balance, invoice history) but invoice creation is API/SDK-only.
For Developers & Agents
Both the Agent API and Offers API share these properties:
- Deterministic state transitions — A valid, confirmed payment or nothing. No partial states, no reversals, no undefined outcomes.
- Settlement-gated execution — Services, API calls, or compute tasks run only after cryptographic proof of Bitcoin settlement.
- Agent-to-agent commerce — One agent creates a payment endpoint. Another agent pays and unlocks it. No human in the loop.
- Direct machine-to-machine flow — Payments move between wallets without intermediaries. No frozen balances, no external approval.
- Encrypted file delivery — Attach encrypted data to payments; decryption keys released only after settlement.
Protocol Guarantees (API-Only, No Streaming Required)
All protocol guarantees are delivered through standard API request/response:
| Guarantee | Mechanism |
|---|---|
| Pre-authorization | terms_hash — a SHA-256 snapshot of the invoice/offer terms is returned when the payer fetches the bolt11. The payer submits it back at confirmation time; the server recomputes and rejects with 409 terms_changed if terms were modified between fetch and settlement. |
| Identity verification | Bearer token (Agent API) or secp256k1 pubkey signature (Offers API). Every mutating request is authenticated. |
| State coordination | GET /api/get-unlock-status and SDK waitForSettlement() — agents poll for deterministic state transitions without real-time connections. |
| Atomic settlement | Each bolt11 is recorded as an invoice_payment_attempts row (Agent API / Offers API one-off) or payment_intents row (persistent offers). Settlement confirmation binds the preimage to the specific recorded row — partial or replayed payments are rejected. |
Trust Model
Hypawave is non-custodial — it never holds, controls, or has access to user funds. However, Hypawave acts as the execution oracle for settlement proof: it verifies a matching payment_hash/preimage pair (submitted by the payer for direct-pay offers, or observed via a managed-receive webhook for topups/fees), records the proof, and gates key release accordingly. This is authoritative, not trustless. The platform decides nothing — but it enforces the rule unconditionally: valid settlement proof triggers exactly one unlock.
This is an important distinction. The system eliminates human discretion from delivery, but Hypawave's server infrastructure (API endpoints, webhook listener, settlement observer) is part of the execution path. The trust assumption is narrow: Hypawave will faithfully execute the unlock rule when settlement proof is valid. It cannot steal funds, alter payments, or access encrypted content — but it can fail to deliver if the infrastructure is down.
Availability dependency: If Hypawave infrastructure is unavailable, settlement still completes — the payer's Lightning payment is finalized and funds arrive at the recipient's wallet. However, execution (file delivery, key release) may be delayed until infrastructure resumes. Hypawave is an availability dependency for execution, not for settlement.
Principal vs. Fees
Two payment rails run in parallel, never mixed:
- Principal (buyer → creator) — direct-pay. The payer's Lightning wallet pays the creator's wallet endpoint (Lightning Address or LNURL-pay) directly. Hypawave is never in the payment path and never holds principal funds.
- Fees & topups (creator → Hypawave) — managed receive via LNbits Cloud. Creators top up to cure fees owed. This is the only rail where Hypawave receives funds, and the scope is strictly fee settlement.
Hypawave holding fees it has already earned is a service transaction; holding buyer-to-creator principal would be custody. The platform is strictly the former.
The Fee Model
Hypawave charges a service fee on each settled payment (see GET /api/public-settings for current fee_percent). Creating payment requests is free — there is no cost to request payment or to use the platform. No subscriptions, no setup costs, no hidden fees.
| Model | Who | How it works |
|---|---|---|
| Postpaid | Developer-managed agents (Agent API) | Service fee recorded as negative balance at settlement. Balance can go negative. Negative balance blocks new payment request creation but never blocks delivery — the payer always receives what they paid for. See GET /api/public-settings for current fee_percent. |
| Upfront activation fee | Accountless agents (Offers API) | Creation of an offer or one-off invoice mints a Hypawave-issued activation bolt11 (fee computed from declared price — see GET /api/public-settings for current fee_percent). The offer/invoice is inert until that fee settles. No balance, no postpaid debt — Hypawave earns the fee at creation, never holds buyer principal. Persistent offers include an activation_window (default 30d, bounds [1d, 365d]); when the window elapses, the creator calls POST /api/offers/{id}/renew to mint a fresh activation bolt11 and resume service. |
Agent API Flow Example
The account-based path — for agents with a Hypawave account and API key (sk_live_...):
5. Offers: The Accountless Path
The Agent API (Section 4) requires an account and API key. Offers are the primary primitive for a second class of participant: accountless agents — autonomous systems that operate with nothing but a secp256k1 keypair. No signup, no login, no API keys.
Accountless agents have two distinct primitives available. The first is Offers — persistent, reusable payment endpoints that any agent can pay at any time, designed for standing services with repeating revenue. The second is one-time custom payments — single-use invoices scoped to a single payer, mirroring the Agent API's payment request model but without requiring an account or API key. Both primitives support optional encrypted file attachments (client-side AES-256-GCM, keys released only after settlement), use the same secp256k1 keypair authentication, and use the same upfront activation fee model — no prepaid balance, no postpaid debt; Hypawave earns its fee at creation via a Hypawave-issued activation bolt11 that the creator must pay before the primitive becomes active.
Identity & Authentication
Accountless agents authenticate every request by signing the SHA-256 hash of the request body with their private key and including three headers:
x-pubkey— the agent's compressed public key (hex)x-signature— the secp256k1 signature over the payload hash (hex)x-signed-payload-hash— the SHA-256 hash of the raw request body (hex)
On first contact, Hypawave auto-creates a pubkey-only identity for the agent — an identity row with no auth_user_id, no email, no name. The agent exists solely as a public key. Fee model follows the upfront activation fee described in Section 4 — accountless identities do not accrue postpaid balances; Hypawave earns its fee at creation time via a Hypawave-issued activation bolt11 that the creator must pay before the offer or one-off invoice becomes active.
What Are Offers?
Where the Agent API uses one-off payment requests (one invoice, one payer, one settlement), offers are persistent, reusable payment endpoints that any agent can pay at any time. An offer is a standing price — "pay X sats to trigger Y" — with a lifecycle governed by a status enum: active, fulfilled, or paused. Creators can optionally set max_payments (nullable — null means unlimited, an integer limits total payments). A payment_count field tracks how many times the offer has been paid. When payment_count ≥ max_payments, the offer auto-transitions to fulfilled via an atomic RPC — no further payments are accepted. Each payment against an offer spawns an independent payment intent.
How Offers Work
- Create an offer —
POST /api/offerswith amount, pricing type (satsorfiat), description, a requiredpayment_destination(Lightning Address or LNURL-pay URL), an optionalexecution_webhookURL, and an optionalactivation_window("Nd"string or positive integer days; default30d, bounds[1d, 365d]). The request is signed with the creator's secp256k1 keypair (auto-creates the identity on first contact). Thepayment_destinationis where payers will be routed at pay time — funds flow wallet-to-wallet to the creator; Hypawave never receives principal. The response includes a top-levelactivationsibling containing a Hypawave-issued activation bolt11 (fee_bolt11,fee_payment_hash,fee_amount_sats,expires_at,status: "pending",requested_window_ms,terms_hash). The offer is inert until the activation fee settles. - Activate the offer — The creator pays the
activation.fee_bolt11from any Lightning wallet. LNbits Cloud infrastructure receives the fee on Hypawave's behalf (this is the only rail where Hypawave receives funds; principal never flows through Hypawave). On settlement, Hypawave flips the offer to active and theactivation_windowclock starts. When the window elapses, the creator callsPOST /api/offers/{id}/renewto mint a fresh activation bolt11 and resume service. The fee bargain is locked to aterms_hashover{amount, currency, pricing_type, description, payment_destination, declared_price_sats}— editing those fields after activation surfaces409 terms_changedat pay time. - Payer discovers the offer —
GET /api/offers/{id}returns the offer details. This endpoint is public — no authentication required. - Payer pays the offer —
POST /api/offers/{id}/payenforces the activation gate (402 offer_inactiveif pending/expired,409 terms_changedif the bargain moved), fetches a fresh Lightning invoice from the creator'spayment_destinationendpoint, and returns it along with apayer_secret. The payer pays this creator-issued bolt11 directly to the creator's wallet. A payment intent is created with a snapshot of the offer's current state. Thepayer_secretis the payer's credential for submitting settlement proof and later claiming file keys. - Payer confirms settlement — When the Lightning payment settles, the payer's wallet reveals the preimage. The payer submits
{preimage, payer_secret}toPOST /api/offers/payment-intent/{id}/confirm. Hypawave verifiesSHA256(preimage) == payment_hash, atomically marks the payment intent as settled, and fires theexecution_webhookif one was configured. No fee deduction happens at settlement — the activation fee was earned upfront.
Offer Snapshots
Each payment intent stores a snapshot of the offer at creation time: offer_description, offer_webhook, offer_amount, offer_currency. This makes intents self-contained — if the creator updates or deactivates the offer after a payment intent is created, the intent still settles correctly with the terms that were active when the payer initiated payment.
Pricing Types
| Type | Behavior | When to use |
|---|---|---|
sats | Amount is denominated in satoshis. The Lightning invoice is created for exactly this amount. | Machine-to-machine payments where both parties think in sats. |
fiat | Amount is denominated in a fiat currency (USD, EUR, etc.). Converted to sats at the current BTC price when the payment intent is created. | Services priced in fiat but settled in Bitcoin. |
Two-Step Direct-Pay Settlement
When the payer submits a valid preimage to POST /api/offers/payment-intent/{id}/confirm, execution follows a strict two-step process designed for atomicity and auditability:
- Atomic settle — Hypawave first verifies
SHA256(preimage) == payment_hashand authorizes via constant-time compare ofpayer_secret. ThenUPDATE payment_intents SET status='settled' WHERE status='pending'with aRETURNINGclause. This is the race guard — only one confirm call can win the update. Duplicate confirms returnalready_settled: trueand are safely ignored. - Webhook dispatch — After atomic settlement, the system dispatches the
execution_webhookand setsexecution_fired = trueon success. No fee deduction runs at settlement — accountless offers pay their fee upfront via the activation bolt11, so there is no per-payment balance write and nosettled_unpaid_feestate for the Offers API.
Because buyer→creator principal flows wallet-to-wallet (Hypawave never touches it), the preimage submitted by the payer is the only settlement signal Hypawave accepts for offers. Payment-hash / preimage integrity is validated server-side before any state transition.
File Attachments on Offers
Offers support encrypted file attachments — creators can attach files that are released to payers only after settlement. The encryption and key management model differs from the Agent API to support the accountless, multi-payer nature of offers.
Creator Upload Flow
- Get upload URL — Creator calls
POST /api/offers/upload-url(pubkey auth) to receive a presigned upload URL. - Encrypt & upload — Creator encrypts the file locally using AES-256-GCM and uploads the ciphertext to the presigned URL.
- Link metadata — Creator calls
POST /api/offers/store-fileto associate the uploaded file metadata (filename, size, content type) with the offer. - Store wrapped key — Creator calls
POST /api/offers/store-file-keyto store the wrapped encryption key. The key is wrapped so that it can be released per-payment without exposing the raw key material.
Payer Retrieval Flow
- Pay the offer — Payer calls
POST /api/offers/{id}/payand receives a creator-issued Lightning invoice (fetched from the offer'spayment_destinationat pay time) plus apayer_secret. The payer must save this secret — it is only returned once. - Pay the Lightning invoice — Payer pays the bolt11 through LND, CLN, NWC, LNbits, Alby API, or another wallet/API that returns the preimage, directly to the creator. Hypawave is not in the payment path.
- Submit settlement proof — After the payer's wallet reveals the preimage, the payer POSTs
{preimage, payer_secret}to/api/offers/payment-intent/{id}/confirm. Hypawave verifiesSHA256(preimage) == payment_hashand marks the intent settled. - Poll for settlement — Payer calls
GET /api/offers/payment-intent/{id}/status?secret=...with thepayer_secret. After settlement, the response includes aclaim_token. - Retrieve file keys — Payer calls
GET /api/offers/payment-intent/{id}/file-key?claim_token=...with theclaim_token. Returns the wrapped decryption keys, IVs, andoffer_file_idfor all attached files. - Download encrypted files — For each file, payer calls
POST /api/offers/payment-intent/{id}/download-urlwith{offer_file_id, claim_token}in the body. Returns a time-limited presigned URL (5 min) scoped to that single file. - Decrypt locally — Payer fetches the encrypted blob from the presigned URL, unwraps the keys, and decrypts client-side. Hypawave never sees the plaintext.
Agent API vs. Offers: Key Release Models
Agent API uses a one-time atomic key release: settlement proof triggers exactly one key release event, accessed via invoice_file_id. The key is released once and the release is final.
Offers use a claim-token-based model: the payer receives a payer_secret at pay time, exchanges it for a claim_token after settlement, and uses the claim_token to retrieve wrapped file keys. Claim tokens are re-generable — each status call with a valid secret overwrites the previous token. File key retrieval via claim token supports multiple calls (multi-retrieval).
Security at rest: Both payer_secret and claim_token are stored as SHA-256 hashes — never as plaintext. The raw values exist only in the API response to the payer.
Accountless Agent-to-Agent Flow
The offers model enables fully autonomous agent-to-agent commerce with no accounts, no API keys, and no human coordination:
No accounts. No API keys. No browser. Agent A exists as a public key. Agent B doesn't even need an identity — it just pays a Lightning invoice. Settlement triggers deterministic execution via webhook. The entire flow is machine-native.
One-Time Custom Payments
The second accountless primitive. Where an offer is a persistent price any agent can hit, a one-time custom payment is a single-use invoice targeted at a specific payer — the same shape as the Agent API's /api/agent/create-invoice, but signed with a secp256k1 keypair instead of a Bearer token. Same keypair auth as offers, same upfront activation fee model (see GET /api/public-settings for current fee_percent and min_fee_sats), same file-attachment mechanics. The differences are economic, not mechanical:
| Property | Persistent Offer | One-Time Custom Payment |
|---|---|---|
| Payers | Any agent, any number of times | A single targeted payer agent, one settlement |
| Lifetime | Until deactivated or max_payments reached; needs /renew when activation_window elapses | Single-use; dies on settlement or expires_at |
| Use case | Standing services — pay-per-call APIs, published price lists, subscribable endpoints | Bespoke invoices — per-client design work, one-off deliverables, targeted quotes |
| Endpoints | POST /api/offers + /{id}/pay + /{id}/renew | POST /api/offers/create-invoice |
| Settlement signal | Payer submits preimage to POST /api/offers/payment-intent/{id}/confirm | Observed via /api/wallet-webhook using the same preimage proof model as Agent API managed-receive flows |
How It Works
- Create the invoice —
POST /api/offers/create-invoice(pubkey auth) with client/amount/destination fields. Response includesinvoice_id,access_token,payment_url, and a top-levelactivationsibling with a Hypawave-issuedfee_bolt11. The invoice is inert until the activation fee settles. - Pay the activation fee — Creator pays
activation.fee_bolt11from any Lightning wallet. Until it settles,/api/paystream-cbreturns402 activation_pendingand the payer's wallet cannot fetch a creator-issued bolt11. - (Optional) Attach encrypted files — Same mechanics as offers: client-side AES-256-GCM encryption, presigned upload to R2, register metadata via
POST /api/offers/store-invoice-file, store the wrapped key viaPOST /api/offers/invoice-file-key. Same admin-controlled limits (max_files_per_invoice,max_file_size_mb) apply. - Share the payment_url — The payer opens the URL; their wallet pays the creator-issued bolt11 directly to the creator's Lightning Address (wallet-to-wallet; Hypawave never holds principal). Settlement is observed via
/api/wallet-webhookusing preimage proof — the submitter provides{payment_hash, preimage}and Hypawave verifiesSHA256(preimage) == payment_hashagainst an unconsumedinvoice_payment_attemptsrow. - File discovery & key release — On verified settlement, the payer calls
POST /api/get-invoice-fileswith theaccess_tokenin the body to discover attached files. For each file,GET /api/get-key?invoice_file_id=...&token=access_tokenreleases the decryption key (one-time atomic release, same model as the Agent API), andPOST /api/generate-download-urlwith{invoice_file_id, token}returns a time-limited presigned download URL. The payer fetches the encrypted blob and decrypts client-side.
Offers vs. x402
The offers model is comparable to Coinbase's x402 protocol — both enable machine-payable endpoints. The structural differences reflect different design philosophies:
| Property | Hypawave Offers | x402 (Coinbase) |
|---|---|---|
| Settlement | Lightning — instant, final, non-reversible | Stablecoin — per-request authorization, custodied wallets |
| Persistence | Offers persist with lifecycle control (active/fulfilled/paused); unlimited or limited payments via max_payments | Per-request paywall; each HTTP request re-authorizes |
| Identity | secp256k1 pubkey — no account, no KYC | Wallet address — typically custodied |
| Execution | Webhook-triggered; settlement proof fires arbitrary action | HTTP 402 response; resource access gated per request |
| Custody | Non-custodial — funds move peer-to-peer via Lightning | Custodied wallets with platform intermediary |
| Finality | Genuine finality — Lightning settlement is irreversible | Stablecoin settlement — subject to chain reorganization and platform policies |
6. Security Architecture
Non-Custodial by Design
Hypawave never holds funds. Payments move peer-to-peer via Lightning. Encryption keys are generated per session and never leave the creator's device or agent runtime. Hypawave's infrastructure handles settlement verification and execution gating — never money.
Cryptographic Guarantees
- ECDH key exchange for session establishment (secp256k1 for identity/signatures; P-256 for browser-side Web Crypto API compatibility)
- AES-256-GCM encryption for file attachments
- HKDF-SHA256 for key derivation
- SHA-256 preimage verification — settlement proof is cryptographically bound to the specific payment
- Key release — Agent API: decryption keys are released exactly once after payment confirmation (one-time atomic release). Offers: decryption keys are released via claim tokens after settlement — claim tokens are re-generable and file key retrieval supports multiple calls (claim-token-based multi-retrieval)
Replay & Tamper Protection
- Unique payment_hash constraint per invoice — cross-invoice replay blocked
- Payment attempt rows bind each bolt11 to a specific invoice — cross-transaction replay blocked
- Terms hash verification — terms changed between fetch and confirm are rejected
- Secret-token + API-verified webhook confirmations with polling fallback
- Idempotent settlement recording (keyed by payment hash)
Regulatory Posture
Hypawave is designed to avoid custody at every layer. No entity in the system — not the platform, not the infrastructure, not the protocol — holds, controls, or has access to user funds at any point in the transaction lifecycle. Regulatory treatment varies by jurisdiction; the architecture is designed to minimize custodial exposure. File and metadata hashing supports audit without surveillance — participants can prove what was paid for, when, and by whom, without exposing private contents.
7. The Landscape
Existing systems in the Bitcoin and payments ecosystem — custodial wallets, Lightning node providers, paywall token protocols, ecash systems, social tipping layers, and traditional payment processors — each solve specific problems. None combine settlement, delivery, and machine-native execution into a single non-custodial flow.
As agent commerce infrastructure matures, the landscape is differentiating into distinct layers. Understanding where each protocol operates clarifies what they solve — and what they don't.
Execution vs. Authorization Layers
Hypawave operates at the execution layer — where confirmed settlement triggers deterministic state transitions. Other protocols focus on authorization, checkout, or wallet infrastructure. They serve different layers of the stack and can be complementary.
| Protocol | Layer | What it does | Settlement model |
|---|---|---|---|
| Hypawave | Execution | Settlement-triggered deterministic unlock with economic state enforcement | Final, non-reversible (Lightning) |
| Stripe Machine Payments | Platform payments | Platform-managed payment and usage rails for machine-to-machine APIs | Card / stablecoin rails through Stripe balance; custodial |
| x402 (Coinbase) | HTTP paywall | Per-request API paywall via HTTP 402; stablecoin-first | Per-request authorization; custodied wallets |
| ACP (Stripe + OpenAI) | Agent checkout | Agentic commerce checkout flow with shared payment tokens | Card rails; reversible |
| AP2 (Google) | Authorization & governance | Verifiable mandate-based agent authorization | Payment-agnostic; governance layer |
| Raw Lightning | Base payment rail | Underlying network for sending sats; no application or execution layer | Final, non-reversible; no execution semantics |
The key distinction is where each protocol operates. x402 gates resource access per HTTP request. ACP standardizes agent-driven checkout with merchants. AP2 defines authorization mandates and audit trails. Hypawave gates execution on verified settlement and enforces economic state across sessions. These are different problems at different layers.
What Makes Hypawave Structurally Different
The common pushback is: "Isn't this just pay-to-unlock plus webhooks plus encryption?"
- Deterministic state machine semantics — Settlement produces exactly one state transition. Not "payment received, now decide what to do" — but "settlement proof exists, therefore unlock executes."
- Stream-first verification — Authorization is assembled and verified before settlement, not after. The Lightning payment is the final step, not the first. This is the critical distinction from L402/LSAT: L402 authenticates after payment (pay, then get a token). Hypawave Protocol verifies authorization before settlement and enforces deterministic state transition semantics on the result. The order of operations is the differentiator.
- Non-custodial encrypted key release — File encryption keys are held client-side and released exactly once, gated by settlement proof. The platform never has access to plaintext.
- Reliability layer — Retry logic, TTL management, nonce protection, and idempotent finalization handle network failures and webhook replays gracefully.
- Agent-native primitives — API keys, machine-readable receipts, and programmatic settlement polling. Designed for AI agents from the ground up.
Deterministic Execution Under Failure
The complexity is not cryptography. Any team can implement ECDH key exchange and AES encryption. The hard part is building a reliable, idempotent settlement-gated execution engine that behaves deterministically under network failure, webhook replay, Lightning congestion, and partial delivery. Each edge case — duplicate webhooks, expired invoices, race conditions between settlement and key release, preimage replay attempts, concurrent confirm calls — requires careful handling that compounds across the system. The moat is not any single feature; it is the accumulated reliability of deterministic execution under real-world failure conditions.
8. Protocol Position in the Economic Stack
Understanding where Hypawave sits — not just relative to other protocols, but in the broader economic compute stack — clarifies what it is and why it persists. Hypawave is not an application. It is not a model orchestration layer. It is economic verification and execution infrastructure.
Current Position
The global tech economy operates in layers. Each layer builds on the one below it. Hypawave sits at Layer 3 — the settlement and execution rail — between value transport networks and the systems that consume them.
Layer 3 is the programmable settlement layer — it converts base protocols into deterministic economic state machines. Hypawave's specialization within this layer: Bitcoin-native programmable settlement rail. Payment confirmation becomes a function call. Settlement proof triggers execution — file release, API access, compute authorization, data transfer, workflow activation.
Historically, the protocols that occupy this layer become standards. TCP/IP, Visa authorization rails, Stripe payment APIs, SMTP — each became infrastructure that everything above plugs into. The systems above change constantly. The rails persist.
Future Position: The Agent Economy Stack
If AI agents become primary economic actors — buying data, running compute, selling results, paying collaborators — the stack reorganizes. Hypawave's position does not weaken. It becomes more fundamental.
In this world, agents need four primitives to operate economically: identity (keys), money (Bitcoin), verification (Hypawave Protocol), and execution (Hypawave). Without verification and execution rails, agents only have wallets. With Hypawave Protocol, they gain cryptographic proof that a counterparty will deliver. With Hypawave, they gain deterministic economic actions — pay to unlock a dataset, pay to run compute, pay to deploy an agent, pay to activate an API.
Money becomes a function call. Hypawave Protocol verifies the intent. Hypawave makes the call deterministic.
Why This Layer Survives
A common concern in the AI economy is vertical integration: model providers like OpenAI, Anthropic, or Google DeepMind may eventually control compute, models, APIs, agent frameworks, and token pricing. If they control everything, middleware gets absorbed.
This concern is valid — for AI middleware. Prompt routing, model selection, agent orchestration, search aggregation — these sit close to the model layer. The model provider can replicate them. But Hypawave Protocol and Hypawave sit in a fundamentally different layer.
Economic infrastructure vs. AI infrastructure
AI middleware operates above the model layer — routing prompts, selecting models, orchestrating agents. When the model provider adds these features natively, the middleware layer compresses.
Hypawave Protocol and Hypawave operate below the AI stack entirely — in the economic verification and settlement layer. For an AI company to replace them, it would need to:
- Run global payment infrastructure
- Handle money settlement and financial compliance
- Become a financial intermediary with regulatory overhead
- Support open, non-custodial ecosystems across providers
Most AI companies avoid this intentionally. Financial rails create regulatory complexity that is orthogonal to their core business of building models and selling compute.
History confirms this pattern. Even the largest technology platforms still rely on external payment rails:
| Layer | Example | Absorbed by platforms? |
|---|---|---|
| Applications | Many consumer apps | Frequently replaced |
| AI Middleware | Prompt routers, orchestrators | High risk of absorption |
| Settlement / Execution Rails | Stripe, Visa, Mastercard | Survived — even Apple, Google, Amazon use them |
| Protocols | TCP/IP, SMTP, DNS | Never replaced |
The closest analogy to Hypawave's position is SMTP for economic execution:
SMTP: send message → server verifies → delivery occurs
Hypawave: send payment → protocol verifies → execution fires
Both are protocol-layer infrastructure. Both sit between transport and application. Both become more essential as the volume of machine-to-machine activity scales. Neither is easily absorbed by the platforms built on top of them.
Hypawave is not an app to be outcompeted on features. It is not middleware to be absorbed by a platform. It is economic verification and execution infrastructure — its value is its position in the stack, not a feature set. As the token economy and agent commerce scale, the demand for deterministic, non-custodial verification and settlement rails does not shrink. It compounds.
9. The Future
What Settlement-Triggered Execution Enables
The stack position and primitives described above are not theoretical. They unlock concrete use cases that do not exist today:
- Paid API calls — Require Bitcoin settlement before executing requests or returning data
- Machine-to-machine data exchange — Release datasets automatically after settlement confirmation
- Compute and AI task execution — Run inference or processing only after settlement is verified
- Digital goods delivery — Unlock files, research, or premium content automatically
- Usage-based services — Charge per request, per task, or per interaction without custody or reversibility
Each of these requires a monetary medium that is instant, final, non-custodial, programmable, and cryptographically verifiable. Bitcoin satisfies all five properties today. Hypawave Protocol makes it verifiable at machine speed. Hypawave makes it trigger execution.
Hypawave — settlement infrastructure for the next internet.