Open-source Lightning & on-chain infrastructure

Ship any Lightning product in under 3 minutes

Breez Infra is the open-source stack for introducing Lightning and on-chain payments into your app, platform, or product — wallets, checkout flows, micropayments, and more. No node required.

Lightning paymentsOn-chain BitcoinWalletsPayment railsMicropaymentsMerchant tools

3-step setup · Lightning + on-chain · Self-custodial

Start in 3 minutes View on GitHub

< 3 min

To deploy

LN + on-chain

Payment layers

Product patterns

Community deployments

🇸🇳 Senegal

Lightning + on-chain

🇧🇯 Benin

Wallets & rails

Open source

Deploy in < 3 min

What you can build

One infrastructure, endless Lightning products

Breez Infra is the foundation for any project that needs Lightning or on-chain Bitcoin — ship wallets, checkout flows, micropayments, and payment rails without running your own node.

Wallet

Lightning Wallets

Spin up a self-custodial wallet backend — receive, send, check balance, and sign messages. Build mobile or web wallets without running a node.

LNURL

Custom Lightning Addresses

Deploy your own Lightning address system on your domain. Route user@yourapp.com payments through LNURL and BOLT 12 offers.

Payments

Payment Rails

Embed sats-based checkout into marketplaces, SaaS products, or community platforms. BOLT 11, BOLT 12, on-chain, and fiat conversion built in.

Education

EdTech Micropayments

Charge per lesson, per article, or per minute of video. Perfect for educational platforms where traditional payment fees kill small transactions.

Connectivity

Pay-for-WiFi

Sell timed internet access at events, co-working spaces, or cyber cafés. Captive portal + Lightning invoice in one flow.

Commerce

Merchant & POS Tools

Generate QR invoices for local merchants, track payment status in real time, and onboard businesses to the Lightning economy.

Quick Start

Up and running in 3 minutes

Three steps from zero to a live Lightning and on-chain payment stack. No full node, no DevOps headache — just Node.js, a Breez API key, and your product.

1~1 min

Get your Breez API key

Request a free Breez API key and prepare a dedicated demo wallet mnemonic.

breezee — bash

2~1 min

Clone & configure

Install dependencies, add your Breez credentials (and optionally BREEZ_NETWORK=testnet), then generate read and spend keys with the built-in rotation CLI.

breezee — bash

3~30 sec

Launch your infrastructure

Start on testnet for safe demos. Switch to mainnet later with npm run start:mainnet or BREEZ_NETWORK=mainnet. List payment history anytime with GET /payments.

breezee — bash

Testnet: npm run dev:testnet · Mainnet: npm run start:mainnet · Rotate keys: npm run rotate-keys -- --grace

Capabilities

Infrastructure primitives, ready to compose

Wallet core, invoice engine, persisted history, testnet/mainnet modes, and payment rails — the building blocks for any project that accepts Bitcoin.

Wallet Core

Self-custodial wallet powered by Breez Liquid SDK. Mnemonic-backed, nodeless — the foundation for any Lightning product you want to build.

Payment Rails

Pay Lightning invoices, LNURL, Lightning addresses, and on-chain Bitcoin. Fiat-to-sats conversion for flexible pricing.

Invoice Engine

BOLT 11 and BOLT 12 invoices with QR codes, payment tokens, and automatic status tracking when sats arrive.

On-Chain Payments

Receive Bitcoin on-chain alongside Lightning. Generate addresses, QR codes, and unified payment flows for any product that needs both layers.

Tiered API Keys

Read keys for frontends, spend keys for admin. Generate and rotate them from the CLI with npm run rotate-keys — no manual secret crafting.

Event-Driven Flows

SDK payment events trigger downstream actions — unlock WiFi, grant course access, or push signed webhooks to your backend when sats move.

Payment Webhooks

One infrastructure webhook receives signed HMAC events for every payment — invoices, WiFi, bridge forwards, and outbound sends. Verify with delivery IDs and retry-safe idempotency.

Balance Monitoring

Low-wallet alerts push balance.alert and balance.recovered to the same webhook. Checks on startup, periodic polls, and after every send/receive — no polling GET /health yourself.

Payment History

Every invoice, WiFi charge, bridge forward, and outbound send is persisted to SQLite. Query history with filters or look up a paymentToken — records survive restarts, and pending invoices expire automatically.

Network Modes

Run on Liquid testnet for safe demos, then flip to mainnet with one env var or CLI flag. Wallet data stays isolated under testnet/ or mainnet/ — no accidental mixed networks.

Developer-Ready

Swagger at /api-docs, Mintlify guides, and a clean MVC architecture. Extend controllers to match your use case.

Battle-tested in Africa

Real projects, real Bitcoin payments

From startups to community platforms, teams across Africa use Breez Infra to introduce Lightning and on-chain payments into products people use every day.

🇧🇯

Benin

Cotonou · Startups & community projects

2025–2026

Teams in Benin use Breez Infra to introduce Lightning and on-chain payments into wallets, merchant tools, WiFi monetization, and local apps.

Project highlights

Lightning + on-chain wallet backends
Pay-for-WiFi and captive portal billing
Merchant QR invoicing and payment rails

Click a node to see how teams introduce Bitcoin payments

Architecture

The stack behind your Bitcoin payments

Whether you are launching a wallet, adding checkout to a SaaS product, or enabling micropayments on a content platform — Breez Infra gives you a nodeless, self-custodial backend for Lightning and on-chain from day one.

Safe by design

Read keys for client apps, spend keys server-side only. Rotate keys with npm run rotate-keys — use --grace to roll out without downtime. Prefer testnet for demos.

