This document explains the features of the internal BTCPay wallet. For frequently asked questions - check the Wallets FAQ
Note: A private key (xprv) is never required for receiving money on-chain to a BTCPay wallet. The software needs a public key (xpubkey) which is a watch-only wallet token. The xpubkey allows BTCPay to generate a new address each time a new invoice is generated. It enables users to observe the wallet balance and transactions without having to share their private key. Exception is Lightning Network which is a hot wallet with keys online.
The on-chain wallet does not generate a private key. Users have to create their own private key externally and import an xpubkey derived from the private key into Store Settings > Derivation scheme. The public key (xpubkey) can be imported from a compatible hardware wallet or added manually by pasting the key into the field and adding an appropriate suffix. For more information on how to add a derivation scheme to BTCPay, see the Recommended Wallets. If you're using a third-party host and are asked to provide a private key, it's certainly a scam. Never share your private key with anyone. It's called private for a reason.
BTCPay's internal, full-node reliant wallet that can be accessed by clicking Wallets from the top menu. The reliance on the user's own full node makes the wallet more private and secure compared to any SPV wallet.
Each store and a cryptocurrency have a separate wallet displayed on the Wallets page. To access a particular wallet, click Manage.
The wallet contains following features:
- Transactions
- Send
- Receive
- Re-scan
- PSBT
- Settings
An overview of the incoming (green), outgoing (red) and unconfirmed (greyed out) transactions displayed together with timestamps and balances, sorted by date. Users can click on the tx ID to preview the transaction on the block explorer.
The Send function allows spending of the funds from the BTCPay wallet.
To spend the funds, user is required to sign the transaction. Transaction can be signed with:
- Ledger Hardware Wallet
- HD Private key or mnemonic seed
- Wallet supporting PSBT
- Hardware Wallet (BTCPay Vault)
Ledger Nano S has a native integration and can be used to spend bitcoin and altcoins from the wallet. Both Nano S and Ledger X can be used with BTCPay Vault for smoother experience for bitcoin transactions.
Check this tutorial on how to sign a transaction with Ledger Nano S
Transactions in BTCPay's wallet can be signed with a private key or mnemonic seed. Prior to inputing the private key, make sure to set a proper AccountKeyPath in Wallet > Settings.
PSBT (Partially Signed Bitcoin transaction) is supported and can be signed with PSBT compatible wallet.
Check this tutorial on how to sign a transaction with ColdCard Hardware Wallet completely air-gaped.
BTCPay Vault is a cross-platform desktop application that makes it possible to use a wide range of hardware wallets with the BTCPay Wallet.
Check BTCPay Vault documentation for instructions on how to set up and sign with a compatible hardware wallet.
Receive tab generates an unused address which can be used to receive payments. The same can be achieved by generating an invoice (Invoices > Create new invoice).
This option is available in the Advanced mode of the Send page.
It is a privacy enhancing feature which is useful when you send to another of your own wallets or to an exchange. It makes sure that no change UTXO is created by rounding up the amount sent.
By default this feature is disabled, so if your wallet has a UTXO of 1.1 BTC and you input an amount equals to 1.0 BTC, the resulting transaction will have two outputs 0.1 BTC of change, and 1.0 BTC to your destination.
Blockchain analysis will understand that those 0.1 BTC of change belong to the same entity which controlled 1.1 BTC before, and can track the future purchase you make under the same pattern.
By enabling this feature, BTCPay Server wallet will round up the amount sent to 1.1 BTC such that no change output is sent back to you.
Warning: Despite the fact, in this example, that you entered 1.0 in the amount field, the amount that will really be sent to your destination will be 1.1 BTC.
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 the derivation scheme being used.
Wallet re-scan solves two critical problems for BTCPay users:
- Gap limit
- Importing a previously used wallet
Gap limit: Most of the wallets have the gap limit set to 20. This means that if a merchant receives 21 or more consecutive unpaid invoices, those wallets show the incorrect balance and some transactions may not be visible.
Wallet import: When users add a derivation scheme of a wallet that had transactions in the past (previously used wallet), BTCPay won't be able to show the balance and transactions from the past.
Re-scan is a feature that solves both of these problems. Once the scan is complete, BTCPay Server will show the correct balance, along with the past transactions of the wallet.
Wallet re-scan requires access to the full node which means that this function is only available for server owners.
Users who use a third party host should use a newly generated xpub key and also use an external wallet like Electrum which allows them to increase the gap limit.