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

OpenReceive agent directions (FastAPI)

# READ THIS FIRST: this file is 37 KB and a summary drops required steps. Download it whole:
curl -fsSL https://openreceive.org/agent-directions/fastapi/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.19.

Add OpenReceive to a FastAPI application — the app you are already working in. You do not need a copy of the OpenReceive source: the engine is on PyPI (openreceive[fastapi]), the checkout UI is 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 the router serves — do not reimplement wallet RPC, settlement, or pricing.

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 plain HTML or Jinja templates) — do not add React to an HTMX app. Keep FastAPI’s dependency system: the auth dependency this app already resolves its user with is what authorize should call on context.request, and the database OpenReceive gets is a sync SQLAlchemy Engine for the SAME database this app already uses.

What OpenReceive is

A payment library that runs inside YOUR server. It is an APIRouter (openreceive_router, included under /openreceive) that serves its HTTP routes inside 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, look at one file: the project’s .env, if it exists. Read it only far enough to see whether NWC_URI and LSC_URI_PRIMARY are there and non-empty, 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.

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, creating the file if needed. 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 already asked for stablecoins or altcoins, skip the yes/no and go straight to the walkthrough. Otherwise ask whether payers should also be able to pay with USDT, USDC, ETH or SOL. 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, without echoing it. 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 os.environ, and a .env file on disk is not in it. Start the dev server with uvicorn --env-file .env (update the app’s run script or Procfile, not just your own command). When it 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.

After the router is wired, run openreceive doctor --app <module>:app. It reports NWC_URI presence without printing it, probes the wallet, and names any hook still on a placeholder and whether the migration ran. Exit code 1 is a finding to fix, not a reason to skip the check.

Upgrading an existing install

This is not the opening move of a new integration. When OpenReceive is ALREADY installed here, the doctor above is the first check. Compare the installed openreceive (pip show openreceive) 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 openreceive doctor --app <module>:app --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.

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: tell them what to look at, 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 on_paid marks the order paid.

Setup ends here. Say “Setup is finished” in one message, with the link and what to check. Do not 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

openreceive scaffold payments --alembic (or --sql) emits openreceive_payments and openreceive_meta for THIS application’s database. 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-fastapi.

FastAPI quickstart

FastAPI + React. Requires Python ≥ 3.10, FastAPI ≥ 0.115 (Starlette ≥ 0.40) and a SQLAlchemy 2 Engine for OpenReceive’s two tables.

1. Install

pip install "openreceive[fastapi]"
npm install @openreceive/react

OpenReceive is one Python distribution with framework extras. openreceive[fastapi] brings FastAPI, Starlette and SQLAlchemy. The base package includes the wallet client (websockets, coincurve, cryptography), the HTTP engine and the openreceive CLI. The npm package is the checkout UI for your frontend. On a different stack, swap the two: use openreceive[django] with the Django quickstart. A page without a bundler uses @openreceive/elements instead of React.

  Packages
Server openreceive[fastapi], openreceive[django], openreceive[sqlalchemy] (Flask and plain WSGI/ASGI: the Flask recipe)
Frontend @openreceive/react, @openreceive/vue, @openreceive/svelte, @openreceive/angular, @openreceive/elements (plain HTML)

Use uv or a virtualenv on Python 3.10 or newer. A system Python 3.9 cannot install the package.

2. Migrate the payment tables

openreceive scaffold payments --alembic --dialect postgres    # or sqlite | mysql

openreceive scaffold payments --alembic writes one Alembic revision into alembic/versions/. The DDL is frozen in the file, and it creates two tables:

Set the revision’s down_revision to your current head (alembic heads). Then apply it the way you apply your own revisions: alembic upgrade head. The command never opens a database connection. → openreceive scaffold payments

No Alembic? openreceive scaffold payments --sql --dialect postgres prints the same DDL. Feed it to psql, a Flyway file, or whatever runs your migrations. In code, payments_schema_sql(dialect) from openreceive.storage.sql returns the same string. OpenReceive owns the tables’ logic at runtime: locking, write-once settlement, and the reconciliation state machine. There is nothing else to generate. Details: Payment storage.

3. Add wallet credentials

Put the credentials in the server’s environment. That can be a .env your process manager loads, uvicorn --env-file .env, or your secret store:

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 os.environ, so a .env file on disk is not enough on its own. uvicorn --env-file .env loads one in development. In production, the process manager or secret store injects the values. Environment variables lists every variable.

4. Wire OpenReceive

The wiring takes twelve lines:

The router builds the wallet client from NWC_URI and mounts the framework-free engine. There is no background reconciler, meaning no job that checks pending payments on a timer. Settlement runs during normal requests instead, through the durable reconcile gate.

