1. Quick Start 2. TypeScript SDK 3. Overview 4. Authentication 5. Key Management 6. Endpoints 7. Pubkey Authentication 8. Offers (Accountless Agents) 9. One-Time Custom Payments 10. Agent-to-Agent Walkthrough 11. Webhooks & Callbacks 12. File Attachments 13. Test vs Live Mode 14. Rate Limits 15. Error Reference 16. Error Recovery 17. Idempotency 18. Code Examples 19. API Reference

Hypawave Agent API

Complete reference for the programmable Bitcoin settlement API

Quick Start

Get from zero to your first payment request in 5 steps.

Create an API key — Open the menu, go to API Keys, create a live key, and copy it immediately. The raw key is shown only once.
Create a payment request — POST /api/agent/create-invoice with your key in the Authorization header. Specify amount, currency, and client details. payment_destination defaults to your API key owner's saved lightning_address; pass it explicitly only to override (marketplace, multi-wallet, or pass-through flows).
Send to payer agent — The response includes invoice_id, access_token, and instructions_url. Send the payment payload to the payer agent via any channel (HTTP, MCP, A2A, etc.). The instructions_url points to machine-readable settlement instructions so the payer agent can complete the flow without prior Hypawave knowledge. The response also includes payment_url — a browser-based payment page. Use it when the payer pays via a browser.
Payer agent confirms settlement — The payer agent calls GET /api/paystream-cb?token={access_token} to fetch the Lightning bolt11, pays it using their own programmable Lightning infrastructure (LND, CLN, Alby API, LNbits, NWC, etc.), then submits the payment_hash and preimage to POST /api/invoice/{id}/confirm. A service fee is recorded (see GET /api/public-settings for current fee_percent).
Attachments unlock (if any) — Encrypted files become available. Retrieve the decryption key via GET /api/get-key.

Minimal curl Example

curl -X POST /api/agent/create-invoice \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5.00,
    "currency": "USD",
    "payment_destination": "you@wallet.com",
    "client_email": "client@example.com",
    "client_first_name": "Jane",
    "creator_first_name": "Agent"
  }'

Note: First payment request is free — balance starts at zero. After payment settles, a service fee is recorded (see GET /api/public-settings for current fee_percent). When balance goes negative, call POST /api/agent/topup (empty body) to mint a bolt11 for exactly the amount owed and settle fees. To settle programmatically, the agent needs outbound Lightning payment capability (a funded wallet that can pay bolt11s). Otherwise, settle fees via the dashboard.

TypeScript SDK

The fastest way to integrate with Hypawave. Zero dependencies, full TypeScript types, works in Node.js and any modern runtime.

Install

npm install @hypawave/sdk

Open source under MIT — source code at github.com/hypawave/sdk.

Quick Example

import { Hypawave } from "@hypawave/sdk";

const hw = new Hypawave({ apiKey: "sk_live_YOUR_KEY" });

const invoice = await hw.createInvoice({
  client_email: "buyer@example.com",
  client_first_name: "Buyer",
  client_last_name: "Agent",
  amount: 5.00,
  currency: "USD",
  due_date: "2026-03-01",
  payment_destination: "seller@wallet.com",
  expires_in: "1h",
});

console.log(invoice.payment_url);

const result = await hw.waitForSettlement(invoice.invoice_id);
console.log("Settled:", result.settlement_proof);

Available Methods

Method	Description
`createInvoice(params)`	Create a payment request
`getBolt11(accessToken)`	Fetch creator-issued Lightning bolt11
`confirmPayment(invoiceId, params)`	Confirm settlement with preimage
`getPaymentPayload(params, response)`	Build self-describing payload for agent interop
`getBalance(currency?)`	Check settlement balance
`topup()`	Settle outstanding fees via Lightning
`getUnlockStatus(invoiceIds)`	Check settlement status
`getInvoiceFiles(invoiceIds)`	Get file metadata for invoices
`getDownloadUrl(fileId)`	Generate signed download URL
`getKey(fileId)`	Retrieve encryption key for a file
`getReceipt(invoiceId)`	Get creator receipt for settled invoice
`getPayerReceipt(invoiceId, preimage)`	Get payer receipt for settled invoice
`getSettings()`	Fetch current platform configuration
`waitForSettlement(invoiceId, opts?)`	Poll until settled (with timeout)
`getUploadUrl(params)`	Get presigned URL for file upload
`storeFile(params)`	Store encrypted file metadata
`storeFileKey(params)`	Store encryption key for file
`listInvoices(params?)`	List your payment requests

Error Handling

import { Hypawave, HypawaveAPIError } from "@hypawave/sdk";

try {
  const invoice = await hw.createInvoice({ ... });
} catch (err) {
  if (err instanceof HypawaveAPIError) {
    console.error(err.status, err.code, err.message);
  }
}

CJS + ESM + TypeScript — The SDK ships as CommonJS, ES Modules, and full type declarations. Works with any bundler, Node.js, Bun, or Deno.

Overview

The Hypawave Agent API is the programmable interface to Bitcoin-native settlement. Developers and agents create payment requests, attach encrypted data, check balances, and settle outstanding fees — all through API keys and the SDK.

Who is it for

AI agents needing to pay/sell data/compute/services autonomously
Developers building agent-to-agent workflows
Automated systems
Any software needing programmable non-custodial Bitcoin settlement

What can it do

Create payment requests with fiat→BTC conversion
Attach encrypted files/links/data
Gate access to content
Check balance in sats and fiat
Settle outstanding fees via Lightning (fee-settlement only — balance never goes above zero)
API keys provisioned from menu

Bigger Picture

Settlement layer for autonomous commerce. Hypawave Protocol handles authorization and settlement verification. Bitcoin is the rail.

Base URL

https://hypawave.com/api/agent/

Note: The Agent API is powered by the Hypawave Protocol — same encryption, settlement verification, and unlock logic across all paths.

Authentication

All Agent API requests require a Bearer token in the Authorization header. No cookies or CSRF.

Header

Authorization: Bearer sk_live_...

Key Formats

Format	Mode
`sk_test_<base64url>`	Test mode
`sk_live_<base64url>`	Live mode

Security

Keys hashed SHA-256 before storage
Raw key shown once at creation
Revoked keys rejected immediately
Every request logged for audit

Key Management

Keys are created and revoked from the API Keys section in the menu. Requires login.

POST /api/agent/create-key

Create a new API key.

Request body:

{
  "mode": "test" | "live",
  "label": "optional"
}

Response:

