OpenReceive for Fastify

Accept Bitcoin & Stablecoin Payments With Fastify

Register the OpenReceive Fastify plugin with a prefix and three hooks. Invoices, polling and settlement run inside your own server, with no body parser or extra service.

Package

Tested live · Oct 14, 2026 · 0.4.26

Copy agent directions — Paste into Claude Code, Codex or Cursor to add OpenReceive to your Fastify app.

Why OpenReceive

Try the checkout your customers will see

The live demo needs JavaScript: open the OpenReceive home page.

Six steps, real code

Requires Node ≥ 22.

1. Get a receive-only NWC code — get one here. It can issue invoices and watch for payment, and it can never spend from your wallet.

2. Get an LSC code for swaps (optional) — from a swap provider, only if customers should be able to pay in USDT, USDC, ETH or SOL.

3. Set the environment variables — NWC_URI (required) and LSC_URI_PRIMARY / LSC_URI_BACKUP (optional) in the environment of your Fastify server process; see Environment variables.

4. Install

npm install @openreceive/fastify @openreceive/react

5. Wire OpenReceive — quoted from the Fastify quickstart.

import "dotenv/config"; // loads .env into process.env; nothing else does
import Fastify from "fastify";
import { openReceiveFastify } from "@openreceive/fastify";
import { db, orders, sessions } from "./app.ts"; // your existing database handle and models

// Behind a reverse proxy or load balancer, rate limiting needs the real client
// IP — without this every payer shares the proxy's IP and one abuser can lock
// checkout for everyone. The Fastify spelling of Express's "trust proxy";
// drop it only if the app faces the network directly (see the rate-limiting
// guide).
const app = Fastify({ trustProxy: true });

await app.register(openReceiveFastify, {
  wallet: { nwc: process.env.NWC_URI! }, // receive-only NWC code; your app refuses to start otherwise
  storage: {
    db, // pg Pool/Client, mysql2 Pool, node:sqlite, better-sqlite3, or a custom adapter
    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 and does nothing.
      // Use `query` here, not your ORM's other connection. `?` on sqlite and
      // mysql, `$1` on postgres. MySQL has no RETURNING: after the UPDATE,
      // `SELECT ROW_COUNT() AS claimed` tells you the same thing.
      const claimed = await query(
        "UPDATE orders SET state = 'paid', paid_at = ? WHERE id = ? AND state = 'awaiting_payment' RETURNING id",
        [paidAt, reference],
      );
      if (claimed.length === 0) return;
    },
  },
  // The price for a reference — here, your order id — from your own data;
  // OpenReceive converts it into the Lightning invoice. Return null when
  // there is nothing to pay for. `value` is a decimal STRING from the order
  // row, never a float and never a request param. `description` is what the
  // payer is buying, in your own words.
  amountFor: async (reference) => {
    const order = await orders.find(reference);
    return order
      ? {
          currency: "USD",
          value: order.total.toString(),
          description: `${order.lines.length} items`,
        }
      : null;
  },
  // Your own access check: may this caller do this action to this reference?
  // `resource.reference` is your own order id, sent back by the payer's
  // browser — a claim, not proof — already validated as a non-empty string.
  // `native` is the untouched Fastify request: pass it to this app's own
  // cookie and session helpers, and a session decorated by @fastify/session
  // (or whatever this app uses) is readable on it. `request` is a Web
  // Request, so a helper that reads `req.headers.cookie` finds nothing on it
  // and every payer gets a 403.
  authorize: async ({ action, native, resource }) =>
    orders.viewerMay(
      await sessions.currentUser(native),
      resource.reference,
      action,
    ),
  // Recommended for public web shops: caps invoice creation at 60 per client IP
  // per hour. Leave it off (the default) for point-of-sale deployments, where
  // many payers share the terminal's IP.
  rateLimiting: true,
  // The mount. Pass it HERE, at register(), never only inside the options:
  // Fastify scopes the plugin's catch-all route to it, and the OpenReceive
  // routes live directly under it.
  prefix: "/openreceive",
});

6. Render the checkout

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

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

Full Fastify quickstart · Example app

How it runs

Tested on
Node 22
Databases
PostgreSQL, directly or through a transaction pooler, MySQL 8, MariaDB 11 and SQLite
Secrets
NWC_URI, and LSC_URI_PRIMARY for swaps, in the server's environment or .env file, never in browser code
Refunds
Refund a settled Lightning payment from your own wallet: the wallet code is receive-only. A swap deposit that never converted goes back to the payer through the checkout's refund form.
Mobile apps
No app SDK. A mobile app opens your checkout page in a browser tab, which the app stores allow for physical goods and real-world services; digital goods need a link-out program.

Practical questions

Which currencies can customers pay with?
Bitcoin over Lightning, always. With a swap provider configured, also USDT on Tron, Solana or Ethereum, USDC on Solana or Ethereum, ETH and SOL, each converted into the same Lightning payment. Automated swaps guide
Where does the Bitcoin go?
Into the wallet behind your NWC code. OpenReceive never holds funds: the invoice is minted in your wallet and the sats land there. Your server confirms settlement and runs your onPaid hook once per order. Payment storage guide
What wallet do I need?
Any wallet that issues receive-only NWC (Nostr Wallet Connect) codes, hosted or self-run. The code must be able to create invoices and read their status, and must not be able to spend. Get a receive-only NWC code
What does it cost?
OpenReceive is open source and free. Fees charged by your wallet provider, by a swap provider or by Lightning routing belong to those services and are outside OpenReceive's scope.
What do I need to deploy?
A server process with NWC_URI in its environment and a database for the payment tables. No background worker is required: settlement runs on the mounted routes, with an optional notification worker for faster confirmation. Deploying guide

Add OpenReceive to your Fastify app

Copy agent directions · Full quickstart · Example app · API reference · Guides