Persist → webhook → reconcile

Payments land in SQLite (pending → paid/sent/expired), then push signed webhooks. Rebuild state anytime with GET /payments?since=… if a delivery was missed.

Event-driven architecture

Payment events unlock WiFi, grant access, and push payment.received / payment.sent to your backend — with HMAC verification and retry-safe delivery IDs.

Mainnet or testnet

Flip networks with BREEZ_NETWORK or npm run dev:testnet / start:mainnet. Wallet data stays isolated under testnet/ or mainnet/.

Payment flow

Your App

SaaS · Wallet · POS

Breez Infra

API + persist + push

Breez SDK

LN + on-chain

Bitcoin

Lightning + L1

WiFi packages

15 min

100 sats

1 hour

350 sats

3 hours

800 sats

24 hours

2,000 sats

Observability

Webhooks & balance monitoring

Stop polling GET /health and /payment-status. Breez Infra pushes signed events to your backend for every payment and low-wallet alert.

Infrastructure webhooks

One URL for all wallet activity — invoices, WiFi, bridge, and sends.

payment.received

receiveinvoices, WiFi, BOLT 12, on-chain, bridge

payment.sent

send/pay-invoice, bridge forwards

payment.forwarding

sendbridge — forward started

payment.forward_failed

bridge only

payment.amount_rejected

bridge only

webhook.test

POST /webhook/test

Every delivery is HMAC-SHA256 signed (X-Webhook-Signature) with a stable X-Webhook-Delivery-Id across retries. Verify the signature, dedupe by delivery ID, respond 200 — failed deliveries retry up to 3 times. After retries fail, rebuild from the ledger with GET /payments?since=<unix-ms>.

Balance monitoring

Automatic low-wallet alerts on the same infrastructure webhook.

balance.alertAvailable balance drops below threshold

balance.recoveredBalance rises above threshold after a prior alert

Compares availableSats = balance − pending sends (not raw balance). Alerts are informational — they do not block payouts.

startupperiodicsendreceive

Alert payload excerpt

{
  "event": "balance.alert",
  "trigger": "send",
  "wallet": {
    "availableSats": 42000,
    "thresholdSats": 50000
  }
}

Configure in .env

Both features share WEBHOOK_URL and WEBHOOK_SECRET. Balance alerts require both the threshold and the webhook — threshold alone logs a startup warning.

# Infrastructure webhook (all payments + balance alerts)
WEBHOOK_URL=https://your-app.example.com/webhooks/breez
WEBHOOK_SECRET=whsec_your_infrastructure_secret

# Low wallet balance alerts (same webhook URL)
BALANCE_ALERT_THRESHOLD_SATS=50000
BALANCE_ALERT_INTERVAL_MS=300000
BALANCE_ALERT_COOLDOWN_MS=3600000

Test delivery:curl -X POST -H "x-api-key: YOUR_READ_KEY" http://localhost:3000/webhook/testFull webhook guide →·Payment history guide →

API Reference

RESTful primitives for every product

Wallet, invoice, history, WiFi, and webhook endpoints — compose them into wallets, Lightning address routers, edtech paywalls, or merchant tools. Persist + push events replace fragile polling for production. Interactive Swagger docs at /api-docs when the server is running.

GET/health

Service health + wallet balanceRead

GET/rates

All supported fiat ratesRead

POST/price

Rate for one currencyRead

Contribute

Claim an issue. Ship from the browser.

Open issues sync from GitHub. Propose a bug or feature from here, then comment /claim to assign yourself — no maintainer ping needed.

Pick an open issue

Browse bugs, features, and good-first tasks from the live GitHub board — or propose a new one from this page.

Comment /claim

A GitHub Action listens for your comment, assigns the issue to you, and labels it in progress.

Ship a PR

Fork, branch, and open a pull request. CI runs on every push.

Open issues

Good first issues Open in Codespaces

#1in progress
Balance monitoring
Claim issue

New issues open on GitHub under your account after you confirm. Claiming requires the issue_comment workflow (.github/workflows/claim-issue.yml) — comment /claim to get assigned.

Open source · MIT · Community-driven

Your Lightning stack starts here

Clone the repo, configure your keys, and add Lightning and on-chain payments to your next app, SaaS, marketplace, or community platform.

Star on GitHub Read the setup guide

Ship any Lightning product in under 3 minutes

One infrastructure, endless Lightning products

Lightning Wallets

Custom Lightning Addresses

Payment Rails

EdTech Micropayments

Pay-for-WiFi

Merchant & POS Tools

Up and running in 3 minutes

Get your Breez API key

Clone & configure

Launch your infrastructure

Infrastructure primitives, ready to compose

Wallet Core

Payment Rails

Invoice Engine

On-Chain Payments

Tiered API Keys

Event-Driven Flows

Payment Webhooks

Balance Monitoring

Payment History

Network Modes

Developer-Ready

Real projects, real Bitcoin payments

Project highlights

The stack behind your Bitcoin payments

Safe by design

Persist → webhook → reconcile

Event-driven architecture

Mainnet or testnet

Webhooks & balance monitoring

Infrastructure webhooks

Balance monitoring

Configure in .env

RESTful primitives for every product

General3 endpoints

Invoices (receive)4 endpoints

Payments (history)4 endpoints

Payments (spend)2 endpoints

WiFi3 endpoints

Webhooks & monitoring5 endpoints

Claim an issue. Ship from the browser.

Pick an open issue

Comment /claim

Ship a PR

Your Lightning stack starts here