{
  "key": "sk_live_abc123...",
  "prefix": "sk_live_ab",
  "mode": "live",
  "message": "Store securely, not shown again"
}

POST /api/agent/revoke-key

Revoke an existing API key.

Request body:

{
  "key_id": "uuid",
  "reason": "optional"
}

Rate Limit

5 requests/hour per IP, 3/hour per identity.

Endpoints

POST /api/agent/create-invoice

Create a payment request.

Request body fields:

Field	Description
`client_email`	Payer's email address
`client_first_name`	Payer's first name
`client_last_name`	Payer's last name
`amount`	Payment amount
`currency`	Currency code (40+ supported)
`due_date`	Due date
`payment_destination`	Lightning Address or LNURL-pay URL. Optional — defaults to the API key owner's saved `lightning_address`. Override per-call for marketplace routing, multi-wallet owners, or pass-through flows.
`description`	Description text
`company_name`	Company name
`expires_in`	Expiry: 1h, 24h, 7d, or null
`creator_first_name`	Creator's first name
`creator_last_name`	Creator's last name

Response (201):

Field	Description
`ok`	Success boolean
`invoice_id`	Invoice identifier
`access_token`	Token for payment flow
`payment_url`	Browser-based payment page
`instructions_url`	Settlement instructions for payer agents (llms.txt)
`stream_id`	Stream identifier
`amount`	Amount in specified currency
`currency`	Currency code
`sats`	Amount in satoshis
`btc_usd_rate`	BTC/USD rate used
`expires_at`	Expiration timestamp

Limits: Amount limits and fee percentage are configurable — query GET /api/public-settings for current values (min_invoice_usd, max_invoice_usd, fee_percent). 40+ currencies, expiry 1h/24h/7d/null. Creating invoices requires a non-negative balance — a service fee is deducted post-settlement.

GET /api/agent/balance

Check balance.

Query: ?currency=USD

Response (200):

Field	Description
`available_sats`	Balance in satoshis
`fiat_equivalent`	Balance in requested currency
`currency`	Currency code
`btc_price`	Current BTC price
`has_outstanding_fee`	Whether a fee is pending

POST /api/agent/topup

Mint a Lightning invoice for exactly the amount owed in outstanding settlement fees.

Fee-settlement only. The server mints a bolt11 for exactly -available_sats. Callers cannot specify an amount. If the balance is already ≥ 0, the request is rejected with topup_not_needed. Hypawave never pre-funds balances.

Request body:

{} // empty — any fields are ignored

Response (200):

Field	Description
`ok`	Success boolean
`bolt11`	Lightning invoice for the exact owed amount
`payment_hash`	Payment hash
`amount_sats`	Exact owed amount in satoshis
`expires_at`	Invoice expiration
`reused`	`true` if an existing pending invoice was returned (double-click protection)

400 errors: topup_not_needed (balance is already ≥ 0; response includes available_sats).

GET /api/paystream-cb

Fetch the creator-issued Lightning bolt11 for payment. Used by agent/developer payers to get the invoice to pay.

Query: ?token={access_token}

Response (200):

Field	Description
`pr`	Lightning bolt11 invoice (pay this with your Lightning node)
`routes`	Routing hints (typically empty)

402 errors: activation_pending (accountless invoices only — activation fee has not settled yet).

POST /api/invoice/{id}/confirm

Confirm invoice payment by submitting the Lightning preimage. No API key or webhook secret required — authorization is cryptographic proof bound to the specific invoice.

Request body:

{
  "payment_hash": "64-char hex",
  "preimage": "64-char hex"
}

Response (200):

Field	Description
`ok`	Success boolean
`already_settled`	`true` if the invoice was already settled (idempotent)

Errors: 400 missing_proof, invalid_payment_hash, invalid_preimage, preimage_hash_mismatch, no_matching_attempt. 404 invoice_not_found, transaction_not_found. 409 payment_hash_replay.

Requirement: This endpoint requires programmable Lightning infrastructure (LND, CLN, Alby API, LNbits, NWC, etc.) that exposes the payment_hash and preimage after successful payment. Consumer wallets (Wallet of Satoshi, Phoenix, etc.) do not reliably expose the preimage.

Pubkey Authentication

Accountless agents authenticate using a secp256k1 keypair instead of API keys. No account creation, no login, no browser required. The agent's compressed public key is its identity.

Two primitives, one identity

Accountless agents have two distinct ways to transact. Offers are persistent, reusable payment endpoints — any agent or human can pay them at any time, designed for standing services with repeating payments. One-time custom payments are single-use invoices with optional encrypted file attachments, scoped to a single payer — the same model as the Agent API but without requiring an account. Both use the same keypair auth and the same prepaid balance.

Header Format

Header	Type	Description
`x-pubkey`	string	Compressed public key (66-char hex)
`x-signature`	string	secp256k1 signature over the payload hash (hex)
`x-signed-payload-hash`	string	SHA-256 hash of the raw request body (hex)

How It Works

Hash the request body — Compute SHA-256 of the raw JSON body to produce a 32-byte payload hash.
Sign the hash — Sign the payload hash with your secp256k1 private key to produce a DER-encoded signature.
Set headers — Include x-pubkey (your compressed public key), x-signature (the signature), and x-signed-payload-hash (the hex hash) on the request.
Auto-identity — On first request, Hypawave auto-creates a pubkey-only identity. No registration needed — the public key IS the identity.

GET Requests: GET endpoints (balance, list) have no request body. Sign an empty string "" instead — compute sha256("") and use that as both the value you sign and the x-signed-payload-hash header.

Signing Example (JavaScript)

import * as secp from "@noble/secp256k1";
import { createHash } from "crypto";

const privateKey = secp.utils.randomPrivateKey();
const publicKey = Buffer.from(
  secp.getPublicKey(privateKey)
).toString("hex");

function signRequest(body) {
  const raw = JSON.stringify(body);
  const payloadHash = createHash("sha256")
    .update(raw).digest("hex");
  const sig = secp.sign(payloadHash, privateKey);
  const signature = Buffer.from(
    sig.toDERRawBytes()
  ).toString("hex");

  return {
    headers: {
      "x-pubkey": publicKey,
      "x-signature": signature,
      "x-signed-payload-hash": payloadHash,
      "Content-Type": "application/json",
    },
    body: raw,
  };
}

// Example: list offers (sign an empty body)
const body = {};
const { headers, body: rawBody } = signRequest(body);

const res = await fetch(
  "https://hypawave.com/api/offers/list?status=active",
  { method: "GET", headers }
);

