Skip to content

wallets.md

Latest commit

 

History

History
397 lines (261 loc) · 15.3 KB

wallets.md

File metadata and controls

397 lines (261 loc) · 15.3 KB
layout default
title Backend wallets
nav_order 3
LNbits

phase: stable PRs: welcome

Backend wallets

LNbits is modular: You can switch the funding source (backend wallet) without changing anything else in your setup. Keep your extensions, apps, users, and config as-is — just point LNbits to a different backend via environment variables.

What stays the same when you switch backends

  • Your LNbits setup and extensions
  • Your API keys and endpoints
  • Your server and deployment setup

A backend wallet is selected and configured entirely through LNbits environment variables. See the options and variables below, and compare them here: Funding-Source-Table.md

Note

Terminology: “Backend Wallet” and “Funding Source” mean the same thing — the wallet or service that funds your LNbits.

Funding Sources

Funding Sources
CLNRest (runes) LND (REST) OpenNode
CoreLightning LND (gRPC) Blink
CoreLightning REST LNbits Alby
Spark (Core Lightning) LNPay Boltz
Spark L2 ZBD Phoenixd
Cliche Wallet
Breez SDK Breez Liquid SDK Nostr Wallet Connect
Strike Eclair (ACINQ) LN.tips
Fake Wallet

CLNRest (using runes)

Core Lightning REST API docs Should also work with the Rust version of CLNRest

Environment variables

  • LNBITS_BACKEND_WALLET_CLASS: CLNRestWallet
  • CLNREST_URL: https://127.0.0.1:3010
  • CLNREST_CA: /home/lightningd/.lightning/bitcoin/ca.pem (or the content of the file)
  • CLNREST_CERT: /home/lightningd/.lightning/bitcoin/server.pem (or the content of the file)
  • CLNREST_LAST_PAY_INDEX: lightning-cli listinvoices | jq -r '.invoices | map(.created_index) | max'
  • CLNREST_NODEID: lightning-cli getinfo | jq -r .id (only required for v23.08)

Create runes (copy/paste)

# Read-only: funds, pays, invoices, info, summary, and invoice listener
lightning-cli createrune \
  restrictions='[["method=listfunds","method=listpays","method=listinvoices","method=getinfo","method=summary","method=waitanyinvoice"]]' \
| jq -r .rune
# Invoice: max 1,000,001 msat, label must start with "LNbits", 60 req/min
lightning-cli createrune \
  restrictions='[["method=invoice"], ["pnameamount_msat<1000001"], ["pnamelabel^LNbits"], ["rate=60"]]' \
| jq -r .rune
# Pay: bolt11 amount < 1001 (msat), label must start with "LNbits", 1 req/min
lightning-cli createrune \
  restrictions='[["method=pay"], ["pinvbolt11_amount<1001"], ["pnamelabel^LNbits"], ["rate=1"]]' \
| jq -r .rune
# Renepay: invstring amount < 1001 (msat), label must start with "LNbits", 1 req/min
lightning-cli createrune \
  restrictions='[["method=renepay"], ["pinvinvstring_amount<1001"], ["pnamelabel^LNbits"], ["rate=1"]]' \
| jq -r .rune

Set the resulting values into:

  • CLNREST_READONLY_RUNE
  • CLNREST_INVOICE_RUNE
  • CLNREST_PAY_RUNE
  • CLNREST_RENEPAY_RUNE

CoreLightning

Required env vars

  • LNBITS_BACKEND_WALLET_CLASS: CoreLightningWallet
  • CORELIGHTNING_RPC: /file/path/lightning-rpc

CoreLightning REST

Old REST interface using RTL c-lightning-REST

Required env vars

  • LNBITS_BACKEND_WALLET_CLASS: CoreLightningRestWallet
  • CORELIGHTNING_REST_URL: http://127.0.0.1:8185/
  • CORELIGHTNING_REST_MACAROON: /file/path/admin.macaroon or Base64/Hex
  • CORELIGHTNING_REST_CERT: /home/lightning/clnrest/tls.cert

Spark (Core Lightning)

Required env vars

  • LNBITS_BACKEND_WALLET_CLASS: SparkWallet
  • SPARK_URL: http://10.147.17.230:9737/rpc
  • SPARK_TOKEN: secret_access_key

Spark L2

Self-custodial funding source using the Spark L2 network. Requires a Node.js sidecar that bridges lnbits talking to Spark. Works in addition with any Spark-compatible seed (Wallet of Satoshi, BuhoGO, BlitzWallet). If the sidecar is started with a mnemonic then that mnemonic will be used. Otherwhise if a mnemonic is set for the Spark L2 LNbits funding source then that mnemonic will be used.

