@openreceive/http 0.4.3 → 0.4.6

package/README.md

@@ -1,13 +1,35 @@
 # @openreceive/http
 
-Framework-neutral receive-checkout handler. Its normal form requires `service`,
-`authorize`, and the `host` integration. Create bodies never accept payer
-amounts; the host's `amountFor` hook is the only price authority, and the
-commit hook appends a payment-attempt row before the invoice is returned.
+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.
 
-`createHost({ db, amountFor, onPaid })` builds that
+```sh
+npm install @openreceive/http
+```
+
+Start with the [integration quickstart](https://github.com/openreceive/openreceive/blob/master/docs/guides/quickstart-node.md)
+and the [payment storage guide](https://github.com/openreceive/openreceive/blob/master/docs/guides/storage.md).
+
+## 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, node:sqlite, better-sqlite3, or a custom
 adapter). The library owns attempt selection, per-reference commit locking,
@@ -54,4 +76,5 @@ here (`npm run check:public-api` pins both surfaces):
   `WirePaymentCheck`, `WireError`, …), generated from the
   OpenAPI contract. The adapters re-export these too.
 
-See the root README, the storage guide, and the OpenAPI contract.
+See the [API reference](https://github.com/openreceive/openreceive/blob/master/docs/guides/api-reference.md)
+and [HTTP contract](https://github.com/openreceive/openreceive/blob/master/spec/openapi/openreceive-http.v1.yaml).

package/dist/{adapter-surface-DA8w4Sxj.d.ts → adapter-surface-DHngkTKQ.d.ts}

@@ -110,12 +110,6 @@ declare function jsonResponse(status: number, body: unknown, requestId: string,
  */
 declare function errorResponse(error: unknown, requestId: string): Response;
 
-/**
- * Seconds past an attempt's expiry during which reconciliation still scans for a
- * settlement before closing the attempt. Covers clock skew and wallets that
- * accept a payment moments after nominal invoice expiry.
- */
-declare const OPENRECEIVE_ATTEMPT_EXPIRY_GRACE_SECONDS: 900;
 /**
  * Lifecycle of one payment attempt: {@link TransactionSettlementStatus} plus
  * `attention`. `pending` attempts participate in reconciliation; every other
@@ -741,4 +735,4 @@ declare function createStack(options: CreateStackOptions): Stack;
  */
 declare function isStackOptions(options: CreateHttpHandlerOptions | CreateStackOptions): options is CreateStackOptions;
 
-export { errorResponse as $, type AttemptStatus as A, type SettlementEvent as B, type CheckoutCreatedHook as C, type SettlementEventHook as D, type SettlementRecord as E, type SqlClient as F, type SqlDatabase as G, type Host as H, type IpRateLimitConfig as I, type SqlPaymentRepository as J, type SqlPaymentsOptions as K, type SqlQuery as L, type Stack as M, type NotificationListener as N, OPENRECEIVE_ATTEMPT_EXPIRY_GRACE_SECONDS as O, type PaymentInsert as P, type StackStorage as Q, type ReconcilableAttempt as R, type SqlAdapter as S, type StackWallet as T, createHost as U, createHttpHandler as V, createIpRateLimit as W, createProxyRateLimitingConfig as X, createRequestId as Y, createSqlPayments as Z, createStack as _, type Authorize as a, hostError as a0, isServiceErrorShape as a1, isStackOptions as a2, jsonResponse as a3, mapHostRouteError as a4, paymentsSchemaSql as a5, resolveClientIp as a6, startNotificationListener as a7, startNotificationWorker as a8, type AuthorizeAction as b, type AuthorizeContext as c, type AuthorizeResource as d, type CheckoutCreatedInput as e, type CreateHostDbOptions as f, type CreateHostOptions as g, type CreateHostRepositoryOptions as h, type CreateHttpHandlerOptions as i, type CreateStackOptions as j, type HostCheckoutPrice as k, HostError as l, HttpError as m, type HttpHandler as n, type NotificationWorker as o, OPENRECEIVE_RECONCILE_BATCH_SIZE as p, type PaymentRecord as q, type PaymentRepository as r, type PaymentSettlement as s, type PaymentSettlementHook as t, type RateLimit as u, type ReconciliationTransition as v, type ResolveCheckoutContext as w, type ResolveCheckoutHook as x, type ResolvedHostCheckout as y, type ServiceErrorShape as z };
+export { hostError as $, type AttemptStatus as A, type SettlementEventHook as B, type CheckoutCreatedHook as C, type SettlementRecord as D, type SqlClient as E, type SqlDatabase as F, type SqlPaymentRepository as G, type Host as H, type IpRateLimitConfig as I, type SqlPaymentsOptions as J, type SqlQuery as K, type Stack as L, type StackStorage as M, type NotificationListener as N, OPENRECEIVE_RECONCILE_BATCH_SIZE as O, type PaymentInsert as P, type StackWallet as Q, type ReconcilableAttempt as R, type SqlAdapter as S, createHost as T, createHttpHandler as U, createIpRateLimit as V, createProxyRateLimitingConfig as W, createRequestId as X, createSqlPayments as Y, createStack as Z, errorResponse as _, type Authorize as a, isServiceErrorShape as a0, isStackOptions as a1, jsonResponse as a2, mapHostRouteError as a3, paymentsSchemaSql as a4, resolveClientIp as a5, startNotificationListener as a6, startNotificationWorker as a7, type AuthorizeAction as b, type AuthorizeContext as c, type AuthorizeResource as d, type CheckoutCreatedInput as e, type CreateHostDbOptions as f, type CreateHostOptions as g, type CreateHostRepositoryOptions as h, type CreateHttpHandlerOptions as i, type CreateStackOptions as j, type HostCheckoutPrice as k, HostError as l, HttpError as m, type HttpHandler as n, type NotificationWorker as o, type PaymentRecord as p, type PaymentRepository as q, type PaymentSettlement as r, type PaymentSettlementHook as s, type RateLimit as t, type ReconciliationTransition as u, type ResolveCheckoutContext as v, type ResolveCheckoutHook as w, type ResolvedHostCheckout as x, type ServiceErrorShape as y, type SettlementEvent as z };

package/dist/adapter-surface.d.ts

@@ -1,3 +1,3 @@
 export { Checkout, CreateCheckoutAmount, OpenReceive, PaymentCheck, SwapCheckout } from '@openreceive/node';
-export { a as Authorize, b as AuthorizeAction, c as AuthorizeContext, d as AuthorizeResource, C as CheckoutCreatedHook, e as CheckoutCreatedInput, i as CreateHttpHandlerOptions, j as CreateStackOptions, H as Host, l as HostError, m as HttpError, n as HttpHandler, I as IpRateLimitConfig, o as NotificationWorker, r as PaymentRepository, s as PaymentSettlement, t as PaymentSettlementHook, u as RateLimit, w as ResolveCheckoutContext, x as ResolveCheckoutHook, y as ResolvedHostCheckout, z as ServiceErrorShape, B as SettlementEvent, D as SettlementEventHook, M as Stack, Q as StackStorage, T as StackWallet, V as createHttpHandler, _ as createStack, a0 as hostError, a1 as isServiceErrorShape, a4 as mapHostRouteError, a8 as startNotificationWorker } from './adapter-surface-DA8w4Sxj.js';
+export { a as Authorize, b as AuthorizeAction, c as AuthorizeContext, d as AuthorizeResource, C as CheckoutCreatedHook, e as CheckoutCreatedInput, i as CreateHttpHandlerOptions, j as CreateStackOptions, H as Host, l as HostError, m as HttpError, n as HttpHandler, I as IpRateLimitConfig, o as NotificationWorker, q as PaymentRepository, r as PaymentSettlement, s as PaymentSettlementHook, t as RateLimit, v as ResolveCheckoutContext, w as ResolveCheckoutHook, x as ResolvedHostCheckout, y as ServiceErrorShape, z as SettlementEvent, B as SettlementEventHook, L as Stack, M as StackStorage, Q as StackWallet, U as createHttpHandler, Z as createStack, $ as hostError, a0 as isServiceErrorShape, a3 as mapHostRouteError, a7 as startNotificationWorker } from './adapter-surface-DHngkTKQ.js';
 import '@openreceive/core';

package/dist/adapter-surface.js

@@ -7,7 +7,7 @@ import {
   isServiceErrorShape,
   mapHostRouteError,
   startNotificationWorker
-} from "./chunk-YASZ4HDW.js";
+} from "./chunk-TJY2HBVU.js";
 export {
   HostError,
   HttpError,

package/dist/{chunk-YASZ4HDW.js → chunk-TJY2HBVU.js}

@@ -231,10 +231,10 @@ import { sanitizeEvent } from "@openreceive/node";
 
 // src/payment-repository.ts
 import {
+  OPENRECEIVE_ATTEMPT_EXPIRY_GRACE_SECONDS,
   unixSeconds
 } from "@openreceive/core";
 var OPENRECEIVE_ATTEMPT_REUSE_BUFFER_SECONDS = 60;
-var OPENRECEIVE_ATTEMPT_EXPIRY_GRACE_SECONDS = 900;
 function isReusablePaymentAttempt(expiresAt, now = unixSeconds()) {
   return expiresAt - now > OPENRECEIVE_ATTEMPT_REUSE_BUFFER_SECONDS;
 }

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 import { OpenReceive, PaymentCheck } from '@openreceive/node';
 export { Checkout, CreateCheckoutAmount, OpenReceive, PaymentCheck, SwapCheckout } from '@openreceive/node';
-import { H as Host, R as ReconcilableAttempt, S as SqlAdapter } from './adapter-surface-DA8w4Sxj.js';
-export { A as AttemptStatus, a as Authorize, b as AuthorizeAction, c as AuthorizeContext, d as AuthorizeResource, C as CheckoutCreatedHook, e as CheckoutCreatedInput, f as CreateHostDbOptions, g as CreateHostOptions, h as CreateHostRepositoryOptions, i as CreateHttpHandlerOptions, j as CreateStackOptions, k as HostCheckoutPrice, l as HostError, m as HttpError, n as HttpHandler, I as IpRateLimitConfig, N as NotificationListener, o as NotificationWorker, O as OPENRECEIVE_ATTEMPT_EXPIRY_GRACE_SECONDS, p as OPENRECEIVE_RECONCILE_BATCH_SIZE, P as PaymentInsert, q as PaymentRecord, r as PaymentRepository, s as PaymentSettlement, t as PaymentSettlementHook, u as RateLimit, v as ReconciliationTransition, w as ResolveCheckoutContext, x as ResolveCheckoutHook, y as ResolvedHostCheckout, z as ServiceErrorShape, B as SettlementEvent, D as SettlementEventHook, E as SettlementRecord, F as SqlClient, G as SqlDatabase, J as SqlPaymentRepository, K as SqlPaymentsOptions, L as SqlQuery, M as Stack, Q as StackStorage, T as StackWallet, U as createHost, V as createHttpHandler, W as createIpRateLimit, X as createProxyRateLimitingConfig, Y as createRequestId, Z as createSqlPayments, _ as createStack, $ as errorResponse, a0 as hostError, a1 as isServiceErrorShape, a2 as isStackOptions, a3 as jsonResponse, a4 as mapHostRouteError, a5 as paymentsSchemaSql, a6 as resolveClientIp, a7 as startNotificationListener, a8 as startNotificationWorker } from './adapter-surface-DA8w4Sxj.js';
-export { OPENRECEIVE_PAYMENTS_SCHEMA_VERSION } from '@openreceive/core';
+import { H as Host, R as ReconcilableAttempt, S as SqlAdapter } from './adapter-surface-DHngkTKQ.js';
+export { A as AttemptStatus, a as Authorize, b as AuthorizeAction, c as AuthorizeContext, d as AuthorizeResource, C as CheckoutCreatedHook, e as CheckoutCreatedInput, f as CreateHostDbOptions, g as CreateHostOptions, h as CreateHostRepositoryOptions, i as CreateHttpHandlerOptions, j as CreateStackOptions, k as HostCheckoutPrice, l as HostError, m as HttpError, n as HttpHandler, I as IpRateLimitConfig, N as NotificationListener, o as NotificationWorker, O as OPENRECEIVE_RECONCILE_BATCH_SIZE, P as PaymentInsert, p as PaymentRecord, q as PaymentRepository, r as PaymentSettlement, s as PaymentSettlementHook, t as RateLimit, u as ReconciliationTransition, v as ResolveCheckoutContext, w as ResolveCheckoutHook, x as ResolvedHostCheckout, y as ServiceErrorShape, z as SettlementEvent, B as SettlementEventHook, D as SettlementRecord, E as SqlClient, F as SqlDatabase, G as SqlPaymentRepository, J as SqlPaymentsOptions, K as SqlQuery, L as Stack, M as StackStorage, Q as StackWallet, T as createHost, U as createHttpHandler, V as createIpRateLimit, W as createProxyRateLimitingConfig, X as createRequestId, Y as createSqlPayments, Z as createStack, _ as errorResponse, $ as hostError, a0 as isServiceErrorShape, a1 as isStackOptions, a2 as jsonResponse, a3 as mapHostRouteError, a4 as paymentsSchemaSql, a5 as resolveClientIp, a6 as startNotificationListener, a7 as startNotificationWorker } from './adapter-surface-DHngkTKQ.js';
+export { OPENRECEIVE_ATTEMPT_EXPIRY_GRACE_SECONDS, OPENRECEIVE_PAYMENTS_SCHEMA_VERSION } from '@openreceive/core';
 
 /** The pieces of a framework request the bridge needs, framework-agnostic. */
 interface NodeRequestParts {

package/dist/index.js

@@ -34,7 +34,7 @@ import {
   startReconciler,
   typeOrmDb,
   webRequest
-} from "./chunk-YASZ4HDW.js";
+} from "./chunk-TJY2HBVU.js";
 export {
   HostError,
   HttpError,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@openreceive/http",
-  "version": "0.4.3",
-  "description": "Framework-neutral (Web Request/Response) HTTP handler for OpenReceive checkout that builds on @openreceive/node and requires its Node runtime: request routing, host integration, and payment-attempt persistence.",
+  "version": "0.4.6",
+  "description": "Node.js HTTP routes and payment storage for Bitcoin Lightning checkout, with optional USDT, USDC, SOL and ETH swaps.",
   "keywords": [
     "bitcoin",
     "lightning",
@@ -17,8 +17,8 @@
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "dependencies": {
-    "@openreceive/core": "0.4.3",
-    "@openreceive/node": "0.4.3"
+    "@openreceive/core": "0.4.6",
+    "@openreceive/node": "0.4.6"
   },
   "exports": {
     ".": {

package/skills/integrate-openreceive/SKILL.md

@@ -5,7 +5,8 @@ description: >
   Use when adding Bitcoin, Lightning, or crypto checkout to a Node.js, Express,
   Fastify, Next.js, Rails, React, Vue, Svelte, Angular, or plain-HTML
   application with OpenReceive (the @openreceive/* npm packages or the
-  openreceive-rails gem).
+  openreceive-rails gem), or when connecting a BTCPay Server store to a
+  receive-only NWC wallet with the OpenReceive plugin.
 license: MIT
 ---
 
@@ -23,15 +24,25 @@ code** (`NWC_URI`).
 1. Identify the server stack of the application you are in.
 2. Open the matching reference — it is complete (quickstart inlined) and needs
    no network access:
-   - Node (Express / Fastify / Next.js): [references/node.md](references/node.md)
+   - Node, Express: [references/node.md](references/node.md)
+   - Node, Fastify: [references/fastify.md](references/fastify.md)
+   - Node, Next.js App Router: [references/next.md](references/next.md)
    - Rails: [references/rails.md](references/rails.md)
+   - Django: [references/django.md](references/django.md)
+   - Laravel: [references/laravel.md](references/laravel.md)
+   - WordPress + WooCommerce: [references/woocommerce.md](references/woocommerce.md) — the packaged gateway and merchant settings.
+   - BTCPay Server: [references/btcpay.md](references/btcpay.md) — a plugin,
+     configured in BTCPay's store UI or Greenfield API; no application code,
+     no npm packages, no gem. The rest of this file is about the library.
 3. Follow its **Step 0** first: confirm `NWC_URI` is set in the server
    environment before writing code. Never print the value; never invent a
    placeholder.
 
-Install (Node): `npm install @openreceive/express @openreceive/react` — swap
-the adapter (`fastify`, `next`) and UI package (`vue`, `svelte`, `angular`,
-`elements`) for the stack. Install (Rails): `bundle add openreceive-rails`.
+Install, per adapter — Express: `npm install @openreceive/express @openreceive/react`;
+Fastify: `npm install @openreceive/fastify @openreceive/react`; Next.js:
+`npm install @openreceive/next @openreceive/react`. Swap the UI package (`vue`,
+`svelte`, `angular`, `elements`) for the frontend the app already has. Install
+(Rails): `bundle add openreceive-rails`.
 
 ## The three server objects
 

package/skills/integrate-openreceive/references/btcpay.md

@@ -0,0 +1,193 @@
+# OpenReceive agent directions (BTCPay Server)
+
+These directions describe OpenReceive 0.4.6.
+
+Connect a BTCPay Server store to a receive-only NWC wallet with the OpenReceive
+plugin, and optionally let payers pay BTCPay invoices with USDT, USDC, ETH or
+SOL. You do not need a copy of the OpenReceive source, and there is no
+application code to write: the plugin is configured through BTCPay's store UI
+or its Greenfield API, and the quickstart is appended to this file in full.
+
+This is the BTCPay plugin, not the Node or Rails library. Do not install
+`@openreceive/*` packages or the `openreceive-rails` gem into a BTCPay
+deployment, do not add `openreceive_payments` tables, and do not mount
+OpenReceive HTTP routes. BTCPay's invoices, checkout, webhooks and Greenfield
+API are the host; the plugin only supplies the Lightning backend and the swap
+rail.
+
+## What the plugin is
+
+A BTCPay Server plugin (`BTCPayServer.Plugins.OpenReceive`) that registers a
+Lightning connection-string handler for `type=openreceive;nwc=<NWC URI>`.
+Saving that string makes the NWC wallet the store's Lightning node: BTCPay
+mints every Lightning invoice in that wallet and its own `LightningListener`
+records the payments. The plugin never calls a NIP-47 `pay_*` method, so
+every send-side BTCPay feature (Lightning payouts, pull-payment refunds over
+Lightning, the send tab) is unavailable by design.
+
+The one required credential is a receive-only NWC code. A Lightning Swap
+Connect (LSC) code optionally adds server-side swaps: a provider order aimed at
+the invoice's existing BOLT11, tracked in the plugin's own table, with the
+refund path on the same checkout screen.
+
+## Step 0 — check the deployment before you change anything
+
+1. Confirm the BTCPay Server version is 2.4.2 or later (Server Settings →
+   About, or `GET /api/v1/server/info`). The plugin declares that minimum and
+   BTCPay refuses to load it below.
+2. Check whether the plugin is installed (Server Settings → Plugins, or the
+   store navigation shows an "OpenReceive" entry). If not, install it from the
+   BTCPay plugin directory (Server Settings → Plugins, search "OpenReceive"),
+   as the quickstart says; do not invent an installer command.
+3. Check whether the store already has an OpenReceive connection:
+   `GET /api/v1/stores/{storeId}/openreceive/settings` returns
+   `lightningNodeIsOpenReceive`. If true, the wallet step is done — go to
+   swaps only if the user wants them.
+4. If no receive-only NWC code is available, stop and tell the user exactly
+   what to create:
+
+   > OpenReceive cannot mint an invoice without a receive-only NWC code. Get
+   > one at https://openreceive.org/get_a_nwc_code_to_receive_payments and
+   > paste it into Store → OpenReceive → Test connection, or hand it to me and
+   > I will set it through the Greenfield API.
+
+   Never print, log or echo the code; report only whether it is set. Never
+   paste a bare `nostr+walletconnect://` string into BTCPay's Lightning node
+   screen — that form is claimed by the Nostr plugin, without the receive-only
+   guard.
+5. If the user wants altcoin payments, ask for an LSC code from
+   https://openreceive.org/set_up_swap_provider. Do not wait for it: the
+   wallet works without it, and swaps switch on later with one settings change.
+
+Only then start the quickstart.
+
+## Non-negotiables
+
+- The connection string is `type=openreceive;nwc=<NWC URI>[;allow-spend=true]`
+  and nothing else. Set it through the setup page or
+  `PUT /api/v1/stores/{storeId}/openreceive/settings` with `nwcUri`, never by
+  editing BTCPay's Lightning node screen by hand.
+- Receive-only is required. A code that advertises `pay_invoice` or another
+  spend method is refused on save. The override (`allowSpendCapableWallet`,
+  the checkbox on the setup page) is the user's explicit choice; never tick it
+  to make a save succeed.
+- The wallet's network must match BTCPay's. A mismatch is a refusal, not a
+  warning.
+- The wallet must grant `make_invoice` and `list_transactions`.
+  `lookup_invoice` is optional; do not ask the user for a code that grants it.
+- Swaps require the store's Lightning node to be the OpenReceive connection.
+  Enabling swaps on a store using the internal node is refused
+  (`wallet_required`).
+- Swaps set the store's invoice expiration to 60 minutes when it is shorter,
+  and the plugin refuses to create a swap on an invoice with less than the
+  provider's window left. Do not lower the expiration below 45 minutes on a
+  swap-enabled store.
+- Top-up (amountless) invoices are unsupported on this backend. Do not
+  configure a point of sale or payment link that relies on them with this
+  wallet.
+- Secrets stay server-side. The NWC code and LSC code live in BTCPay's
+  database like every other BTCPay credential; never copy them into
+  screenshots, tickets, browser code or logs. The provider's order token never
+  leaves the server.
+- BTCPay's `LightningListener` is the settlement authority. Provider
+  `completed` is not payment; only the wallet reporting the Lightning invoice
+  settled is. Do not build anything that fulfils on a provider state.
+- There is no merchant-initiated refund of a settled Lightning payment. A swap
+  refund is a payer reclaiming a deposit that never converted, and only from
+  the `refund_required` provider state.
+
+## Verifying
+
+Store → OpenReceive → **Run a health check** (the doctor page) runs every probe now: connection, preflight,
+notifications, last scan, provider reachability, invoice expiration, swaps
+needing attention. On a regtest machine, `packages/dotnet/docker/up.sh` then
+`e2e.sh` in the OpenReceive repository proves the whole path end to end, and
+that is the only situation where cloning the repository is the right move.
+
+## More documentation
+
+Fetch one when the moment comes. Each is raw markdown, so a plain GET is
+enough; drop the `.md` for the same page a person would read.
+
+- https://openreceive.org/guides/btcpay-reference.md — every setting, route, swap state, doctor probe and log event of the plugin
+- https://openreceive.org/guides/security.md — why receive-only is the only wallet credential
+- https://openreceive.org/guides/lightning-swap-connect.md — what an LSC code actually is
+- https://openreceive.org/guides/automated-swaps.md — provider states, and what turning swaps on commits a merchant to
+- https://openreceive.org/guides/swap-refunds.md — the refund states; the route back is BTCPay's own invoice checkout page here
+- https://openreceive.org/guides.md — the index, if what you need is not above
+
+Questions, or a problem with the plugin itself:
+https://openreceive.org/contact
+
+---
+
+## The quickstart, in full
+
+Inlined verbatim so this file needs no network access — follow it once Step 0
+passes. The page it comes from is https://openreceive.org/guides/quickstart-btcpay.
+
+## BTCPay Server quickstart
+
+Requires BTCPay Server ≥ 2.4.2.
+
+The OpenReceive plugin makes a receive-only NWC wallet the Lightning node of a
+BTCPay store. BTCPay mints every Lightning invoice in that wallet and records
+payments through its own settlement machinery. Optionally, payers can pay a
+BTCPay invoice with USDT, USDC, ETH or SOL through a Lightning Swap Connect
+provider; the swap settles into the same wallet. The store's internal node is
+never used.
+
+This is not the Node or Rails library. There are no hooks, no
+`openreceive_payments` table and no OpenReceive HTTP routes: BTCPay's
+invoices, checkout, webhooks and Greenfield API are the host.
+
+### 1. Prerequisites
+
+- A BTCPay Server, version 2.4.2 or later, on any network (mainnet, testnet,
+  signet, regtest). The wallet must be on the same network.
+- A receive-only NWC code for the wallet you want to receive into
+  ([get one here](https://openreceive.org/get_a_nwc_code_to_receive_payments)).
+  The code must grant `make_invoice` and `list_transactions` and must not
+  advertise any spend method. `lookup_invoice` is optional.
+- Optionally, a Lightning Swap Connect (LSC) code from a
+  [swap provider](https://openreceive.org/set_up_swap_provider), if payers
+  should be able to pay with USDT, USDC, ETH or SOL.
+
+### 2. Install the plugin
+
+In BTCPay, open **Server Settings → Plugins**, search the plugin directory
+for **OpenReceive**, click **Install**, and restart BTCPay when prompted.
+BTCPay creates the plugin's one table (`openreceive_swaps`, schema
+`BTCPayServer.Plugins.OpenReceive`) in its own Postgres at startup; nothing
+else is created.
+
+To build the plugin from source instead, follow
+[the .NET workspace README](https://github.com/OpenReceive/openreceive/blob/master/packages/dotnet/README.md).
+
+### 3. Connect the wallet
+
+Follow the plugin README's illustrated walkthrough:
+[OpenReceive for BTCPay Server](https://github.com/OpenReceive/openreceive/blob/master/packages/dotnet/BTCPayServer.Plugins.OpenReceive/README.md).
+It opens the **OpenReceive** page in the store's sidebar, saves the
+receive-only NWC code, optionally saves the LSC code to turn swaps on, and
+creates a first test invoice. There is nothing else to configure: you never
+open BTCPay's Lightning node screen, and the plugin never reads the internal
+node.
+
+Saving fails closed if the wallet advertises a spend method such as
+`pay_invoice`. Mint a receive-only code instead; the override for a wallet
+that cannot is a deliberate, logged choice. Swaps raise the store's invoice
+expiration to 60 minutes when it is shorter, because a swap needs at least 45
+minutes of invoice life.
+
+### 4. Check it
+
+**Run a health check** on the OpenReceive page runs every probe in place:
+the connection, the wallet preflight, payment notifications, the last wallet
+scan, the swap provider and its assets, the invoice expiration, and swaps
+that need a human. Each failing probe carries a fix link.
+
+Every setting, Greenfield route, swap state, log event and probe is in the
+[BTCPay plugin reference](https://openreceive.org/guides/btcpay-reference.md), including what is
+unsupported by design: every send-side feature, top-up invoices, and a bare
+`nostr+walletconnect://` string in BTCPay's Lightning node screen.