This is the full file; follow it from Step 0.

OpenReceive agent directions (NestJS)

# READ THIS FIRST: this file is 41 KB and a summary drops required steps. Download it whole:
curl -fsSL https://openreceive.org/agent-directions/nestjs/full.md
# Skip the download only if you already have all of it: pasted, read from disk or fetched raw.

Step 0 in brief (Step 0 below has the details):

These directions describe OpenReceive 0.4.24.

Add OpenReceive to a NestJS application — the app you are already working in, on Nest’s default Express platform. You do not need a copy of the OpenReceive source: the packages are on npm, and the quickstart is appended to this file in full, so you can do the whole integration without fetching anything. Prefer the published packages and the routes they mount — do not reimplement wallet RPC, settlement, or pricing, and do not rewrite the routes as a Nest controller.

Do not clone the OpenReceive repository into this app, and do not copy a demo’s models (ShopOrder, a signed-cookie visitor, an in-memory catalog) over tables that already exist. Find this application’s order, product, and user models — whatever they are actually named — and map the three hooks onto those.

Keep this application’s frontend framework, authentication and database. Pick the UI package that matches the frontend that is already here (@openreceive/react, /vue, /svelte, /angular, or /elements for server-rendered views and plain HTML) — do not add React to a Vue app or to Handlebars views. Reuse the app’s existing session/auth in authorize and its existing database handle (the TypeORM DataSource, the Prisma service) in storage.db.

What OpenReceive is

A payment library that runs inside YOUR server. It mounts HTTP routes in the application you are editing, issues Lightning invoices against a wallet the merchant already controls, and calls back into your code when one settles. There is no OpenReceive account and no API key, and OpenReceive never holds the funds — the sats land in the wallet the merchant connected.

The one required credential is a receive-only NWC code (Nostr Wallet Connect): a string from the merchant’s wallet that can create invoices and read their status, and cannot spend. A swap provider (an “LSC” code) optionally lets the payer send USDT, USDC, ETH or SOL instead, converted into that same Lightning payment. Step 0 collects those credentials from the user; you write three hooks — authorize, amountFor, onPaid; OpenReceive supplies invoices, polling, settlement and the checkout UI. It never owns orders, users, prices, or fulfillment.

Step 0 — ask for the two codes, one question at a time

Before anything else, check one file: the project’s .env, if it exists. grep -E '^(NWC_URI|LSC_URI_PRIMARY)=.' .env | cut -d= -f1 names the codes it sets without printing them. Check with that, here and after each write, not by reading the file, and never print the values. A code that is already set is not asked for again; if both are set, skip to step 5 (making the server load the file), then the quickstart.

On a hosted builder (v0, Vercel, Replit, Lovable), the user may say instead that both codes are already set as the project’s environment variables or secrets. Believe them: do not ask for the codes, do not write .env, and do not read or print the variables. Skip step 5’s file loading: the platform already puts them in process.env.

Otherwise your next action is a question to the user. Do not install packages, edit the app, write .env.example, or search anywhere else before asking it. Do not read deploy config (compose files, platform secrets), Docker containers, or process environments, and never run printenv. A new shop has neither code yet: hunting for one burns the turn and can leak other secrets into the transcript.

Two server-only URIs are needed before the quickstart:

The user never edits an environment file. They paste each code into the chat; you store it. Ask one question per message.

  1. First message — the NWC code, and nothing else. Ask for it and walk them through getting it:

    To receive payments I need a receive-only wallet code. In Rizful: open the menu, tap NWC, choose Receive-only NWC code, and tap Copy (https://openreceive.org/get_a_nwc_code_to_receive_payments). If you would rather run your own wallet, Alby Hub works too: Connections → Add Connection → Read Only. Paste the code here and I will store it.

    Do not mention .env, exports, or “tell me when it’s set”.

  2. When they paste it. If it does not start with nostr+walletconnect://, ask them to copy the receive-only code again. Otherwise write NWC_URI=<paste> into the project’s .env with your file-editing tool, creating the file if needed. Never write it with a shell command (echo, printf, a heredoc, python -c): the command line shows the code. Make sure .gitignore covers .env (and .dockerignore, if the app has one). Never echo the value, commit it, or put it in client code. Reply only that it is saved, then ask the next question.

  3. Second message — swaps. If the user asked for stablecoins, USDT, USDC, ETH, SOL, altcoins or “crypto” (as in “Bitcoin and stablecoin payments”), this message IS the walkthrough below: send it as it is, and do not ask yes or no first. Otherwise ask whether payers should also be able to pay with USDT, USDC, ETH or SOL, then give the walkthrough. The walkthrough:

    Go to https://lightning-swap.com, sign in for API keys, create a key, and copy the whole URI (https://openreceive.org/set_up_swap_provider). Paste it here and I will store it — or say “Bitcoin only” and I will continue without it.

    Mention FixedFloat only if they already use it.

  4. When they paste it. If it does not start with lightning+swapconnect://, ask them to copy it again. Otherwise add LSC_URI_PRIMARY=<paste> to the same .env with the file-editing tool, never a shell command. Swaps are now on, so build the refund route back (the swap non-negotiable below) as part of this integration. If they chose Bitcoin only, leave LSC_URI_PRIMARY unset and skip that route.
  5. Make the server load the file — yourself. OpenReceive reads process.env, and a .env file on disk is not in it. If AppModule already imports ConfigModule.forRoot() from @nestjs/config, that loads it. Otherwise put import "dotenv/config"; first in src/main.ts, as the quickstart does. When the app is started with Docker Compose, give the service env_file: .env. Restart the server after writing the file.

Do not invent placeholder URIs. Start the quickstart only once NWC_URI is saved and LSC_URI_PRIMARY is saved or explicitly declined. The first boot runs the receive-only preflight: if it reports spend methods such as pay_invoice, remove NWC_URI from .env and ask for a receive-only code again. Never set the spend-capable override to get past it.

Upgrading an existing install

This is not the opening move of a new integration. When OpenReceive is ALREADY installed here, npx openreceive doctor reports every credential as set/unset (never the value) and probes the wallet. Check the installed @openreceive/node and @openreceive/browser against the release named at the top of this file: the headless display models below do not exist in older versions, and the first tile click throws with nothing saying why. Upgrade first.

Only then start the quickstart.

After the quickstart — hand over, then stop

The quickstart is done when npx openreceive doctor --db <file-or-url> --url <app url> is clean and this app serves the checkout page for one of its orders. Doctor names any failed check and exits nonzero; fix it before going on. Doctor reads .env itself. Never source it into a shell: the & in a code splits the value and prints the pieces.

Give the user that checkout link. The browser check in the quickstart’s step 6 (payment-method icons, wallet logos, a pay tutorial) is theirs: name it in one line of your closing message, and do not run it yourself.

You cannot pay the invoice: the code is receive-only. Do not pay, settle or mark an order paid, and do not look for a way to (a wallet control port, a test endpoint, another wallet). If the user wants a real settlement test, they pay on that link from their own wallet, and onPaid marks the order paid.

Setup ends here. Your last message starts “Setup is finished” and has at most five short lines (about 80 characters each): the link, the methods it offers, and one line of what to look at. Send nothing after it. Do not list what changed, copy out the quickstart’s browser checklist, offer more work, or end the message on a question.

Non-negotiables

The quickstart below has the code. These are the rules it cannot state for itself, and they hold for every integration.

Your tables, not ours

npx openreceive scaffold payments --orm typeorm (or --orm prisma) emits openreceive_payments and openreceive_meta for THIS application’s database. Register the migration the way the app runs its other migrations. That is the whole persistence OpenReceive needs. It does not replace your orders, users, or products, and you do not join them.

If you build your own checkout UI

The drop-ins (<Checkout>, <openreceive-checkout>) already obey all of this. This list is the short form of https://openreceive.org/guides/checkout-ux.md, for a UI built on @openreceive/browser/headless. Read that before writing components.

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.

Questions, or a problem with the library 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-nestjs.

NestJS quickstart

NestJS on its default Express platform. Requires Node ≥ 22 and NestJS ≥ 10.

OpenReceive mounts in main.ts as Express middleware, with @openreceive/express, the adapter the Express quickstart uses. There is no Nest module to import. Three things differ from a plain Express app, and this page is about them:

1. Install

npm install @openreceive/express @openreceive/http @openreceive/react

@openreceive/express mounts the routes. @openreceive/http supplies the database handle in step 4 (typeOrmDb, prismaDb). Swap @openreceive/react for the UI package your frontend uses: @openreceive/vue, @openreceive/svelte, @openreceive/angular, or @openreceive/elements for server-rendered views. The openreceive package is only the CLI, and npx openreceive … below needs no install.

This page is for Nest’s default Express platform. OpenReceive has not been tested on @nestjs/platform-fastify.

Some editor sandboxes run npm with ignore-scripts. That setting skips Prisma’s engine download and esbuild’s binary postinstall. If a typecheck or build fails only in such an environment, the environment is the cause, not your code.

2. Migrate the payment tables

npx openreceive scaffold payments --orm prisma   # or drizzle | typeorm | sequelize | knex

openreceive scaffold payments writes one schema or migration file for your ORM, plus a wiring guide. It never touches a database. → openreceive scaffold payments

Then run the generated migration the way you normally do (for example npx prisma migrate dev). OpenReceive runs the tables’ logic at runtime, so there is nothing else to generate. Details: Payment storage, Node ORM recipes.

No ORM? You can pass a bare driver handle (pg, node:sqlite, better-sqlite3) as the db in step 4. The scaffold has no flavor for it. Instead of scaffolding, run the same DDL once yourself, using paymentsSchemaSql(dialect) from @openreceive/http. Your adapter already pulls that package in, but this import is yours, so install it too: npm install @openreceive/http.

With TypeORM, the scaffold writes src/migrations/20260101000000-create-openreceive-tables.ts. Register it the way the app registers its other migrations: a migrations glob such as dist/migrations/*.js already picks it up. It runs at start with migrationsRun: true, or with npx typeorm migration:run -d <data source>. With Prisma, scaffold with --orm prisma and run npx prisma migrate dev.

3. Add wallet credentials

Create a server-only .env:

NWC_URI=
LSC_URI_PRIMARY=
LSC_URI_BACKUP=
  1. Get a receive-only NWC code from a compatible wallet (get one here). Put it in NWC_URI.
  2. Optional: set up a swap provider. Put its connection string in LSC_URI_PRIMARY, and a second one in LSC_URI_BACKUP if you have one.

Never put these values in browser code. Your app refuses to start if the NWC code also advertises spend methods such as pay_invoice. Create a receive-only code instead (Security).

OpenReceive reads process.env, so creating a .env file is not enough on its own. If AppModule already imports ConfigModule.forRoot() from @nestjs/config, that loads .env into process.env before main.ts mounts OpenReceive. Otherwise put import "dotenv/config"; first in main.ts (npm install dotenv). Environment variables covers production secrets.

4. Wire OpenReceive in main.ts

One factory call takes your hooks and a database handle. Mount it in main.ts, after the app’s own session, cookie or Passport middleware and before app.listen(). There is no background reconciler: settlement runs during normal requests, through the durable reconcile gate.

import "dotenv/config"; // drop this line if ConfigModule.forRoot() loads .env
import { NestFactory } from "@nestjs/core";
import type { NestExpressApplication } from "@nestjs/platform-express";
import { openReceiveExpress } from "@openreceive/express";
import { typeOrmDb } from "@openreceive/http";
import type { Request } from "express";
import { DataSource } from "typeorm";
import { AppModule } from "./app.module";
import { AuthService } from "./auth/auth.service"; // your existing services
import { OrdersService } from "./orders/orders.service";

async function bootstrap() {
  const app = await NestFactory.create<NestExpressApplication>(AppModule);
  // The app's own app.use(session(...)), cookie-parser or passport.session()
  // stay above the mount, so the session is on the request when authorize runs.
  const orders = app.get(OrdersService);
  const auth = app.get(AuthService);
  // Nest adds its JSON body parser only at listen, after this mount. Without
  // this line every checkout request fails with a 500.
  app.useBodyParser("json");
  app.use(
    openReceiveExpress({
      wallet: { nwc: process.env.NWC_URI! }, // receive-only NWC code; your app refuses to start otherwise
      storage: {
        // The app's TypeORM DataSource. Prisma: prismaDb(app.get(PrismaService), "postgres").
        db: typeOrmDb(app.get(DataSource), "postgres"),
        onPaid: async ({ reference, paidAt, query }) => {
          // Settlement transaction; runs only for the first settled attempt for
          // a reference. The WHERE clause is the lock: a second fulfillment
          // path of yours (admin action, replayed job) updates zero rows. Use
          // `query` here, not a repository: it runs in this same transaction.
          // `$1` on postgres, `?` on sqlite.
          await query(
            "UPDATE orders SET status = 'paid', paid_at = $1 WHERE id = $2 AND status = 'awaiting_payment'",
            [paidAt, reference],
          );
        },
      },
      // The price for a reference (your order id, as a string) from your own
      // data. `value` is a decimal STRING from the order row, never a float and
      // never a request param. `description` is what the payer is buying.
      amountFor: async (reference) => {
        const order = await orders.findOne(reference);
        return order
          ? {
              currency: "USD",
              value: order.total.toString(),
              description: `${order.lines.length} items`,
            }
          : null;
      },
      // Nest's guards do not run here: make the check your guard makes.
      // `native` is the Express request your session, cookie-parser or
      // Passport middleware already filled in. `request` is a Web Request
      // without any of that, so a helper given it finds no session and every
      // payer gets a 403. `resource.reference` is a claim from the payer's
      // browser, not proof.
      authorize: async ({ action, native, resource }) =>
        orders.viewerMay(await auth.currentUser(native as Request), resource.reference, action),
      // Recommended for public web shops: caps invoice creation at 60 per
      // client IP per hour. Leave it off for point-of-sale deployments, where
      // many payers share the terminal's IP.
      rateLimiting: true,
    }),
  );
  // Behind a reverse proxy, rate limiting needs the real client IP. Delete the
  // line only if the app faces the network directly (see the rate-limiting guide).
  app.set("trust proxy", 1);
  await app.listen(process.env.PORT ?? 3000);
}
bootstrap();

The first request checks the wallet. Later OpenReceive requests also settle pending invoices, so a payer who closes the tab is still covered. → openReceiveExpress · authorize context

Where authorize finds the user:

app.setGlobalPrefix() does not move middleware. The routes stay under /openreceive, the prefix the checkout below uses.

An optional worker, startNotificationWorker({ service, host }), listens for wallet payment notifications so settlement does not wait for the next page load. → startNotificationWorker

Your app also needs an ordinary route that creates the order. It validates the cart, computes the price with exact decimal math, and returns the order id. The page passes that id as the reference. OpenReceive never takes a price from payer input.

The reference is a string you choose, and it identifies what gets fulfilled. Use your order id. Make it:

OpenReceive never looks inside the reference, but it relies on it:

Naming boundary: TypeScript APIs use camelCase fields (paymentHash, amountMsats). Everything on the wire is snake_case (payment_hash, amount_msats). The wire means the mounted HTTP routes and the browser snapshots.

5. Render checkout

import { Checkout } from "@openreceive/react";
import "@openreceive/react/styles.css";

<Checkout reference={order.id} prefix="/openreceive" />;

The checkout renders, polls, and settles itself.

@openreceive/react and @openreceive/elements each ship a compiled styles.css. Each sheet is self-contained, so a plain <link rel="stylesheet"> works with no build step. Each is also scoped: every rule applies only inside what OpenReceive renders.

Serve the compiled styles.css without Tailwind processing. Import it from JavaScript if your bundler handles CSS, or use a plain <link rel="stylesheet">. Do not @import it into your app’s Tailwind entry. Its rules have low specificity, so your page’s styles can override checkout styles. Scoping does not prevent that.

Server-rendered views (Handlebars, EJS, Pug) use the <openreceive-checkout> element from @openreceive/elements instead. Serve its standalone script and stylesheet straight from the package, so there is nothing to build:

import path from "node:path";
import { fileURLToPath } from "node:url";

app.useStaticAssets(
  path.dirname(
    fileURLToPath(import.meta.resolve("@openreceive/elements/standalone/openreceive-checkout.js")),
  ),
  { prefix: "/checkout-assets/" },
);

In a CommonJS build, the default before Nest 12, use path.dirname(require.resolve("@openreceive/elements/standalone/openreceive-checkout.js")). Then, on the order’s page:

<link rel="stylesheet" href="/checkout-assets/openreceive-checkout.css">
<script type="module" src="/checkout-assets/openreceive-checkout.js"></script>
<openreceive-checkout reference="{{order.id}}" prefix="/openreceive"></openreceive-checkout>

<Checkout> is complete as rendered. It already shows the description from amountFor and the collapsed transaction-details panel. Do not build a custom UI to show them. The display rules for them become your job only if you replace the drop-in component (Checkout UX).

Match the host page’s theme. By default the checkout follows the payer’s stored choice, then the system color scheme. If this page always uses one theme, lock it with <Checkout theme="dark" … />. On the custom element, set the theme attribute. Locking the theme keeps a white card off a dark page. CSS variables under data-theme style the checkout. Frontend checkout lists the settings you can change.

Everything the checkout draws ships inside the JavaScript: the payment-method icons, the wallet logos, and the pay tutorials. There is no image file to copy or serve, and no asset option to set. Deploy your normal JavaScript and CSS build output, including any generated JavaScript chunks. Bundlers with code splitting can wait to load tutorial screenshots until a tutorial first opens. Single-file builds, including the standalone checkout, include them from the start. If your Content-Security-Policy has a strict img-src, allow data: (Provider registry).

That is the whole loop. Your server owns the price and the order. The payer gets an invoice. onPaid runs inside the settlement transaction. If that transaction rolls back, the callback may run again. For delivery to outside systems, use an outbox in your app: record the message in the transaction and send it after commit.

The NestJS starter is a runnable one-product shop with all of the above: TypeORM, sessions, Handlebars views and the element (examples/nestjs-starter). Map its hooks onto the models in THIS app; do not copy its order model over yours.

6. Verify

npx openreceive doctor

openreceive doctor checks Node, NWC_URI, and the swap-provider configuration. It also probes the wallet relay to confirm the code is receive-only. Add --db <file-or-url> to confirm the migration ran. Add --url http://localhost:3000 to confirm the routes are mounted. Every failing line states its own fix. → openreceive doctor

Then open the checkout in a browser. Confirm the payment-method icons and wallet logos render. Open a wallet’s pay tutorial to check its screenshots. If an image is missing, look in the console for CSP violations and in the Network panel for failed JavaScript chunks. To fix it, allow data: in img-src and deploy the complete build output. Do not add image routes or copy package source images. Do not use registry icon_path or tutorial path keys as browser URLs.