Account-Based vs. Pubkey Auth

Property	API Key (Bearer)	Pubkey Auth
Identity	Supabase auth user + identity row	Pubkey-only identity (no auth user)
Setup	Sign up, log in, create API key	Generate keypair — done
Fee model	Postpaid (service fee deducted from balance on settlement)	Upfront (pay activation bolt11 to activate; no balance writes)
Endpoints	/api/agent/* endpoints	/api/offers/* endpoints
Use case	Humans + managed agents	Autonomous agents, accountless access

Pubkey auth is designed for fully autonomous agents. The agent's private key never leaves the agent's runtime. Hypawave only ever sees the public key and signatures.

Persistent Identity & History

Your keypair is your identity. On first contact, Hypawave auto-creates an identity row linked to your public key. As long as you sign with the same private key, you can query your full history at any time:

GET /api/offers/list-invoices — all invoices you created (Path 3a)
GET /api/offers/list-payments — payment history per offer (Path 3b)
POST /api/offers/payment-intent/{id}/receipt — settlement receipt
POST /api/offers/payment-intent/{id}/status — payment intent status

Lose the private key, lose access to history. There is no recovery mechanism — the keypair is the sole credential.

Offers (Accountless Agents)

Offers are persistent, reusable payment endpoints — unlike one-off invoices, an offer lives until the creator deactivates it and any agent or human can pay it at any time. Each payment spawns an independent payment intent. For single-payer, one-time flows, see One-Time Custom Payments.

Upfront activation fee model

Accountless offers are non-custodial on both sides: you pay Hypawave's service fee upfront (never postpaid), and payers pay you directly over Lightning. POST /api/offers returns a top-level activation sibling containing a Hypawave-issued fee_bolt11. Pay it to activate the offer. The offer is inert until that fee settles and stays payable for the requested activation_window (default 30d, bounds [1d, 365d]). When the window elapses, call POST /api/offers/{id}/renew to mint a fresh activation bolt11.

Fee policy: max(min_fee_sats, floor(declared_price_sats * fee_percent / 100)). See GET /api/public-settings for current values. For fiat offers, declared_price_sats is locked at mint time using a fresh BTC price. Offer terms are snapshotted into terms_hash; editing them after activation surfaces 409 terms_changed at pay time — revert or /renew.

POST /api/offers/{id}/renew

Mint a fresh activation fee bolt11 to extend or resume service on an accountless offer. Creator-only (your pubkey must match the offer's creator_pubkey). Returns an activation object in the same shape as create.

Behavior: an existing pending bolt11 is returned unchanged with reused: true (retry-safe). An expired pending row is lazy-expired and a fresh one is minted. If the current window is still active, the endpoint returns 400 activation_not_needed with window_end so you can decide when to renew.

// Auth: Pubkey headers
// Request body (optional):
{
  "activation_window": "30d"  // optional, default 30d, bounds [1d, 365d]
}

// Response (200):
{
  "ok": true,
  "offer_id": "uuid-...",
  "reused": false,
  "activation": {
    "fee_bolt11": "lnbc...",
    "fee_payment_hash": "abc...",
    "fee_amount_sats": 100,
    "expires_at": "2026-04-18T00:00:00Z",
    "status": "pending",
    "requested_window_ms": 2592000000,
    "terms_hash": "..."
  }
}

GET /api/offers/list

List the calling agent's own offers. Useful for state recovery and idempotency — check for an existing active offer before creating a duplicate. Filter by ?status= (active, deactivated, or exhausted). Defaults to active. Capped at 100 results.

// Auth: Pubkey headers — sign empty string sha256("")
// Response (200):
{
  "offers": [
    {
      "id": "uuid-...",
      "amount": 100,
      "currency": "sats",
      "pricing_type": "sats",
      "description": "Weather API query",
      "status": "active",
      "max_payments": null,
      "payment_count": 3,
      "execution_webhook": "https://...",
      "created_at": "2026-03-10T10:00:00Z"
    }
  ],
  "count": 1
}

GET /api/offers/list-invoices

List all invoices the identity created — covers both one-time custom payments and offer-triggered invoices. Supports ?status=paid|not_paid|expired, ?limit= (max 50), and ?offset=.

// Auth: Pubkey headers — sign empty string sha256("")
// Response (200):
{
  "invoices": [
    {
      "invoice_id": 42,
      "stream_id": "uuid",
      "amount": 15.00,
      "currency": "USD",
      "description": "Design work",
      "status": "paid",
      "created_at": "2026-03-10T10:00:00Z",
      "due_date": "2026-04-01",
      "expires_at": "2026-03-11T10:00:00Z",
      "client_first_name": "Jane",
      "client_last_name": "Doe",
      "company_name": "Acme Inc",
      "has_file": true,
      "payment_hash": "abc123...",
      "preimage": "def456...",
      "paid_at": "2026-03-10T11:00:00Z"
    }
  ],
  "has_more": false
}

GET /api/offers/list-payments

List all payment intents received against the identity's offers, with full settlement state. Use for auditing, reconciliation, and crash recovery. Supports ?status=pending|settled|failed, ?offer_id=, ?limit= (max 50), and ?offset=.

// Auth: Pubkey headers — sign empty string sha256("")
// Response (200):
{
  "payments": [
    {
      "payment_intent_id": "uuid",
      "offer_id": "uuid",
      "status": "settled",
      "locked_amount_sats": 14250,
      "locked_fiat_amount": 15.00,
      "locked_currency": "USD",
      "locked_btc_rate": 105263,
      "offer_description": "Weather API query",
      "offer_amount": 100,
      "offer_currency": "sats",
      "payer_pubkey": "02abc...",
      "payment_hash": "abc123...",
      "preimage": "def456...",
      "settled_at": "2026-03-10T11:00:00Z",
      "created_at": "2026-03-10T10:00:00Z",
      "execution_fired": true
    }
  ],
  "has_more": false
}

POST /api/offers

Create a new offer. Account-based creators require non-negative balance; accountless creators pay an upfront activation fee instead. Supports pubkey auth or Bearer token. Set max_payments to limit payments (e.g. 1 for single-use delivery). Omit or set to null for unlimited. payment_destination is required — the creator's Lightning Address or LNURL-pay URL where payers will be sent at pay time.

Required fields:

Field	Type	Description
`amount`	number	Price per payment
`pricing_type`	string	'sats' or 'fiat'
`description`	string	What the offer provides
`payment_destination`	string	Creator's Lightning Address or LNURL-pay URL
`signed_payload_hash`	string	SHA-256 of body (hex)
`signature`	string	secp256k1 signature (hex)

Optional fields:

Field	Type	Description
`currency`	string	Fiat code (if pricing_type='fiat')
`execution_webhook`	string	HTTPS URL to call on settlement
`max_payments`	integer\|null	Payment limit (null = unlimited)
`metadata`	object	Arbitrary key-value metadata
`activation_window`	string	"Nd" format, default "30d", bounds [1d, 365d]

// Response (201):
{
  "offer_id": "uuid-...",
  "created_at": "2026-03-10T10:00:00Z",
  "max_payments": 1
}

GET /api/offers/{id}

Read an offer. Public endpoint — no authentication required. Returns offer details including payment limits and file attachment info.

// Auth: None
// Response (200):
{
  "id": "uuid-...",
  "amount": 100,
  "currency": "sats",
  "pricing_type": "sats",
  "description": "Weather API query",
  "creator_pubkey": "02abc123...",
  "status": "active",
  "max_payments": 1,
  "payment_count": 0,
  "has_files": true,
  "file_count": 1,
  "created_at": "2026-03-10T10:00:00Z"
}

DELETE /api/offers/{id}

Deactivate an offer. Only the creator (matching pubkey) can deactivate it. Existing settled payment intents are not affected. Returns 409 if already deactivated.

// Auth: Pubkey headers — sign empty string, must be creator
// Response (200):
{
  "ok": true,
  "id": "uuid-...",
  "status": "deactivated"
}

POST /api/offers/{id}/pay

Pay an offer. Hypawave fetches a fresh Lightning invoice from the creator's payment_destination endpoint and returns it along with a payer_secret. The payer pays the bolt11 directly to the creator — Hypawave never receives the principal. No authentication required — anyone can pay.

// Auth: None (rate-limited by IP)
// Request body (optional):
{
  "payer_pubkey": "03def456..."
}

// Response (200):
{
  "payment_intent_id": "uuid-...",
  "bolt11": "lnbc1u1p...",
  "payment_hash": "def456...",
  "payer_secret": "a1b2c3d4...",
  "locked_amount_sats": 100,
  "locked_currency": "sats",
  "locked_btc_rate": null,
  "expires_at": null
}

Save the payer_secret immediately. It is required to submit the preimage proof via the confirm endpoint and to check status / retrieve file keys after settlement. It is shown only once and stored hashed.

POST /api/offers/payment-intent/{id}/confirm

Submit settlement proof for a direct-pay offer payment. After paying with your programmable Lightning infrastructure (LND, CLN, Alby API, LNbits, NWC, etc.), POST the preimage and payer_secret. Hypawave verifies SHA256(preimage) === payment_hash and authorizes the intent. Idempotent: repeated calls return already_settled: true.

// Auth: payer_secret in body (rate-limited by IP)
// Request body:
{
  "preimage": "64-char-hex-preimage",
  "payer_secret": "a1b2c3d4..."
}

// Response (200):
{
  "ok": true,
  "payment_intent_id": "uuid-...",
  "already_settled": false,
  "settled_unpaid_fee": false
}

Errors: 400 invalid_preimage, 400 missing_payer_secret, 400 preimage_mismatch, 401 unauthorized, 404 payment_intent_not_found.

POST /api/offers/upload-url

Get a presigned URL to upload an encrypted file for an offer. URL expires after 1 hour.

// Auth: Pubkey signature
// Request:
{ "offer_id": "uuid-...", "fileName": "deliverable.zip.enc", "contentType": "application/octet-stream", "fileSize": 102400 }

// Response:
{ "signedUrl": "https://...", "objectKey": "offers/uuid-deliverable.zip.enc" }

POST /api/offers/store-file

Link uploaded file metadata to an offer. Only the offer creator can call this.

// Auth: Pubkey signature
// Request:
{ "offer_id": "uuid-...", "storage_key": "offers/uuid-deliverable.zip.enc", "filename": "deliverable.zip.enc", "size": 102400, "iv_hex": "aabbccdd..." }

// Response:
{ "ok": true, "offer_file_id": "offer-file-uuid" }

POST /api/offers/store-file-key

Store the wrapped encryption key for a file attached to an offer.

// Auth: Pubkey signature
// Request:
{ "offer_file_id": "offer-file-uuid", "wrapped_key": "base64-encoded-key", "key_version": 1, "wrap_algo": "aes-256-gcm" }

// Response:
{ "ok": true }

GET /api/offers/payment-intent/{id}/status

Check payment intent status. Requires the payer_secret returned at pay time. After settlement, includes a claim_token for file key retrieval.

// Auth: payer_secret query parameter
GET /api/offers/payment-intent/{id}/status?secret=a1b2c3d4...

// Response (settled, with files):
{
  "status": "settled",
  "settled_at": "2026-03-10T11:00:00Z",
  "has_files": true,
  "claim_token": "e5f6g7h8..."
}

GET /api/offers/payment-intent/{id}/file-key

Retrieve wrapped decryption keys for all files attached to a settled payment intent. Requires a valid claim_token or the Lightning preimage as proof of payment.

// Auth: claim_token or preimage query parameter
GET /api/offers/payment-intent/{id}/file-key?claim_token=e5f6g7h8...

// Response (200):
{
  "files": [
    {
      "offer_file_id": "file-uuid",
      "filename": "deliverable.zip.enc",
      "wrapped_key": "base64-encoded-key",
      "iv_hex": "aabbccdd...",
      "key_version": 1,
      "wrap_algo": "aes-256-gcm"
    }
  ]
}

POST /api/offers/payment-intent/{id}/download-url

Generate a time-limited presigned download URL (5 min) for a single encrypted offer file. Authenticated via claim_token or preimage in the request body.

// Request:
{ "offer_file_id": "file-uuid", "claim_token": "e5f6g7h8..." }

// Response:
{ "downloadUrl": "https://r2-signed-url...?expires=300" }

GET /api/offers/payment-intent/{id}/receipt

Retrieve a structured JSON receipt for a settled payment intent. Authenticated via payer_secret.

// Auth: payer_secret query parameter
GET /api/offers/payment-intent/{id}/receipt?secret=a1b2c3d4...

// Response (200):
{
  "receipt": {
    "payment_intent_id": "uuid",
    "offer_id": "uuid",
    "status": "settled",
    "payment_hash": "abc123...",
    "locked_amount_sats": 5000,
    "locked_fiat_amount": 5.00,
    "locked_currency": "USD",
    "locked_btc_rate": 100000,
    "offer_description": "Weather API query",
    "settled_at": "2026-03-10T...",
    "has_files": true,
    "file_count": 1
  }
}

Pricing Types

Type	Behavior	Use case
`sats`	Fixed satoshi amount. Invoice is created for exactly this amount.	Machine-to-machine payments
`fiat`	Fiat-denominated. Converted to sats at current BTC price when payment intent is created.	Services priced in USD/EUR etc.

Offers are designed for autonomous agents. The creator sets up an offer once, and any number of payers can pay it independently. Each payment creates a separate payment intent with a snapshot of the offer terms at the time of payment. Offers support encrypted file attachments — attach files at creation, and payers retrieve decryption keys after settlement.

One-Time Custom Payments

The second primitive available to accountless agents. One-time custom payments are single-use invoices targeted at a specific payer — the same model as the Agent API's create-invoice, but authenticated with a secp256k1 keypair instead of a Bearer token. All the same fields are supported: expiry, currencies, client info, creator branding, and optional encrypted file attachments. Like offers, the creator pays an upfront activation fee at creation (see GET /api/public-settings for current fee_percent and min_fee_sats) — no balance, no postpaid debt.

Flow

Create the invoice — POST /api/offers/create-invoice with pubkey headers. Specify all client and payment details. Response returns invoice_id, access_token, payment_url, AND a top-level activation object containing fee_bolt11 — an upfront activation fee you must pay before the invoice becomes payable.
Pay the activation fee — Pay activation.fee_bolt11 using any Lightning wallet. The fee is computed from the declared invoice amount (see GET /api/public-settings for fee_percent). Until this settles, the payment_url returns 402 activation_pending.
(Optional) Encrypt a file locally — AES-256-GCM recommended. Generate a random key and IV. Upload the encrypted blob to storage and note the objectKey.
(Optional) Store invoice file — POST /api/offers/store-invoice-file with the invoice_id, objectKey, IV, and key hash.
(Optional) Store decryption key — POST /api/offers/invoice-file-key with the invoice_file_id and base64-encoded encryption key.
Share and poll — Share the payment_url with the payer. Poll settlement status via POST /api/get-unlock-status with pubkey headers and { invoice_ids: [42] }. After Lightning settlement, the protocol releases the file key automatically.

Endpoints

POST /api/offers/create-invoice

Auth: Pubkey headers. Mints a Hypawave-issued activation fee bolt11 returned in the activation response field. The invoice is inert until the creator pays that fee.

// Request body:
{
  "client_email": "client@example.com",
  "client_first_name": "Jane",
  "client_last_name": "Doe",
  "amount": 15.00,
  "currency": "USD",
  "due_date": "2026-04-01",
  "payment_destination": "user@wallet.com",
  "description": "Design work",
  "expires_in": "24h"
}

// Response (201):
{
  "ok": true,
  "invoice_id": 42,
  "access_token": "tok_...",
  "payment_url": "https://hypawave.com/client_payment?invoiceId=42&token=tok_...",
  "stream_id": "uuid",
  "amount": 15.00,
  "currency": "USD",
  "sats": 14250,
  "btc_usd_rate": 105263,
  "expires_at": "2026-04-01T12:00:00Z",
  "activation": {
    "fee_bolt11": "lnbc1500n1...",
    "fee_payment_hash": "ab12...64chars",
    "fee_amount_sats": 143,
    "expires_at": "2026-03-29T14:00:00Z",
    "status": "pending"
  }
}

POST /api/offers/store-invoice-file

Auth: Pubkey headers. Register an encrypted file attachment against an invoice you created.

// Request:
{ "invoice_id": 42, "file_name": "deliverable.zip.enc", "encrypted_file_url": "uploads/abc-deliverable.zip.enc", "iv_hex": "aabbccdd...", "key_hash": "sha256-of-encryption-key", "size": 102400 }

// Response:
{ "ok": true, "id": "file-uuid" }

POST /api/offers/invoice-file-key

Auth: Pubkey headers. Store the base64-encoded decryption key for a file attached to your invoice.

// Request:
{ "invoice_file_id": "file-uuid", "key_b64": "base64-encoded-aes-key" }

// Response:
{ "ok": true }

POST /api/get-unlock-status

Auth: Pubkey headers, Bearer token, or session cookie. Poll settlement status for your invoices.

// Request:
{ "invoice_ids": [42, 43] }

// Response:
{ "unlocked": { "42": true }, "statuses": { "42": { "unlocked": true, "status": "key_released" } } }

Accountless agents pay an upfront activation fee at creation — no balance, no postpaid debt. Each invoice has its own activation lifecycle: pay the activation.fee_bolt11, and the invoice becomes payable. To retrieve history, use GET /api/offers/list-invoices.

Agent-to-Agent Walkthrough

Complete end-to-end walkthrough of two autonomous agents transacting through the offers system. No accounts, no API keys, no browser, no human in the loop.

The Flow

Agent A generates a keypair — Agent A generates a secp256k1 private key and derives its compressed public key. This public key is the agent's permanent identity.
Agent A creates an offer — POST /api/offers with amount, pricing_type, description, payment_destination (Agent A's Lightning Address or LNURL-pay URL), an optional execution_webhook URL, and an optional activation_window ("30d" default, bounds [1d, 365d]). The response includes a top-level activation object containing a Hypawave-issued fee_bolt11.
Agent A pays the activation fee — Pay activation.fee_bolt11 using any Lightning wallet. Fee is computed from the declared price (see GET /api/public-settings for fee_percent). Once the fee settles, the offer becomes payable for the requested activation_window. Extend or resume service later via POST /api/offers/{id}/renew.
Agent B discovers the offer — GET /api/offers/{id} returns the offer details. Agent B evaluates whether to pay.
Agent B pays the offer — POST /api/offers/{id}/pay returns a creator-issued Lightning invoice and a payer_secret. The route enforces the activation gate — returns 402 offer_inactive if the activation window has elapsed, or 409 terms_changed if Agent A edited the offer's terms after activation. Agent B saves the payer_secret and pays the invoice directly to Agent A.
Agent B confirms settlement — After Agent B's wallet reveals the preimage, Agent B POSTs {preimage, payer_secret} to /api/offers/payment-intent/{id}/confirm. Hypawave verifies SHA256(preimage) == payment_hash and POSTs to Agent A's execution_webhook. No fee deduction at settlement — the fee was already paid upfront via activation.
Agent B retrieves its receipt — GET /api/offers/payment-intent/{id}/receipt?secret={payer_secret} returns a structured JSON receipt — machine-readable proof of the transaction.

Complete Example (JavaScript)

import * as secp from "@noble/secp256k1";
import { createHash } from "crypto";

const BASE_URL = "https://hypawave.com";

// --- Agent A: Setup ---
const privKey = secp.utils.randomPrivateKey();
const pubKey = Buffer.from(
  secp.getPublicKey(privKey)
).toString("hex");

function signedFetch(path, body) {
  const raw = JSON.stringify(body);
  const hash = createHash("sha256")
    .update(raw).digest("hex");
  const sig = secp.sign(hash, privKey);
  const signature = Buffer.from(
    sig.toDERRawBytes()
  ).toString("hex");

  return fetch(BASE_URL + path, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-pubkey": pubKey,
      "x-signature": signature,
      "x-signed-payload-hash": hash,
    },
    body: raw,
  });
}

// Step 1: Create an offer with activation_window
const offerRes = await signedFetch("/api/offers", {
  amount: 100,
  pricing_type: "sats",
  description: "Weather data for any city",
  payment_destination: "agent-a@wallet.com",
  execution_webhook:
    "https://agent-a.example.com/on-payment",
  activation_window: "30d",
});
const offer = await offerRes.json();
console.log("Offer created:", offer.offer_id);

// Step 2: Pay activation.fee_bolt11 to activate
console.log(
  "Activate:",
  offer.activation.fee_bolt11,
  offer.activation.fee_amount_sats + " sats"
);
// ... Agent A pays via Lightning ...

// --- Agent B: Discover and pay ---
// Step 3: Read the offer (public, no auth)
const infoRes = await fetch(
  BASE_URL + "/api/offers/" + offer.offer_id
);
const info = await infoRes.json();
console.log(info.description, info.amount);

// Step 4: Pay (returns creator-issued bolt11)
const payRes = await fetch(
  BASE_URL + "/api/offers/" +
    offer.offer_id + "/pay",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      payer_pubkey: "03...",
    }),
  }
);
const payment = await payRes.json();
console.log("Pay invoice:", payment.bolt11);
// Agent B pays directly to Agent A via Lightning

// Step 5: Submit settlement proof
await fetch(
  BASE_URL + "/api/offers/payment-intent/" +
    payment.payment_intent_id + "/confirm",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      preimage: "64-char-hex-from-wallet",
      payer_secret: payment.payer_secret,
    }),
  }
);
// Hypawave verifies preimage and fires
// Agent A's execution_webhook.

Quick Reference (curl)

# Read an offer (public)
curl https://hypawave.com/api/offers/OFFER_ID

# Pay an offer
curl -X POST \
  https://hypawave.com/api/offers/OFFER_ID/pay \
  -H "Content-Type: application/json" \
  -d '{"payer_pubkey": "03..."}'

# Confirm settlement (submit preimage)
curl -X POST \
  https://hypawave.com/api/offers/payment-intent/INTENT_ID/confirm \
  -H "Content-Type: application/json" \
  -d '{"preimage": "PREIMAGE_HEX", "payer_secret": "PAYER_SECRET"}'

# Get receipt for a settled payment
curl "https://hypawave.com/api/offers/payment-intent/INTENT_ID/receipt?secret=PAYER_SECRET"

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.

With File Delivery

The same flow extends to encrypted file delivery. Agent A attaches encrypted files to the offer. Agent B pays, then retrieves the decryption keys after settlement.

Agent A creates offer with file — Agent A creates an offer (optionally with max_payments: 1 for single-use delivery), then attaches an encrypted file via upload-url, store-file, and store-file-key.
Agent B discovers and pays — Agent B reads the offer (has_files: true, file_count: 1), then calls POST /api/offers/{id}/pay. Saves the payer_secret and pays the creator-issued Lightning invoice directly to Agent A.
Agent B confirms settlement — Agent B POSTs {preimage, payer_secret} to /api/offers/payment-intent/{id}/confirm.
Agent B checks status — Agent B calls GET /api/offers/payment-intent/{id}/status?secret=... On settlement, the response includes a claim_token.
Agent B retrieves file keys — Agent B calls GET /api/offers/payment-intent/{id}/file-key?claim_token=... to get the wrapped decryption keys.
Agent B downloads encrypted files — For each file, POST /api/offers/payment-intent/{id}/download-url with {offer_file_id, claim_token}. Returns a time-limited presigned URL (5 min).
Agent B retrieves its receipt — GET /api/offers/payment-intent/{id}/receipt?secret={payer_secret} returns a structured JSON receipt.
Agent B decrypts locally — Agent B fetches the encrypted blob, unwraps the encryption key, and decrypts. Payment was the authorization.

Webhooks & Callbacks

Hypawave uses polling, not push webhooks.

How Payment Confirmation Works

Principal payments (buyer → creator) are non-custodial and direct. Settlement is confirmed by cryptographic proof — the payer submits the Lightning preimage to Hypawave:

Invoices (Paths 2/3a): Payer calls POST /api/invoice/{id}/confirm with {payment_hash, preimage}. Hypawave verifies SHA256(preimage) == payment_hash and matches against a recorded payment attempt.
Offers (Path 3b): Payer calls POST /api/offers/payment-intent/{id}/confirm with {preimage, payer_secret}.
Trusted integrations: Server-to-server settlement via POST /api/wallet-webhook (requires WALLET_WEBHOOK_SECRET).

Topup and fee payments are confirmed via an LNbits webhook (secret URL token + server-side API verification). All webhooks are internal infrastructure — agents do not receive push notifications and should poll /api/get-unlock-status or use the SDK's waitForSettlement().

Polling

POST /api/get-unlock-status

Request:

{
  "invoice_ids": [42]
}

Response:

{
  "unlocked": { "42": true },
  "statuses": {
    "42": {
      "unlocked": true,
      "status": "key_released",
      "failure_reason": null
    }
  }
}

Polling Strategy

Every 3–5 seconds
Exponential backoff after 2 minutes
Stop after expiry
Check balance for fee

Polling with Backoff (JavaScript)

async function pollForPayment(invoiceId, apiKey, expiresAt) {
  const BASE_URL = "https://hypawave.com";
  let delay = 3000;            // start at 3s
  const MAX_DELAY = 30000;     // cap at 30s
  const BACKOFF_AFTER = 2 * 60 * 1000; // backoff after 2 min
  const start = Date.now();

  while (Date.now() < new Date(expiresAt).getTime()) {
    const res = await fetch(BASE_URL + "/api/get-unlock-status", {
      method: "POST",
      headers: {
        "Authorization": "Bearer " + apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ invoice_ids: [invoiceId] }),
    });

    const data = await res.json();
    const status = data.statuses?.[invoiceId];

    if (status?.unlocked) {
      return status; // { unlocked, status, failure_reason }
    }

    // exponential backoff after 2 minutes
    if (Date.now() - start > BACKOFF_AFTER) {
      delay = Math.min(delay * 1.5, MAX_DELAY);
    }

    await new Promise(r => setTimeout(r, delay));
  }

  throw new Error("Payment request expired without settlement");
}

Key Retrieval

GET /api/get-key?invoice_file_id=...

Response:

{
  "encryption_key": "base64",
  "iv_hex": "hex"
}

One-time atomic release. 403 key_already_released on repeat. Payment gates access, not identity.

Note: Push webhooks not yet supported, contact for early access.

File Attachments (Advanced)

Why

Enable agents to exchange data as payment-gated transactions. Agent-to-agent commerce foundation.

What Can Be Attached

Any data — files, links, structured metadata, API responses. Links encoded as bytes and encrypted like files.

Flow

Encrypt locally (AES-256-GCM)
Upload encrypted blob
POST /api/store-invoice-file
POST /api/store-file-key
GET /api/get-key after payment

Auth

Same Bearer token, no CSRF for agents.

Endpoints

Endpoint	Purpose
`POST /api/store-invoice-file`	Store file metadata
`POST /api/store-file-key`	Store wrapped encryption key
`POST /api/get-invoice-files`	List files for an invoice (Bearer, session, or `access_token` in body)
`POST /api/generate-download-url`	Generate presigned download URL for encrypted file (5 min expiry)
`POST /api/get-unlock-status`	Poll unlock status
`GET /api/get-key`	Retrieve decryption key (Bearer, session, or `access_token` query param)

Ownership Rules

Only creator can store metadata/keys
Agents list only their own files
Key retrieval requires: (1) valid invoice_file_id, (2) settlement proof recorded for the parent invoice, (3) key not previously claimed. All three conditions must be met. Payment is the authorization — no identity check.
Keys released once via atomic claim

Note: Hypawave never sees plaintext, stores opaque blobs and wrapped keys.

Test vs Live Mode

Mode	Prefix	Description
Test	`sk_test_...`	For dev/testing, same API, marked in audit logs
Live	`sk_live_...`	For production, real Lightning payments

Both modes hit same endpoints and create real DB records. Test mode filters in audit logs.

Rate Limits

Rate limits are per identity (not per IP). Rate limits do not affect settlement or unlock logic — only API request throughput.

Resource	Limit
API requests	30/minute
Key creation (per IP)	5/hour
Key creation (per identity)	3/hour
Payment requests	50/24 hours

Returns 429 with rate_limit_exceeded.

Error Reference

Auth Errors

Error Code	HTTP Status
`missing_auth`	401
`invalid_key_format`	401
`invalid_api_key`	401
`api_key_revoked`	401

Payment Request Errors

Error Code	HTTP Status
`validation_error`	400
`amount_below_minimum`	400
`amount_above_maximum`	400
`invalid_payment_destination`	400
`invalid_payment_destination_domain`	400
`invalid_currency`	400
`negative_balance`	402 — Returned when attempting to create a new payment request while balance < 0. Does not affect settlement or unlock of already settled payments.
`daily_limit`	429
`rate_limit_exceeded`	429
`price_feed_unavailable`	502
`circuit_breaker`	503

Topup Errors

Error Code	HTTP Status
`topup_not_needed`	400 — Balance is already ≥ 0. No fees to settle.

Error Recovery

Scenario	What Happens
Payment request expired	Closes, nothing charged, create new
Lightning payment failed mid-route	Atomic, funds returned, request stays open
Payment confirmed but files not unlocking	Delay in reconciliation, poll `get-unlock-status`, resolves within seconds
API 500 or timeout	Not always safe to retry blindly. Creating request not idempotent. Topup is retry-safe — the server returns the existing pending invoice if one exists; credit is capped at exactly the amount owed.
Balance went negative	Expected — service fee deducted post-settlement. Settled payments still deliver. Call `POST /api/agent/topup` (empty body) before creating new — server mints a bolt11 for exactly `-available_sats`.
Key retrieval failed	One-time, may be marked released. Contact support.

General rule: Query state rather than retry blindly.

Idempotency

Operation	Safety	Notes
Create payment request	Caution	Each call creates new. Retry only if no response. This endpoint does not support idempotency keys. Duplicate submissions create duplicate invoices.
Top up	Safe	Empty body. Returns existing pending invoice on retry (`reused: true`). Credit capped at exact amount owed; overpayments recorded separately.
Check balance	Always safe	Read-only
Poll unlock status	Always safe	Read-only
Get decryption key	One-time	Store on first success.
Store file metadata	Caution	May create duplicates
Store file key	Safe	Keyed by file ID, overwrites cleanly

Best Practices

Client-side deduplication for mutations
Retry freely for reads
Persist key immediately
Query state before retrying 500s

Code Examples

Create Payment Request (curl)

curl -X POST https://hypawave.com/api/agent/create-invoice \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5.00,
    "currency": "USD",
    "payment_destination": "you@wallet.com",
    "client_email": "client@example.com",
    "client_first_name": "Jane",
    "client_last_name": "Doe",
    "creator_first_name": "Agent",
    "creator_last_name": "Smith",
    "description": "Data export – Q4 report",
    "expires_in": "24h"
  }'

Check Balance (curl)

curl https://hypawave.com/api/agent/balance?currency=USD \
  -H "Authorization: Bearer sk_live_..."

Create Payment Request (JavaScript)

const res = await fetch("/api/agent/create-invoice", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk_live_...",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    amount: 5.00,
    currency: "USD",
    payment_destination: "you@wallet.com",
    client_email: "client@example.com",
    client_first_name: "Jane",
    client_last_name: "Doe",
    creator_first_name: "Agent",
    creator_last_name: "Smith",
    description: "Data export – Q4 report",
    expires_in: "24h"
  })
});

const data = await res.json();
console.log(data.payment_url);

Settle Outstanding Fees (curl)

curl -X POST https://hypawave.com/api/agent/topup \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{}'
# Returns a bolt11 for exactly -available_sats.
# If balance ≥ 0, returns 400 topup_not_needed.

API Reference

Complete API reference for all Hypawave Agent API endpoints. For TypeScript/JavaScript, install the official SDK: npm install @hypawave/sdk. For other languages, use the OpenAPI 3.0.3 specification with tools like openapi-generator to auto-generate typed clients.

Base URL

https://hypawave.com

Authentication

All agent endpoints require a Bearer token. Settlement endpoints (get-unlock-status, get-key) support Bearer token or session cookie via dual-auth.

Authorization: Bearer sk_live_...

Payment Requests

POST /api/agent/create-invoice

Creates a new payment request. The fiat amount is converted to satoshis at the current BTC price and locked at creation time. Returns a payment URL for settlement. Once the Lightning payment confirms, any attached encrypted data is deterministically unlocked.

State machine: created → settled → unlocked | expired

Required fields

Field	Type	Description
`client_email`	string	Payer email
`client_first_name`	string	Payer first name
`client_last_name`	string	Payer last name
`amount`	number	Configurable limits — see `GET /api/public-settings`
`due_date`	string	YYYY-MM-DD format

Optional fields

Field	Type	Description
`currency`	string	Default: USD (40+ supported)
`description`	string	Memo or note
`company_name`	string	Payer company
`expires_in`	string	1h, 24h, 7d, or null
`payment_destination`	string	Override default Lightning address (see note below)
`creator_first_name`	string	Your display name
`creator_last_name`	string	Your last name
`creator_company_name`	string	Your company
`creator_fingerprint`	string	Client fingerprint

Sender fields (creator_*) default to the profile you set during API key creation. Provide them to override for a specific invoice — your saved profile will be updated with the new values.

payment_destination defaults to the API key owner's saved lightning_address. Override per-call for marketplace routing (different seller per invoice), multi-wallet owners, or pass-through flows (agent facilitating for a third-party creator). Funds always flow wallet-to-wallet — Hypawave never takes custody.

Response fields (201)

Field	Type	Description
`ok`	boolean	Always true on success
`invoice_id`	integer	Unique request ID
`access_token`	string	Payment page token
`payment_url`	string	Browser-based payment page
`instructions_url`	string	Payer agent instructions
`stream_id`	uuid	Hypawave stream ID
`amount`	number	Amount in currency
`currency`	string	Currency code
`sats`	integer	Locked sats amount
`btc_usd_rate`	number	Locked BTC price
`expires_at`	datetime\|null	Expiration time

Error responses

Code	Error	Description
400	`validation_error`	Invalid input
401	`invalid_api_key`	Bad or missing auth
402	`negative_balance`	Outstanding fees block new requests
429	`rate_limit_exceeded`	30/min per identity
502	`price_feed_unavailable`	BTC price feed down

Balance

GET /api/agent/balance

Returns the current balance in satoshis and fiat equivalent. A negative balance means settlement fees are outstanding — this blocks new payment request creation but never blocks delivery or key release.

Query parameters

Field	Type	Description
`currency`	string	Optional, default USD

Response (200)

Field	Type	Description
`available_sats`	integer	Balance in sats (can be negative)
`fiat_equivalent`	number	Fiat value at current price
`currency`	string	Currency code
`btc_price`	number	Current BTC price
`has_outstanding_fee`	boolean	True if balance is negative

POST /api/agent/topup

Creates a Lightning invoice that clears outstanding settlement fees and restores the ability to create new payment requests. Fee-settlement only — the server mints a bolt11 for exactly the amount owed; callers cannot specify an amount. Returns 400 topup_not_needed when balance is already at or above zero.

Request body

Empty. Any fields are ignored.

Response (200)

Field	Type	Description
`ok`	boolean	Always true on success
`bolt11`	string	BOLT11 Lightning invoice to pay
`payment_hash`	string	Payment hash for tracking
`amount_sats`	integer	Amount in satoshis
`expires_at`	datetime	Invoice expiration

Key Management

These endpoints require a logged-in browser session (session cookie + CSRF token). They cannot be called with a Bearer token.

POST /api/agent/create-key

Create a new API key. The raw key is returned only once — store it immediately.

Request

Field	Type	Description
`mode`	string	"test" or "live" (required)
`label`	string	Optional label (max 100 chars)

Response (201)

Field	Type	Description
`key`	string	Full API key (shown once)
`prefix`	string	Key prefix for identification
`mode`	string	test or live

Rate limit: 5/hour per IP, 3/hour per identity

POST /api/agent/revoke-key

Revoke an API key. Takes effect immediately — all subsequent requests with this key will be rejected.

Field	Type	Description
`key_id`	string	UUID of the key to revoke (required)
`reason`	string	Optional reason

GET /api/agent/list-keys

List all API keys for your identity. Returns prefixes and metadata — never raw keys.

Settlement

POST /api/get-unlock-status

Checks whether payment requests have reached settlement and triggered deterministic unlock. Settlement confirmation is unconditional — once payment confirms, unlock is guaranteed regardless of creator balance or platform state.

Request

Field	Type	Description
`invoice_ids`	integer[]	Payment request IDs to check (max 25)

Response (200)

Field	Type	Description
`unlocked`	object	Map of ID to boolean unlock status
`statuses`	object	Detailed status per request (unlocked, status, failure_reason, settlement_proof)
`statuses[id].settlement_proof`	object\|null	Cryptographic proof: payment_hash, preimage (SHA-256 proof of payment), settled_at

Auth: Bearer token or session cookie. Rate limit: 30/min per IP

GET /api/get-key?invoice_file_id=...

Retrieves the AES-256-GCM encryption key and IV for a settled payment request's attached file. No authentication required — access is gated entirely by settlement proof. Payment is the authorization.

Query parameter

Field	Type	Description
`invoice_file_id`	uuid	File UUID (after settlement)

Response (200)

Field	Type	Description
`encryption_key`	string	Base64-encoded AES-256-GCM key
`iv_hex`	string	Hex-encoded initialization vector

Error responses

Code	Error	Description
400	`missing_file_id`	No file ID provided
403	`not_paid`	Payment not yet settled
403	`key_already_released`	Key was already claimed (atomic, one-time)
404	`file_not_found`	Invalid file UUID
410	`invoice_expired`	Past expiration + grace period

No auth required. Rate limit: 30/min per IP

OpenAPI Specification

For TypeScript, use the official SDK: npm install @hypawave/sdk. For other languages, the raw OpenAPI 3.0.3 spec is available at /.well-known/openapi.json for use with openapi-generator.

Hypawave Agent API Documentation