Branch: master
Find file Copy path
092afbc Feb 5, 2019
3 contributors

Users who have contributed to this file

@pavlenex @NicolasDorier @britttttk
295 lines (197 sloc) 13.4 KB

This document clarifies some of the most common questions and issues users face with the Lightning Network in BTCPay. Before you start using the off-chain protocol, familiarize yourself with the risks. Additionally, read Getting Started with Lightning Network in BTCPay

Lightning Network General FAQ

Lightning Network (LND) FAQ

Lightning Network (c-lightning) FAQ

Lightning Network General FAQ

Here are some general questions about LN in BTCPay, regardless of the implementation.

How many users can use Lightning Network in BTCPay?

In BTCPay, only server admin has the Lightning Network node, due to technical and security reasons. On a self-hosted server, you can use only 1 Lightning Node. If you want to accept LN in multiple stores, you'll have to deploy a separate server for each store.

How to find node info and open a direct channel with a store using BTCPay?

If you're a customer trying to pay a Lightning Network invoice:

  1. make sure to select "Lightning" from coin selection.
  2. Select Copy/Scan
  3. Select Node Info and scan or copy it manually.

BTCPay Checkout

The exact procedure of opening a direct Lightning Network channel depends on the wallet you’re using. But, you should be able to figure it out easily now that you have merchant’s node information.

As a merchant, do I need to open direct channels?

Merchants need incoming channels - other people opening a channel with them, providing liquidity. Your customer should be able to open a direct channel with you. You can also ask well-connected nodes to open a direct channel with you. Opening a channel is not spending funds, it’s more like putting the funds on a pre-paid card, and spending it later, or withdrawing it by closing a channel.

I previously installed BTCPayServer without the integrated lightning support, can I migrate?

The integrated lightning support is only useful for scenario where you are at the same time the host and the merchant of BTCPay Server.

When logged as admin of your server you will then have a nice link to connect to plug your lightning node to BTCPay Server.


You can then click on Test Connection in this page to see if you successfully configured your lightning node.

Depending on how you deployed BTCPayServer you might have different step to do:

Case 1: You manually installed

If you installed BTCPayServer manually without docker or Azure, then you only need to start run CLightning with the correct network parameter.

Assuming you are running as root, CLightning will allow call to its API via a unix socket on /root/.lightning/lightning-rpc

Once this is done, make sure you start BTCPayServer with


If you are using CLightning for Litecoin, use the parameter -ltclightning instead.

Then, make sure the port lightning network ports 9735 (BTC) and 9736 (LTC) are open on your firewalls.

Case2: You are using docker (without Azure)

In this case, you only have to change the docker-compose you are using. If before you were using docker-compose -f "$(pwd)/Production/docker-compose.btc-ltc.yml" up -d (as documented here), then you need to change to docker-compose -f "$(pwd)/Production/docker-compose.btc-ltc-clightning.yml" up -d.

Then, make sure the port lightning network ports 9735 (BTC) and 9736 (LTC) are open on your firewalls.

Case3: You are using Azure

Log as root:

sudo su -


wget -O - >

Modify the file /etc/profile.d/

You should have something like:

export BTCPAY_DOCKER_COMPOSE="/var/lib/waagent/custom-script/download/0/btcpayserver-docker/Production/docker-compose.btc-ltc.yml"

Modify by adding -clightning at the end:

export BTCPAY_DOCKER_COMPOSE="/var/lib/waagent/custom-script/download/0/btcpayserver-docker/Production/docker-compose.btc-ltc-clightning.yml"

Update your environment variables in current session by running:

. /etc/profile.d/

Then restart your server:

Then, connect to your Microsoft Azure Portal, Go to the resource group of your install, and add a new security rule in the Network Security Group inside it. (See this example)

If your resource group do not have a Network Security Group, you can skip this step. The Network Security Group has been introduced in new Azure installs.

Add a Security Inbound Rules:

Rule 1:

  • Name: LightningBTC
  • Priority: 150
  • Source: Internet
  • Destination: Any
  • Port: 9735
  • Protocol: TCP

Rule 2:

  • Name: LightningLTC
  • Priority: 151
  • Source: Internet
  • Destination: Any
  • Port: 9736
  • Protocol: TCP

Here is how it should look like:


Can I use a pruned node with LN in BTCPay?

Both LND and c-lightning support prunning.

This will prune your Bitcoin full node to a maximum of 100GB (of blocks):

