# BTCPay Wallet FAQ

This document contains frequently asked questions and solutions to common issues regarding internal or external wallets you're using with or within BTCPay.

# What is BTCPay wallet?

BTCPay has an internal wallet which you can use to see the transactions and even send the money out of it. The wallet works only with a supported hardware wallet, like Ledger Nano S.

You'll have to confirm and sign the transaction on your hardware wallet. BTCPay wallet is not a hot wallet. The private keys are secured inside your hardware wallet.

# What is wallet re-scan in BTCPay?

The Rescan feature is best explained in a real-life situation:

  • You use a wallet outside of BTCPay (for example Ledger Nano S with the Ledger Live app)
  • You receive a payment worth 1BTC to your Nano S wallet.
  • After a while you decide to add the xpubkey you use with your Ledger to your BTCPay Server. You add this xpub as a derivation scheme in your Store.
  • You then find out that BTCPay has no information about transaction A, and shows 0 BTC balance while Ledger Live shows 1BTC.

This happens because when you use a new derivation scheme with your store, BTCPay Server doesn't know the past transactions of your wallet.

To solve this issue, you need to use the Rescan feature. The Rescan relies on Bitcoin Core 0.17.0's scantxoutset to scan the current state of the blockchain (called UTXO Set) for coins belonging to your derivation scheme. Once the scan is complete, BTCPay Server will show the correct balance, along with some of past transactions of your wallet.

We highly recommend you to use an internal wallet in case you need to double-check the transaction. If you wish to use an external wallet, here are our recomendations:

  • Electrum - desktop wallet
  • Ledger Nano S - hardware wallet (other hardware wallets should be added at some point)
  • Zap - Lightning Network LND wallet
  • Spark - Lightning Network c-lightning wallet
  • Sentinel - Watch-only on-chain wallet for Android
  • ArcBit / bitWallet - Watch-only on-chain wallet for Android

# How to connect my wallet to BTCPay Server?

The process of connecting a wallet to your BTCPay server is the same for both third-party or self-hosted deployments. Your private keys are never uploaded nor required by the BTCPay Server. You’re only uploading the xpubkey.

There are two ways to connect your BTCPay and your wallet:

  1. Automatic with Ledger Nano S hardware wallet
  2. Manual with any wallet supporting xpubkey (Electrum highly recommended)

Watch the video below or read this article for step by step instructions.

# Missing payments in my software or hardware wallet

If your internal BTCPay wallet is showing the transactions and you do not see the funds on your desktop, mobile or hardware wallet, you need to increase the gap limit of the external wallet you're using. Do not worry, your funds are safe, they're just not showing yet.

Most wallets, have a gap limit of 20. This means that after 20 consecutive unpaid invoices, wallet will stop fetching the transactions beyond that and won't show them. The solution is to increase the gap limit. Not all wallets have this feature.

For that reason, it's highly recommended that you use Electrum wallet. To set increase the gap limit in Electrum, follow this video

Enter following commands in Electrum console:


Restart your Electrum and verify that the newly set gap limit is correct by entering:


There's no good answer to how much you should set the gap limit to. Most merchants set 100-200. If you're a big merchants with high transaction volume, you can try with an even higher gap limit.

Be aware that :

  • A higher gap limit may slow down the performance of your wallet
  • Not all wallets support the increased gap limit. If you import an Electrum recovery seed into another wallet, you may not see all the funds again.

When an invoice is created in BTCPay, it does it for all coins you have setup. You may want to increase the gap limit for altcoins as well in their supported wallets.

If you do not see your funds yet, you may have set up your derivation scheme incorrectly.

# Why is my Ledger not detected by BTCPay Server?

Check that you are running the Ledger app with a version equal or above 1.2.4. Make sure to use Google Chrome. Plug your Ledger Nano S into your PC. Enter the PIN, and select the coin wallet app, for example > Bitcoin. Try refreshing the browser.

If the problem persists, contact the owner of the BTCPay Server: The reverse proxy of the BTCPay server hosting BTCPay might not support Websockets.

To confirm this is the issue, create a new invoice and go on its checkout page, you can also go on your store's "Wallet" page. You should then see this error in the Javascript console:

WebSocket connection to ‘wss://pay.example.com/i/4yhCmpWxJcHfVG3rV4EmEu/status/ws’ failed: Error during WebSocket handshake: Unexpected response code: 404

To fix the situation, if your reverse proxy is nginx, make sure that the following is included at the top of /etc/nginx/conf.d/default.conf :

# If we receive Upgrade, set Connection to "upgrade"; otherwise, delete any
# Connection header that may have been passed to this server
map $http_upgrade $proxy_connection {
  default upgrade;
  '' close;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $proxy_connection;

Then restart nginx.

/etc/init.d/nginx reload

# Receiving address in Zap and Electrum is different?

Zap and Electrum are two different wallets. Zap is for Lightning Network and Electrum is for on-chain transactions. They are unrelated and use different private keys. Use Electrum or internal BTCPay wallet to check your on-chain payments and Zap for your Lightning Network payments.

In the future, there will be wallets merging both on-chain and off-chain transactions into one, but for now, you have to use them separately.

# Can I see my payments on mobile?

If you wish to follow your on-chain payments on a mobile device, you can use a watch-only wallet like Sentinel for Android and bitWallet or ArcBit for iOS. Watch-only wallets allow xpub import and don't require the private key.

# What is a derivation scheme?

In order to receive payments to your BTCPay, you need to connect a wallet in your Store Settings by providing an xpubkey generated by your own wallet software. BTCPay uses what is called a derivation scheme to represent the destination of the funds received by your invoices. The destination of those funds will be your wallet, located by the xpubkey that you provide.

Using different derivation schemes with your xpub, you can also choose to create various receiving address types, shown in your store invoices.

Address Type Example
P2WPKH xpub...
P2SH-P2WPKH xpub...-[p2sh]
P2PKH xpub...-[legacy]
Multi-sig P2WSH 2-of-xpub1...-xpub2...
Multi-sig P2SH-P2WSH 2-of-xpub1...-xpub2...-[p2sh]
Multi-sig P2SH 2-of-xpub1...-xpub2...-[legacy]