Configuration Reference

This reference is generated from every command-line option registered by the standard Bitcoin build of BTCPay Server. Use the same application version that you deploy because options and defaults can change between releases. Some advanced settings are available only through configuration providers and are documented with the feature that consumes them.

Configuration-file keys, environment variables, and command-line options feed the same configuration system. Environment variables use the BTCPAY_ prefix. Legacy compatibility options are intentionally omitted.

The maintainer guide explains how to run the pre-release check and regenerate this page.

Process and network

Command line	Configuration file	Environment	Description
-? \| -h \| --help	N/A	N/A	Show help information
-n \| --network	network	BTCPAY_NETWORK	Set the network among (mainnet,testnet,regtest) (default: mainnet)
--chains \| -c	chains	BTCPAY_CHAINS	Chains to support as a comma separated. Default to empty if --nodefaultchain is set (default: btc; available: btc)
--nodefaultchain \| -nodefaultchain	nodefaultchain	BTCPAY_NODEFAULTCHAIN	Allow BTCPay to start without any chain enabled (default: false)
-c \| --conf	conf	BTCPAY_CONF	The configuration file
-p \| --port	port	BTCPAY_PORT	The port on which to listen
-b \| --bind	bind	BTCPAY_BIND	The address on which to bind
-d \| --datadir	datadir	BTCPAY_DATADIR	The data directory

Database

Command line	Configuration file	Environment	Description
--postgres	postgres	BTCPAY_POSTGRES	Connection string to a PostgreSQL database
--explorerpostgres	explorerpostgres	BTCPAY_EXPLORERPOSTGRES	Connection string to the postgres database of NBXplorer. (optional, used for dashboard and reporting features)

HTTP and security

Command line	Configuration file	Environment	Description
--nocsp	nocsp	BTCPAY_NOCSP	Disable CSP (default false)
--rootpath	rootpath	BTCPAY_ROOTPATH	The root path in the URL to access BTCPay (default: /)
--disable-registration	disable-registration	BTCPAY_DISABLE-REGISTRATION	Disables new user registrations (default:true)
--xforwardedproto	xforwardedproto	BTCPAY_XFORWARDEDPROTO	If specified, set X-Forwarded-Proto to the specified value, this may be useful if your reverse proxy handle https but is not configured to add X-Forwarded-Proto (example: --xforwardedproto https)

Host and external services

Command line	Configuration file	Environment	Description
--externalservices	externalservices	BTCPAY_EXTERNALSERVICES	Links added to external services inside Server Settings / Services under the format service1:path2;service2:path2.(default: empty)
--btcpayhostenabled	btcpayhostenabled	BTCPAY_BTCPAYHOSTENABLED	Enable the btcpay-host integration (default: false)
--btcpayhostexecutable	btcpayhostexecutable	BTCPAY_BTCPAYHOSTEXECUTABLE	Path to the btcpay-host executable (default: btcpay-host)
--torrcfile	torrcfile	BTCPAY_TORRCFILE	Path to torrc file containing hidden services directories (default: empty)
--torservices	torservices	BTCPAY_TORSERVICES	Tor hostnames of available services added to Server Settings (and sets onion header for btcpay). Format: btcpayserver:host.onion:80;btc-p2p:host2.onion:81,BTC-RPC:host3.onion:82,UNKNOWN:host4.onion:83. (default: empty)
--socksendpoint	socksendpoint	BTCPAY_SOCKSENDPOINT	Socks endpoint to connect to onion urls (default: empty)
--updateurl	updateurl	BTCPAY_UPDATEURL	Url used for once a day new release version check. Check performed only if value is not empty (default: empty)

Logging and diagnostics

Command line	Configuration file	Environment	Description
--debuglog	debuglog	BTCPAY_DEBUGLOG	A rolling log file for debug messages.
--debugloglevel	debugloglevel	BTCPAY_DEBUGLOGLEVEL	The severity you log (default:information)

Development

Command line	Configuration file	Environment	Description
--cheatmode	cheatmode	BTCPAY_CHEATMODE	Add some helper UI to facilitate dev-time testing (Default false)

Chain services

The generated options use Bitcoin (BTC) as the chain prefix. Builds that include other chains use the same setting names with btc replaced by the lowercase crypto code in command-line and configuration-file keys, and by the uppercase crypto code in environment variables. For example, Litecoin's explorer URL is --ltcexplorerurl, ltc.explorer.url, or BTCPAY_LTCEXPLORERURL.

Chain	Crypto code
Bitcoin	BTC
Bitcoin Gold	BTG
Dash	DASH
Dogecoin	DOGE
Groestlcoin	GRS
Liquid Bitcoin	LBTC
Litecoin	LTC
Monacoin	MONA

Only configure chains included in the deployed build and its NBXplorer instance. Not every chain supports every Lightning-specific setting.

Command line	Configuration file	Environment	Description
--btcexplorerurl	btc.explorer.url	BTCPAY_BTCEXPLORERURL	URL of the NBXplorer for BTC (default: http://127.0.0.1:24444/)
--btcexplorercookiefile	btc.explorer.cookiefile	BTCPAY_BTCEXPLORERCOOKIEFILE	Path to the NBXplorer cookie file (default: the network data directory)
--btclightning	btc.lightning	BTCPAY_BTCLIGHTNING	Easy configuration of lightning for the server administrator: Must be a UNIX socket of c-lightning (lightning-rpc) or URL to a charge server (default: empty)
--btcexternallndgrpc	btc.external.lndgrpc	BTCPAY_BTCEXTERNALLNDGRPC	The LND gRPC configuration BTCPay will expose to easily connect to the internal lnd wallet from an external wallet (default: empty)
--btcexternallndrest	btc.external.lndrest	BTCPAY_BTCEXTERNALLNDREST	The LND REST configuration BTCPay will expose to easily connect to the internal lnd wallet from an external wallet (default: empty)
--btcexternalrtl	btc.external.rtl	BTCPAY_BTCEXTERNALRTL	The Ride the Lightning configuration so BTCPay will expose to easily open it in server settings (default: empty)
--btcexternalspark	btc.external.spark	BTCPAY_BTCEXTERNALSPARK	Show spark information in Server settings / Server. The connection string to spark server (default: empty)
--btcexternalcharge	btc.external.charge	BTCPAY_BTCEXTERNALCHARGE	Show lightning charge information in Server settings/Server. The connection string to charge server (default: empty)