export BTCPAYGEN_ADDITIONAL_FRAGMENTS="opt-save-storage"`
. ./ -i

Other pruning options are documented here

How to change from c-lightning to LND or vice-versa?

You need to SSH log in into your virtual machine.

To switch to LND:

sudo su -
cd btcpayserver-docker
. ./ -i 

To switch to c-lightning:

sudo su -
cd btcpayserver-docker
export BTCPAYGEN_LIGHTNING="clightning"
. ./ -i

I switched Lightning Network implementation, but getting "no payment available" error

When you switch from one implementation to another, you need to reconfigure your lightning connection string at a store level, to use adequate implementation. Stores > General Settings > Lightning nodes > Modify > Connection string. In connection string, click on the "click here" link.

I get "WARNING: The LIGHTNING_ALIAS variable is not set. Defaulting to a blank string" when starting container

You can ignore this. If you want to set an alias for your lightning node, open the env file:

sudo su -

And add or modify the LIGHTNING_ALIAS entry to LIGHTNING_ALIAS=myawesomenode.

How to display my Lightning Node information so that others can connect to me?

The information other users need to connect to your node, is already displayed at the checkout. Sometimes, merchants want to display their node so that their customers can connect beforehand.

There are numerous ways to find your node information, but the easiest way to display it to others is by using Lightning Node info page. Go to Store > General Settings > Lightning nodes > Modify. At the bottom of the page, there is a "Open Public Node Page" button. Click on it to see the information. The page can be embeded into your website with <iframe>.

BTCPay Checkout

Lightning Network (LND) FAQ

Here are some of the common questions about the LND implementation of the Lightning Network.

How to restart my LND?

sudo su -
docker restart btcpayserver_lnd_bitcoin

How to see LND logs?

To check the logs of your LND node in BTCPay Server (Docker installations) use the following command:

docker logs --tail 40 btcpayserver_lnd_bitcoin

You can change 40 to whatever number you wish. The number represents the lines of code that will be shown. For more information about the logs, see Troubleshooting page

What’s the default directory of LND in BTCPay?


LND connection issues after an update

Authentication tends to fail on LND after an update, symptoms are:

  • In store settings, when testing the connection to your node you get Error while connecting to the API (The HTTP status code of the response was not expected (500).)
  • In Zap wallet, Unable to connect to host: cannot retrieve macaroon: cannot get macaroon: root key with id 0 doesn’t exist

In such case, you need to delete the macaroon of lnd and restart it.

If you are using docker deployment, please connect with SSH to your VM and the following command:

sudo su -
docker exec btcpayserver_lnd_bitcoin rm /data/admin.macaroon
docker exec btcpayserver_lnd_bitcoin rm /data/invoice.macaroon
docker exec btcpayserver_lnd_bitcoin rm /data/readonly.macaroon
docker exec btcpayserver_lnd_bitcoin rm /data/data/macaroons.db
docker exec btcpayserver_lnd_bitcoin rm /data/data/chain/bitcoin/mainnet/invoice.macaroon
docker exec btcpayserver_lnd_bitcoin rm /data/data/chain/bitcoin/mainnet/macaroons.db
docker exec btcpayserver_lnd_bitcoin rm /data/data/chain/bitcoin/mainnet/readonly.macaroon
docker restart btcpayserver_lnd_bitcoin

If a macaroon does not exist, you will see an error message, you can safely ignore it.

Because this will invalidate the previous macaroons, you need to manually reconnect with Zap with Server Settings / Services / LND-gRPC.

How to change my LND Node alias?

To change the display name of your LND node, you should ssh log in into your virtual machine and apply the following:

sudo su -
cd btcpayserver-docker
export LIGHTNING_ALIAS="namehere"
. ./ -i

Lightning Network (c-lightning) FAQ

Here are some of the common questions about the c-lightning implementation of the Lightning Network.

How to find an on-chain address in Spark?

To fund your on-chain wallet in Spark, you need to get an on-chain address. To find your address, click on the version link at the left corner bottom of the Spark wallet (for example v0.2.2).

That should toggle the settings. Click > Console. To generate a new address in RPC Console field, enter newaddr for bech32 address or newaddr p2sh-segwit click execute. At the bottom you should see the newly generated address. You can also toogle help if you need help with other commands in Spark.

BTCPay Checkout BTCPay Checkout

Lightning Network Questions and Support

Community support for Lightning Network question is pretty limited, since the protocol is fairly new.

If you're facing a technical problem with your Lightning Network implementation, that's not documented here you may want to ask questions in their respective communities.

LND Support

c-lightning Support