Ψ

Hypawave: Settlement as Authorization

Oliver Hayen


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

  1. 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.
  2. Payer Fetches Bolt11 — The payer calls GET /api/paystream-cb to fetch the creator-issued Lightning bolt11. The response includes a terms_hash — a SHA-256 snapshot of the locked terms. The bolt11's payment_hash is recorded in an attempt row, binding it to the specific invoice.
  3. 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 preimage from their node's payment response.
  4. 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.
  5. 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} to POST /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} to POST /api/offers/payment-intent/{id}/confirm.
  • Trusted integrations: Server-to-server submission via POST /api/wallet-webhook (requires WALLET_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: createdsettledunlocked | 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

LayerRoleTrust ModelAnalogy
Bitcoin (L1)Final settlementGlobal consensus, on-chainBattery
Lightning (L2)Payment channelsChannel/liquidity stateTransformer
Hypawave ProtocolAuthorization & verificationNo custody, no global stateGrid

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:

PathWhoAuthenticationFee ModelPrimitive
Agent APIDeveloper-managed agentsBearer token (sk_live_...)Postpaid (service fee at settlement)One-off payment requests
Offers APIAutonomous agentssecp256k1 keypair signatureUpfront 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:

GuaranteeMechanism
Pre-authorizationterms_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 verificationBearer token (Agent API) or secp256k1 pubkey signature (Offers API). Every mutating request is authenticated.
State coordinationGET /api/get-unlock-status and SDK waitForSettlement() — agents poll for deterministic state transitions without real-time connections.
Atomic settlementEach 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.

ModelWhoHow it works
PostpaidDeveloper-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 feeAccountless 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_...):

1. Agent A POST /api/agent/create-invoice (amount, currency, expiry, encrypted payload hash) ← Returns: payment_request_id, Lightning invoice (bolt11), access_token 2. Agent B Pays bolt11 through LND, CLN, NWC, LNbits, Alby API, or another wallet/API that returns the preimage ← Lightning settlement confirmed via webhook 3. Hypawave (execution oracle) Records settlement proof, releases encrypted key ← Execution unlocked: file keys available, receipt issued 4. Agent B POST /api/get-invoice-files (with access_token in body) ← Returns: file metadata (IDs, names) for the invoice 5. Agent B GET /api/get-key?invoice_file_id=...&token=access_token ← Returns: decryption key and IV for each file 6. Agent B POST /api/generate-download-url (with access_token in body) ← Returns: time-limited presigned URL (5 min) for each encrypted file 7. Agent B Fetches encrypted blob, decrypts locally, executes next action (No human in the loop. Settlement was the authorization.)

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

  1. Create an offerPOST /api/offers with amount, pricing type (sats or fiat), description, a required payment_destination (Lightning Address or LNURL-pay URL), an optional execution_webhook URL, and an optional activation_window ("Nd" string or positive integer days; default 30d, bounds [1d, 365d]). The request is signed with the creator's secp256k1 keypair (auto-creates the identity on first contact). The payment_destination is 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-level activation sibling 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.
  2. Activate the offer — The creator pays the activation.fee_bolt11 from 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 the activation_window clock starts. When the window elapses, the creator calls POST /api/offers/{id}/renew to mint a fresh activation bolt11 and resume service. The fee bargain is locked to a terms_hash over {amount, currency, pricing_type, description, payment_destination, declared_price_sats} — editing those fields after activation surfaces 409 terms_changed at pay time.
  3. Payer discovers the offerGET /api/offers/{id} returns the offer details. This endpoint is public — no authentication required.
  4. Payer pays the offerPOST /api/offers/{id}/pay enforces the activation gate (402 offer_inactive if pending/expired, 409 terms_changed if the bargain moved), fetches a fresh Lightning invoice from the creator's payment_destination endpoint, and returns it along with a payer_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. The payer_secret is the payer's credential for submitting settlement proof and later claiming file keys.
  5. Payer confirms settlement — When the Lightning payment settles, the payer's wallet reveals the preimage. The payer submits {preimage, payer_secret} to POST /api/offers/payment-intent/{id}/confirm. Hypawave verifies SHA256(preimage) == payment_hash, atomically marks the payment intent as settled, and fires the execution_webhook if 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