Optional tuning

  • SPARK_L2_PAY_WAIT_MS: 4000 (payment timeout in ms)
  • SPARK_L2_PAY_POLL_MS: 500 (polling interval in ms)
  • SPARK_L2_STREAM_KEEPALIVE_MS: 15000 (SSE keepalive in ms)

Example: run the sidecar

git clone https://github.com/lnbits/spark_sidecar.git
cd spark_sidecar
npm install

SPARK_MNEMONIC="bottom bottom bottom bottom bottom bottom bottom bottom bottom bottom bottom bottom" \
SPARK_NETWORK=MAINNET \
SPARK_SIDECAR_PORT=8765 \
SPARK_PAY_WAIT_MS=20000 \
node server.mjs

For testing, you can generate a 12-word mnemonic at https://iancoleman.io/bip39/. Store it securely — it controls your funds. Then select Spark (L2) as the funding source in LNbits.

LND (REST)

Required env vars

  • LNBITS_BACKEND_WALLET_CLASS: LndRestWallet
  • LND_REST_ENDPOINT: http://10.147.17.230:8080/
  • LND_REST_CERT: /file/path/tls.cert
  • LND_REST_MACAROON: /file/path/admin.macaroon or Base64/Hex

or:

  • LND_REST_MACAROON_ENCRYPTED: eNcRyPtEdMaCaRoOn

LND (gRPC)

Required env vars

  • LNBITS_BACKEND_WALLET_CLASS: LndWallet
  • LND_GRPC_ENDPOINT: ip_address
  • LND_GRPC_PORT: port
  • LND_GRPC_CERT: /file/path/tls.cert
  • LND_GRPC_MACAROON: /file/path/admin.macaroon or Base64/Hex

You can also use an AES-encrypted macaroon instead:

  • LND_GRPC_MACAROON_ENCRYPTED: eNcRyPtEdMaCaRoOn

To encrypt your macaroon:

uv run lnbits-cli encrypt macaroon

LNbits

Required env vars

  • LNBITS_BACKEND_WALLET_CLASS: LNbitsWallet
  • LNBITS_ENDPOINT: for example https://lnbits.com
  • LNBITS_KEY: lnbitsAdminKey

LNPay

For the invoice listener to work you must have a publicly accessible URL in your LNbits and set up LNPay webhooks pointing to <your LNbits host>/wallet/webhook with the event Wallet Receive and no secret. Example: https://mylnbits/wallet/webhook.

Required env vars

  • LNBITS_BACKEND_WALLET_CLASS: LNPayWallet
  • LNPAY_API_ENDPOINT: https://api.lnpay.co/v1/
  • LNPAY_API_KEY: sak_apiKey
  • LNPAY_WALLET_KEY: waka_apiKey

OpenNode

For the invoice to work you must have a publicly accessible URL in your LNbits. No manual webhook configuration required.

Required env vars

  • LNBITS_BACKEND_WALLET_CLASS: OpenNodeWallet
  • OPENNODE_API_ENDPOINT: https://api.opennode.com/
  • OPENNODE_KEY: opennodeAdminApiKey

Blink

For the invoice to work you must have a publicly accessible URL in your LNbits. No manual webhook configuration required.

You can generate a Blink API key at https://dashboard.blink.sv. More info: https://dev.blink.sv/api/auth#create-an-api-key

Required env vars

  • LNBITS_BACKEND_WALLET_CLASS: BlinkWallet
  • BLINK_API_ENDPOINT: https://api.blink.sv/graphql
  • BLINK_WS_ENDPOINT: wss://ws.blink.sv/graphql
  • BLINK_TOKEN: BlinkToken

Alby

For the invoice to work you must have a publicly accessible URL in your LNbits. No manual webhook configuration required.

Generate an Alby access token here: https://getalby.com/developer/access_tokens/new

Required env vars

  • LNBITS_BACKEND_WALLET_CLASS: AlbyWallet
  • ALBY_API_ENDPOINT: https://api.getalby.com/
  • ALBY_ACCESS_TOKEN: AlbyAccessToken

Boltz

This connects to a running boltz-client and handles Lightning payments through submarine swaps on the Liquid network.

You can run the daemon in standalone mode via standalone = True in the config or boltzd --standalone. Create a Liquid wallet with:

boltzcli wallet create lnbits lbtc

Required env vars

  • LNBITS_BACKEND_WALLET_CLASS: BoltzWallet
  • BOLTZ_CLIENT_ENDPOINT: 127.0.0.1:9002
  • BOLTZ_CLIENT_MACAROON: /home/bob/.boltz/macaroons/admin.macaroon or Base64/Hex
  • BOLTZ_CLIENT_CERT: /home/bob/.boltz/tls.cert or Base64/Hex
  • BOLTZ_CLIENT_WALLET: lnbits

ZBD

For the invoice to work you must have a publicly accessible URL in your LNbits. No manual webhook configuration required.