from fastapi import FastAPI
from sqlalchemy import create_engine
from openreceive.fastapi import openreceive_lifespan, openreceive_router
from openreceive.server import Host
from .app import current_user, orders  # your existing models and auth dependency

# OpenReceive's own sync Engine for its two tables — the SAME database as
# your orders, its own connection pool. On SQLite give it a dedicated Engine.
engine = create_engine("postgresql+psycopg://…")

host = Host(
    # The price for a reference — here, your order id — from your own data;
    # OpenReceive converts it into the Lightning invoice. Return None 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.
    amount_for=lambda reference: (
        {"currency": "USD", "value": str(order.total), "description": order.summary}
        if (order := orders.find(reference))
        else None
    ),
    # Your own access check: may this caller do this action to this reference?
    # `context.request` is the untouched Starlette Request — reuse the same
    # dependency your order page uses. `context.resource["reference"]` is a
    # claim the payer's browser sent, not proof.
    authorize=lambda context: orders.viewer_may(
        current_user(context.request), context.resource["reference"], context.action
    ),
    # INSIDE the settlement transaction; runs only for the reference's first
    # settled attempt. Use `settlement.connection` (that transaction) for the
    # order write, never a second session. The WHERE clause is the lock.
    on_paid=lambda settlement: settlement.connection.execute(
        orders.claim_paid(settlement.reference, settlement.paid_at)
    ),
)

app = FastAPI(lifespan=openreceive_lifespan(host, engine=engine))
app.include_router(
    # Recommended for public web shops: `rate_limiting=True` 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.
    openreceive_router(host, engine=engine, rate_limiting=True),
    prefix="/openreceive",
)

authorize receives the Starlette Request. Cookies, headers, and whatever SessionMiddleware or auth dependency this app already has are readable there. FastAPI ships no session of its own, so you must bind the payer’s reference to something the request proves. Behind a reverse proxy, run uvicorn with --proxy-headers. Otherwise rate_limiting counts the proxy as the one payer.

There is no CSRF layer to add. FastAPI has no CSRF (cross-site request forgery) layer, and OpenReceive does not want one. Every mounted route refuses a request whose Sec-Fetch-Site header says cross-site. That stops another origin’s page from minting or refunding on a logged-in payer’s behalf. The Express and Fastify adapters rely on exactly the same protection. Its limit is the header itself. A client that does not send it, such as a non-browser or an old browser, is not refused. So authorize stays the actual boundary. Security has the full account.

openreceive_lifespan runs the receive-only wallet preflight when uvicorn starts. It stops the process if the code is missing, unreachable, or able to spend. That way the deploy fails instead of the first payer. Pass lazy=True for tests and for build steps that have no secrets. The first request then checks the wallet, and requests get 503 WALLET_UNAVAILABLE until the check passes. → openreceive_router · openreceive_lifespan · the authorize context

rate_limiting=True is for public web shops. Leave it off for point-of-sale, where many payers share one IP. → Rate limiting

An optional worker, openreceive notifications --app main:app, listens for wallet payment notifications so settlement does not wait for the next page load. → openreceive notifications

Your app also needs an ordinary order-creation route that validates the cart, prices with exact decimal math, and returns the order id the page will pass as the reference. OpenReceive never prices from payer input.

The reference is a string you choose, and it is the fulfillment identity: your order id. Use one per thing you fulfill, create it before checkout, keep it across retries, and never reuse it. OpenReceive never looks inside it, but the reference still matters:

Naming boundary: the Python API is snake_case (payment_hash, amount_msats), and so is everything on the wire. The mounted HTTP routes and the browser snapshots use the same names.

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 zero specificity, so your page’s styles can override checkout styles. Scoping does not prevent that.

<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.

A page without a bundler renders the same checkout as a custom element: <openreceive-checkout reference="…" prefix="/openreceive"> from @openreceive/elements. You can also serve its standalone build from your static directory.

Buy a Button is a runnable illustration of the boundary (examples/buttons/server/fastapi). It is not a template to copy models from. It keeps products, visitors and orders in SQLite, and the three hooks are the only bridge to OpenReceive. It is the smallest correct FastAPI integration of the packaged checkout. Map that shape onto the models in THIS app.

6. Verify

openreceive doctor --app main:app

openreceive doctor checks Python, NWC_URI, and swap-provider configuration. It also probes the wallet relay to confirm the code is receive-only. With --app module:attr (your FastAPI app, the router, or an OpenReceiveApp), it also confirms the migration ran and names any hook still on a placeholder. Add --url http://localhost:8000 to confirm the routes are mounted. Every failing line states its own fix, and the command exits with code 1 when anything fails. openreceive debug-report prints the same output as a redacted support report. → openreceive doctor

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

Swap credentials (LSC_URI_*) stay server-side too. The provider order id and token live in the attempt’s server-only swap_data column. They never reach a response or a log (Automated swaps).