TypeBehaviorWhen to use
satsAmount is denominated in satoshis. The Lightning invoice is created for exactly this amount.Machine-to-machine payments where both parties think in sats.
fiatAmount 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:

  1. Atomic settle — Hypawave first verifies SHA256(preimage) == payment_hash and authorizes via constant-time compare of payer_secret. Then UPDATE payment_intents SET status='settled' WHERE status='pending' with a RETURNING clause. This is the race guard — only one confirm call can win the update. Duplicate confirms return already_settled: true and are safely ignored.
  2. Webhook dispatch — After atomic settlement, the system dispatches the execution_webhook and sets execution_fired = true on 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 no settled_unpaid_fee state 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

  1. Get upload URL — Creator calls POST /api/offers/upload-url (pubkey auth) to receive a presigned upload URL.
  2. Encrypt & upload — Creator encrypts the file locally using AES-256-GCM and uploads the ciphertext to the presigned URL.
  3. Link metadata — Creator calls POST /api/offers/store-file to associate the uploaded file metadata (filename, size, content type) with the offer.
  4. Store wrapped key — Creator calls POST /api/offers/store-file-key to 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

  1. Pay the offer — Payer calls POST /api/offers/{id}/pay and receives a creator-issued Lightning invoice (fetched from the offer's payment_destination at pay time) plus a payer_secret. The payer must save this secret — it is only returned once.
  2. 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.
  3. 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 verifies SHA256(preimage) == payment_hash and marks the intent settled.
  4. Poll for settlement — Payer calls GET /api/offers/payment-intent/{id}/status?secret=... with the payer_secret. After settlement, the response includes a claim_token.
  5. Retrieve file keys — Payer calls GET /api/offers/payment-intent/{id}/file-key?claim_token=... with the claim_token. Returns the wrapped decryption keys, IVs, and offer_file_id for all attached files.
  6. Download encrypted files — For each file, payer calls POST /api/offers/payment-intent/{id}/download-url with {offer_file_id, claim_token} in the body. Returns a time-limited presigned URL (5 min) scoped to that single file.
  7. 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:

1. Agent A Generates secp256k1 keypair (private key + compressed public key) (The public key IS the identity. No registration needed.) 2. Agent A POST /api/offers (signed with keypair) {amount: 100, pricing_type: "sats", description: "Weather API query", payment_destination: "agent-a@wallet.com", execution_webhook: "https://agent-a.example.com/on-payment", activation_window: "30d"} ← Returns: offer_id, activation: {fee_bolt11, fee_amount_sats, ...} Agent A Pays activation.fee_bolt11 from its Lightning wallet ← Identity auto-created (if new), offer flips to active once the fee settles (when the window elapses, Agent A calls POST /api/offers/{id}/renew) 3. Agent B GET /api/offers/{offer_id} ← Returns: offer details (amount, currency, description) 4. Agent B POST /api/offers/{offer_id}/pay (Hypawave enforces activation gate, fetches a fresh bolt11 from Agent A's payment_destination) ← Returns: bolt11, payment_hash, payment_intent_id, payer_secret Agent B Pays bolt11 directly to Agent A from its Lightning wallet ← Wallet reveals preimage on settlement 5. Agent B POST /api/offers/payment-intent/{id}/confirm {preimage, payer_secret} ← Hypawave verifies SHA256(preimage) == payment_hash, marks intent settled 6. Hypawave (execution oracle) → Fires POST to Agent A's execution_webhook (no fee deduction — activation fee was earned upfront at offer creation) ← Agent A's server receives settlement proof, executes (returns data, runs compute, etc.) --- File delivery variant (if offer has attached files) --- 7. Agent B GET /api/offers/payment-intent/{id}/status?secret={payer_secret} ← Returns: status="settled", claim_token 8. Agent B GET /api/offers/payment-intent/{id}/file-key?claim_token={claim_token} ← Returns: wrapped decryption keys for all attached files 9. Agent B Downloads encrypted files, unwraps keys, decrypts locally (No human in the loop. Settlement was the authorization. Files released per-payment.)

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:

PropertyPersistent OfferOne-Time Custom Payment
PayersAny agent, any number of timesA single targeted payer agent, one settlement
LifetimeUntil deactivated or max_payments reached; needs /renew when activation_window elapsesSingle-use; dies on settlement or expires_at
Use caseStanding services — pay-per-call APIs, published price lists, subscribable endpointsBespoke invoices — per-client design work, one-off deliverables, targeted quotes
EndpointsPOST /api/offers + /{id}/pay + /{id}/renewPOST /api/offers/create-invoice
Settlement signalPayer submits preimage to POST /api/offers/payment-intent/{id}/confirmObserved via /api/wallet-webhook using the same preimage proof model as Agent API managed-receive flows

How It Works

  1. Create the invoicePOST /api/offers/create-invoice (pubkey auth) with client/amount/destination fields. Response includes invoice_id, access_token, payment_url, and a top-level activation sibling with a Hypawave-issued fee_bolt11. The invoice is inert until the activation fee settles.
  2. Pay the activation fee — Creator pays activation.fee_bolt11 from any Lightning wallet. Until it settles, /api/paystream-cb returns 402 activation_pending and the payer's wallet cannot fetch a creator-issued bolt11.
  3. (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 via POST /api/offers/invoice-file-key. Same admin-controlled limits (max_files_per_invoice, max_file_size_mb) apply.
  4. 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-webhook using preimage proof — the submitter provides {payment_hash, preimage} and Hypawave verifies SHA256(preimage) == payment_hash against an unconsumed invoice_payment_attempts row.
  5. File discovery & key release — On verified settlement, the payer calls POST /api/get-invoice-files with the access_token in the body to discover attached files. For each file, GET /api/get-key?invoice_file_id=...&token=access_token releases the decryption key (one-time atomic release, same model as the Agent API), and POST /api/generate-download-url with {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:

PropertyHypawave Offersx402 (Coinbase)
SettlementLightning — instant, final, non-reversibleStablecoin — per-request authorization, custodied wallets
PersistenceOffers persist with lifecycle control (active/fulfilled/paused); unlimited or limited payments via max_paymentsPer-request paywall; each HTTP request re-authorizes
Identitysecp256k1 pubkey — no account, no KYCWallet address — typically custodied
ExecutionWebhook-triggered; settlement proof fires arbitrary actionHTTP 402 response; resource access gated per request
CustodyNon-custodial — funds move peer-to-peer via LightningCustodied wallets with platform intermediary
FinalityGenuine finality — Lightning settlement is irreversibleStablecoin 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.

ProtocolLayerWhat it doesSettlement model
HypawaveExecutionSettlement-triggered deterministic unlock with economic state enforcementFinal, non-reversible (Lightning)
Stripe Machine PaymentsPlatform paymentsPlatform-managed payment and usage rails for machine-to-machine APIsCard / stablecoin rails through Stripe balance; custodial
x402 (Coinbase)HTTP paywallPer-request API paywall via HTTP 402; stablecoin-firstPer-request authorization; custodied wallets
ACP (Stripe + OpenAI)Agent checkoutAgentic commerce checkout flow with shared payment tokensCard rails; reversible
AP2 (Google)Authorization & governanceVerifiable mandate-based agent authorizationPayment-agnostic; governance layer
Raw LightningBase payment railUnderlying network for sending sats; no application or execution layerFinal, 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 5 Applications Freelance platforms, marketplaces, SaaS tools, AI assistants
Layer 4 Agent / Commerce Infrastructure AI agents, API services, compute markets, autonomous workflows
Layer 3 Hypawave — Settlement & Execution Rail Payment → verified settlement → deterministic action
Layer 2 Base Protocol Infrastructure Bitcoin, Lightning Network, TCP/IP, TLS, DNS
Layer 1 Physical Infrastructure Electricity, hardware, data centers, GPUs, internet fiber

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.

Layer 8 Human Interfaces Dashboards, audit tools, accounting views, dispute review
Layer 7 Agent Applications Autonomous research, trading agents, data sellers, compute brokers
Layer 6 Agent Runtime Systems Agent frameworks, planning, task decomposition, tool usage, memory
Layer 5 Hypawave — Economic Execution Settlement proof → deterministic state change → action
Layer 4 Hypawave Protocol — Verification & Authorization Cryptographic proof of intent, stream assembly, settlement verification
Layer 3 Value Transport Networks Bitcoin, Lightning Network
Layer 2 Cryptographic Identity Keypairs, signatures, wallets, identity attestations
Layer 1 Physical Compute + Energy GPUs, data centers, energy grids

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:

LayerExampleAbsorbed by platforms?
ApplicationsMany consumer appsFrequently replaced
AI MiddlewarePrompt routers, orchestratorsHigh risk of absorption
Settlement / Execution RailsStripe, Visa, MastercardSurvived — even Apple, Google, Amazon use them
ProtocolsTCP/IP, SMTP, DNSNever 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.