Frequently Asked Questions
77 answers about Hypawave, Bitcoin settlement, and programmable payments.
Getting Started
What is Hypawave?
Hypawave is a non-custodial Bitcoin Lightning settlement and authorization protocol. You create a payment request, set conditions like amount and expiry, and when payment is confirmed, delivery happens automatically. No intermediaries, no manual approvals.
How do I get paid with Hypawave?
You create a payment request, share the link, and the payer completes it using any Bitcoin or Lightning wallet. Funds go directly to your wallet.
What are the different ways to use Hypawave?
There are two access paths: Agent API (create an account, generate an API key, and let your agent operate under your identity using Bearer token auth and the SDK) and Offers API (no account needed — an autonomous agent generates a secp256k1 keypair and operates independently, supporting both persistent offers and one-off invoices).
Do I need an account to pay a payment request?
No. Anyone can complete a payment request without creating an account.
Do I need an account to receive money?
It depends on the access path. Through the Agent API, you need an account to create and manage payment requests. Through the Offers API, autonomous agents can operate without an account using keypair authentication. In all cases, funds go directly to your wallet — Hypawave never holds your money.
What happens after I pay?
Your payment is confirmed, the transaction is recorded, and any attached deliverables begin the secure unlock process.
Why is there a service fee after payment?
A small service fee is recorded after payment settles, not charged upfront. This keeps the payment direct and non-custodial. Current fee rates are available via GET /api/public-settings.
When do files or deliverables unlock?
Files unlock automatically once payment is confirmed. Settlement is the only condition — delivery is unconditional after that.
What if there are no files or links attached?
Then the payment simply completes. Nothing needs to unlock.
What happens if I close the page after paying?
Nothing is lost. The system continues in the background, and you can return later.
How much does Hypawave cost?
Hypawave charges a small service fee on each payment request, paid separately after the main payment. There are no subscriptions, hidden fees, or setup costs. Current rates and limits are available via GET /api/public-settings.
Can I request payment in my local currency?
Yes. Hypawave supports over 40 fiat currencies. You set the amount in your preferred currency and it converts to Bitcoin at the current exchange rate.
What happens if my payment request expires before the client pays?
The request closes and no payment can be made against it. You can create a new one if needed. Nothing is lost or charged.
API & Integration
What is the Agent API?
The Agent API lets you create and manage payment requests programmatically. You sign up, generate an API key from your dashboard, and authenticate requests with a Bearer token. Your agent operates under your identity.
What is the Offers API?
The Offers API is designed for fully autonomous agents. No account is needed. An agent generates a secp256k1 keypair, authenticates by signing requests with its private key, and operates independently.
How do I get an API key?
Sign up for an account, then generate an API key from your dashboard. Use it as a Bearer token in the Authorization header of your API requests.
What authentication methods does Hypawave support?
Two methods: Bearer token authentication for the Agent API (requires an account and API key), and secp256k1 keypair signature authentication for the Offers API (no account required).
What is the difference between Agent API and Offers API?
The Agent API is for developer-managed agents — you create an account, generate an API key, and your agent creates payment requests programmatically via the SDK. Payers can be other agents or developers (using the payment payload) or end users (via a payment link). The Offers API is for fully autonomous agents — no account needed, the agent generates its own secp256k1 keypair and operates independently. Offers support machine-to-machine settlement, where one agent creates an offer and another agent pays it programmatically.
How do AI agents discover the Hypawave API?
Hypawave publishes a machine-readable OpenAPI specification at /.well-known/openapi.json. AI agents can discover available endpoints, authentication methods, and capabilities automatically.
Can I use Hypawave from any programming language?
Yes. Hypawave is a standard REST API. Any language that can make HTTP requests can integrate with it.
What does the API return after creating a payment request?
A structured response with the payment request ID, Lightning invoice, amount, expiry, and status. Your agent can poll the status endpoint to track settlement.
What Lightning infrastructure do I need?
Payer agents need programmable Lightning infrastructure that exposes the payment preimage after settlement — such as LND, Core Lightning (CLN), Alby API, LNbits, or any NWC-compatible wallet. The preimage is required to confirm settlement with Hypawave. Creator agents just need a Lightning Address to receive payments (any wallet works). Consumer wallets (Wallet of Satoshi, Phoenix, etc.) do not reliably expose the preimage and are not suitable for the payer side. Paths 2, 3a, and 3b are designed for agent-to-agent settlement.
How does an agent confirm payment?
After paying the Lightning bolt11, the agent submits the payment_hash and preimage to POST /api/invoice/{id}/confirm (for invoices) or POST /api/offers/payment-intent/{id}/confirm (for offers). No API key or server secret is needed — the cryptographic proof itself is the authorization.
Programmable Settlement
What does "programmable settlement" mean?
It means payment controls execution. A payment request can include rules like expiry and locked delivery, so access only unlocks after verified payment within a valid time window.
Is Hypawave creating a new kind of money?
No. Hypawave uses Bitcoin exactly as it is. It adds deterministic rules around when delivery happens — not how Bitcoin works.
How is this different from smart contracts?
Smart contracts run code on-chain. Hypawave enforces payment conditions off-chain and only executes actions once payment is verified and valid. No contracts or blockchain deployment required.
Why is programmability useful for getting paid?
It removes ambiguity. If payment is confirmed before expiry, delivery unlocks automatically. If not, the request expires and nothing happens.
What does request expiry actually do?
Expiry creates a hard deadline. After the expiration time, payment attempts are rejected, settlement cannot occur, and delivery remains locked. This prevents stale or ambiguous requests.
Can programmable payments work without files or data?
Yes. Even without files, payment still follows strict rules — correct amount, valid time window, and deterministic completion.
How does Hypawave ensure both sides agree on terms?
When the payer fetches the Lightning bolt11, Hypawave returns a terms_hash — a SHA-256 snapshot of the invoice terms (amount, currency, description, payment destination). The payer submits this hash back when confirming settlement. If terms changed between fetch and confirmation, the request is rejected. This ensures both sides agree on terms before any funds move.
Does Hypawave require persistent connections or streaming?
No. The entire protocol is API-driven — standard HTTP request/response. Developers and agents integrate with simple API calls. No WebSockets, no streaming, no persistent connections required.
Is Hypawave open-source or protocol-based?
Both. The TypeScript SDK is open source under MIT — github.com/hypawave/sdk (@hypawave/sdk on npm). The full API is documented via OpenAPI and agent-readable instructions (llms.txt) — any language can integrate via raw HTTP. The settlement protocol itself follows a formal settlement-as-authorization model with defined state transitions and cryptographic verification, detailed on the Architecture page. The platform server is operated by Hypawave but never holds principal funds (non-custodial).
AI Agents & Automation
Why do AI agents need a system like Hypawave?
AI agents require deterministic outcomes. Hypawave ensures that work executes only if payment is valid, verified, and within its allowed window.
Why can't AI agents rely on traditional banking systems?
Banking systems are reversible, slow, and built for humans. AI agents need instant, final settlement and strict execution conditions.
Why don't wallets alone solve this for AI agents?
Wallets move money but don't control execution. They don't enforce expiry, delivery gating, or deterministic state transitions.
Can an AI agent use Hypawave without a human creating an account?
Yes. The Offers API allows fully autonomous agents to operate with just a secp256k1 keypair. No account, no email, no human setup required.
How does Hypawave support micropayments for AI agents?
Hypawave uses Lightning for instant low-value payments, allowing agents to pay per request or per task without custody or manual approval.
Why is payment finality important for AI agents?
Agents cannot manage disputes or reversals. Hypawave relies on final settlement so agents can act immediately and safely after verification.
How does Hypawave support paid data or service access for agents?
Agents can attach files, data, or API responses to a payment request. Access unlocks automatically only after verified payment within the allowed timeframe.
What problem does Hypawave solve for machine-to-machine workflows?
It removes coordination overhead. Machines don't negotiate trust — they rely on deterministic payment state.
Can AI agents coordinate repeated or ongoing exchanges?
Yes. Agents can generate structured payment requests with defined time windows and execution conditions for recurring or automated interactions.
What happens if an AI agent fails or goes offline mid-exchange?
Nothing breaks. If payment is not completed before expiry, the request expires and execution never happens.
Why is Hypawave suitable for autonomous, long-running agents?
Hypawave is non-custodial and state-driven. Every payment has a clear, final outcome — agents can poll status and act without ambiguity.
Files & Deliverables
Why can't I download files immediately after paying?
Files unlock only after payment is fully confirmed. This ensures the payment is final before any content is released.
What conditions are required to unlock files?
Confirmed payment is the only condition. Once settlement is recorded, files unlock unconditionally.
What happens if a payment session fails or expires?
If a session fails, the payer can retry by fetching a new bolt11 and confirming again. If a payment request expires before payment, it closes and no funds move.
Can files fail to unlock even if payment succeeds?
No. Once payment is confirmed, files always unlock. The payer always receives what they paid for, regardless of the creator's account balance.
Can I access deliverables without creating an account?
Viewing status is possible, but downloading files requires an account for security.
Why do I need an account to download files?
Accounts prevent unauthorized access and protect encrypted content.
Are download links stored in plain text?
No. Links and files are encrypted and protected.
Can Hypawave be used without files at all?
Yes. It works perfectly for simple payment requests with no attachments.
Security & Trust
Is Hypawave custodial?
No. Hypawave never holds your money. Payments go directly from payer to recipient.
Are files encrypted?
Yes. All files are encrypted end-to-end.
Who controls the encryption keys?
Only the sender and recipient. Hypawave does not have access.
Can Hypawave read my files or links?
No. Encryption prevents Hypawave from seeing content.
What happens if someone tampers with a payment link?
The system detects it and blocks completion.
Can someone pay the wrong amount or bypass fees?
No. Amounts are set by the invoice and fees are recorded automatically after payment.
Does Hypawave store my personal data?
Hypawave stores only what is needed to manage payment requests — such as your email and request details. Files are encrypted end-to-end, and Hypawave cannot access their contents. The Offers API path stores no personal data at all — only a public key.
Bitcoin & Lightning
Why does Hypawave use Bitcoin Lightning?
It's fast, global, and allows instant, final settlement — exactly what programmable payments require.
How fast are payments?
Usually seconds.
What wallet should I use?
Payer agents need programmable Lightning infrastructure that exposes the preimage, such as LND, Core Lightning, Alby API, LNbits, or an NWC-compatible wallet. Creator agents only need a Lightning Address to receive payments.
What happens if my wallet doesn't support Lightning?
Hypawave requires a Lightning-compatible wallet. Most modern Bitcoin wallets support Lightning.
Where do service fees go?
They support Hypawave's infrastructure and ongoing development.
Is Bitcoin converted to dollars automatically?
No. You receive Bitcoin directly.
Tracking & Records
How do I track my payment requests?
Developer-managed agents can track payment requests, status, fees, receipts, and unlock events from the dashboard. Accountless agents use status endpoints and machine-readable receipts.
What do "Sent" and "Received" mean?
Sent = payment requests you created. Received = payment requests you completed.
What if I've never sent or received a payment request?
Your history stays empty until you do.
How do I know if a client paid?
The payment request status updates automatically in real time.
How do I know if a service fee is still pending?
Pending fees are clearly shown alongside your payment requests.
Do I get a receipt?
Yes. Every completed payment generates a receipt.
What does a receipt prove?
That a specific payment request was completed at a specific time and amount.
Can I verify a payment cryptographically?
Yes. Receipts can be independently verified.
Can receipts be used for accounting or taxes?
Yes. They provide clear payment records.
Legal / Compliance
Is Hypawave a money transmitter?
No. Hypawave does not take custody of funds.
Does Hypawave require KYC?
No KYC is required to use Hypawave.
Who is responsible for taxes?
Users are responsible for their own tax reporting.
What countries are supported?
Hypawave works globally wherever Bitcoin and Lightning are available.