Generate a ZBD API key here: https://zbd.dev/docs/dashboard/projects/api

Required env vars

  • LNBITS_BACKEND_WALLET_CLASS: ZBDWallet
  • ZBD_API_ENDPOINT: https://api.zebedee.io/v0/
  • ZBD_API_KEY: ZBDApiKey

Phoenixd

For the invoice to work you must have a publicly accessible URL in your LNbits.

You can get a phoenixd API key from ~/.phoenix/phoenix.conf. See the phoenixd documentation for details.

Required env vars

  • LNBITS_BACKEND_WALLET_CLASS: PhoenixdWallet
  • PHOENIXD_API_ENDPOINT: http://localhost:9740/
  • PHOENIXD_API_PASSWORD: PhoenixdApiPassword

Eclair (ACINQ)

Connect to an existing Eclair node so your backend handles invoices and payments.

Required env vars

  • LNBITS_BACKEND_WALLET_CLASS: EclairWallet
  • ECLAIR_URL: http://127.0.0.1:8283
  • ECLAIR_PASSWORD: eclairpw

Fake Wallet

A testing-only backend that mints accounting units inside LNbits accounting (no real sats).

Required env vars

  • LNBITS_BACKEND_WALLET_CLASS: FakeWallet
  • FAKE_SECRET: ToTheMoon1
  • FAKE_UNIT: sats

LN.tips

As the initinal LN.tips bot is no longer active the code still exists and is widly used. Connect one of custodial services as your backend to create and pay Lightning invoices through their API or selfhost this service and run it as funding source. Resources: https://github.com/massmux/SatsMobiBot

Required env vars

  • LNBITS_BACKEND_WALLET_CLASS: LNTipsWallet
  • LNTIPS_API_ENDPOINT: https://ln.tips
  • LNTIPS_API_KEY: LNTIPS_ADMIN_KEY

Breez SDK

A Greenlight invite code or Greenlight partner certificate/key can register a new node with Greenlight. If the Greenlight node already exists, neither is required.

Required env vars

  • LNBITS_BACKEND_WALLET_CLASS: BreezSdkWallet
  • BREEZ_API_KEY: ...
  • BREEZ_GREENLIGHT_SEED: ...
  • BREEZ_GREENLIGHT_INVITE_CODE: ...
  • BREEZ_GREENLIGHT_DEVICE_KEY: /path/to/breezsdk/device.pem or Base64/Hex
  • BREEZ_GREENLIGHT_DEVICE_CERT: /path/to/breezsdk/device.crt or Base64/Hex

Breez Liquid SDK

This uses the Breez SDK - Liquid to manage Lightning payments via submarine swaps on the Liquid network. Provide a mnemonic seed phrase (for example, generate one with a Liquid wallet like Blockstream Green) and set it in the environment or admin UI.

Required env vars

  • LNBITS_BACKEND_WALLET_CLASS: BreezLiquidSdkWallet
  • BREEZ_LIQUID_SEED: ...

Fees apply for each submarine swap. You may need to increase the reserve fee under Settings → Funding or via:

  • LNBITS_RESERVE_FEE_MIN: ...
  • LNBITS_RESERVE_FEE_PERCENT: ...

Cliche Wallet

Required env vars

  • CLICHE_ENDPOINT: ws://127.0.0.1:12000

Nostr Wallet Connect (NWC)

To use NWC as a funding source you need a pairing URL (pairing secret) from an NWC provider. See providers here: https://github.com/getAlby/awesome-nwc?tab=readme-ov-file#nwc-wallets

Configure in the admin UI or via env vars:

  • LNBITS_BACKEND_WALLET_CLASS: NWCWallet
  • NWC_PAIRING_URL: nostr+walletconnect://...your...pairing...secret...

Strike (alpha)

Custodial provider integrated via Strike OAuth Connect (OAuth 2.0 / OIDC). Authenticate a Strike user in your app, then call Strike APIs on the user’s behalf once scopes are granted. Requires a Strike business account, registered OAuth client, minimal scopes, and login/logout redirect URLs.

Get more info here https://docs.strike.me/strike-oauth-connect/

Integration endpoints

  • STRIKE_API_ENDPOINT: https://api.strike.me/v1
  • STRIKE_API_KEY: YOUR_STRIKE_API_KEY

Additional Guides

  • Admin UI — Manage server settings via a clean UI (avoid editing .env by hand).
  • User Roles — Quick Overview of existing Roles in LNBits.
  • Funding sources — What’s available and how to enable/configure each.

Powered by LNbits

LNbits empowers everyone with modular, open-source tools for building Bitcoin-based systems — fast, free, and extendable.

If you like this project, send some tip love or visit our Shop

LNbits Shop Visit LNbits Shop Try myLNbits SaaS Read LNbits News Explore LNbits Extensions