@openreceive/http

Add Bitcoin Lightning checkout to your Node.js application while keeping your orders, prices, and fulfillment in your own code. This package provides the Web Request/Response handler and payment repository used by the Express, Fastify, and Next.js adapters, with payment attempts stored in your existing database.

OpenReceive supports optional swaps from USDT, USDC, SOL, and ETH through a configured swap provider. The provider converts the payment to BTC over Lightning, which settles into the merchant's connected wallet. Available assets and networks depend on the provider; swaps are optional.

Install

This package is ESM-only and requires Node >= 22.

npm install @openreceive/http

Start with the integration quickstart and the payment storage guide.

Connect your application

For Express, Fastify, or Next.js, start with the matching adapter; each uses this handler and repository. For a custom Node.js host, compose service, authorize, and the host integration. Amounts come from your server, and a payment attempt is committed before checkout instructions are returned.

createHost({ db, amountFor, onPaid }) builds the host integration on the library-owned payment repository inside the host application's existing database (pg, mysql2, node:sqlite, better-sqlite3, or a custom adapter). The library owns attempt selection, per-reference commit locking, write-once settlement with first-attempt-only fulfillment, and the pending → settled | expired | failed | attention reconciliation state machine (attention reads as pending on the wire; operators see it only in openreceive_payments.status). onPaid is the settlement hook in both modes: with db it receives PaymentSettlement (reference plus a query that runs inside the settlement transaction); with a custom repository it receives SettlementEvent<Transaction> (reference, paymentHash, paidAt, details, and transaction). The repository awaits fulfillment before commit; failure rolls back both payment and host writes. On Cloudflare Workers, which cannot open a Postgres connection to Supabase, createHost({ supabase: { url, key }, amountFor }) keeps the same rows in Supabase over its HTTPS API, and the host's SQL function openreceive_on_paid fulfills inside the settlement transaction (Supabase over HTTPS). Settlement piggybacks on mounted routes by default through the durable openreceive_meta gate (opportunisticReconcile: false disables, { minIntervalSeconds } tunes); startNotificationWorker is the optional listen-plus-reconcile worker process. A custom PaymentRepository via the payments option is the advanced escape hatch.

It reuses one live attempt per rail, permits new attempts after expiry, and verifies the payment_hash selector belongs to the authorized order. Committed retries use the stored safe checkout snapshot. swapData is never serialized into an HTTP response. OpenReceive never requires a separate database or Redis.

This is the home of the full host-integration surface. The framework adapters (@openreceive/express, @openreceive/fastify, @openreceive/next) re-export only a curated slice — the handler/stack factories, error surface, notification worker, and their options/context/hook types — so anything deeper imports from here (npm run check:public-api pins both surfaces):

• Handler and stack: createHttpHandler, createStack, their options types, and mapHostRouteError / HttpError / HostError.
• Host integration: createHost, the SQL repository (createSqlPayments, paymentsSchemaSql), the PaymentRepository contract types, and the settlement hook contexts above.
• Reconciliation: maybeReconcilePayments (the durable gate pass), reconcileHostPayments, startReconciler, and the shared constants (OPENRECEIVE_ATTEMPT_EXPIRY_GRACE_SECONDS, OPENRECEIVE_RECONCILE_BATCH_SIZE, scan bounds).
• Rate limiting: createIpRateLimit, resolveClientIp, and IpRateLimitConfig behind the handler's rateLimiting / rateLimitHook options.
• Generated wire types: the snake_case Wire* request/response body types (WireCheckout, WireCreateCheckoutRequest, WirePaymentCheck, WireError, …), generated from the OpenAPI contract. The adapters re-export these too.

See the API reference and HTTP contract.

Agent skills

Run npx openreceive skills install from your application after installing an OpenReceive server adapter. The offline copy ships in @openreceive/node, a server-adapter dependency. For a frontend-only project, use npx skills add OpenReceive/openreceive. See agent setup. The bundled installers write to .agents/skills/; use --dir .claude/skills for Claude Code. They replace only integrate-openreceive and debug-openreceive-payment, preserving unrelated skills.