Tor gives a BTCPay Server installation an onion service that can be reached without publishing the server’s ordinary internet address. In the standard Docker deployment, Tor services are enabled by default, helping some home and office operators avoid port-forwarding, public DNS and a fixed Lightning IP. Onion access is a routing option—not a guarantee of anonymity, leak-free plugins or an inaccessible clearnet site.
What Tor does in BTCPay Server
BTCPay Server can use Tor in two related ways. First, its standard Docker deployment includes Tor hidden services and selected Tor connectivity as part of the Bitcoin setup. The deployment FAQ says Tor is activated by default on Docker deployments; the official Docker README lists hidden services among the bundled components (Deployment FAQ; btcpayserver-docker README).
As an Amazon Associate I earn from qualifying purchases.
A hidden service gives the BTCPay instance a hostname ending in .onion. A Tor-capable browser or application connects through the Tor network instead of resolving that hostname through ordinary DNS. The result is an alternative route to the BTCPay web interface and, depending on the services enabled, to other BTCPay endpoints.
Second, BTCPay can use Tor for selected outbound or peer connections. Its Bitcoin node can have a Tor peer endpoint, and configuration options can point applications at a Tor SOCKS endpoint. The exact services and defaults depend on the deployment and version, so an installation should be checked against the documentation for the version actually running.
#1 Best Overall
- BITCOIN EXCLUSIVE, PHONE VERIFICATION: Bitkey is designed from the ground up exclusively for bitcoin — a dedicated hardware wallet for secure bitcoin storage. Approve transactions with a tap using your phone and NFC. No device screen is required.
- SELF-CUSTODY, NO EXCHANGE OR CUSTODIAN REQUIRED: You hold two of the three keys in the Bitkey system – one on your phone and one on your Bitkey device. The third is stored on Bitkey’s server and cannot move your bitcoin on its own.
- NO SEED PHRASE: Set up and use Bitkey without creating or storing a seed phrase.
- 2-of-3 MULTISIG: Three keys are stored separately across your phone, Bitkey device, and Bitkey’s server. Any two keys are required to move your bitcoin.
- BUILT-IN RECOVERY: Encrypted backup and recovery tools can help you regain access if you lose your phone or Bitkey device. You can also designate a Recovery Contact.
Why activate Tor? Does it mean that nobody knows who I am?
Tor can simplify a particular hosting problem: running BTCPay at home or in an office without exposing the same set of network details that a conventional public deployment requires. BTCPay’s FAQ specifically identifies several tasks that onion access can reduce or avoid in this use case:
- Opening inbound firewall ports to the public internet.
- Creating NAT or router redirections.
- Configuring public DNS so an HTTPS certificate can be issued for the site.
- Maintaining a fixed public IP address for Lightning connectivity.
These are documented benefits for the Docker arrangement and similar setups; they are not a promise that every BTCPay installation can dispense with all network configuration. A locally hosted server still needs reliable power, storage, backups and administration, and any clearnet services you deliberately publish still have their normal exposure.
Tor also does not make the operator anonymous. BTCPay’s documentation states: “But if you’re looking for perfect privacy and security, activating Tor with your BTCPay just won’t do it.” The warning matters because the application is more than its login page. Plugins, payment integrations, webhooks, browser behavior, server logs and administrative mistakes can reveal information or send requests over the ordinary network.
How to find the BTCPay onion address
There are two documented ways to retrieve the address. Use the server settings when you can already sign in, or read the generated hostname file when you need the address before opening the site over clearnet.
Rank #2
- Unparalleled Security: Protect your assets NDA-free EAL 6+ Secure Element, offering robust defense and complete transparency
- Simple & Secure Interface: Manage your digital assets easily with a clear OLED screen for secure on-device confirmations
- Supports 1000s of Coins & Tokens: Securely handle thousands of assets, including Bitcoin, Ethereum, and more, all in one wallet
- Effortless Asset Management: Monitor and transact seamlessly with Trezor Suite, our intuitive desktop and mobile app
- Enhanced Backup Solution: Rest assured with Multi-share Backup, eliminating single points of failure for secure cold wallet recovery
From Server Settings
- Sign in to the BTCPay Server administrator interface.
- Open Server Settings.
- Open the Services section. The reverse-proxy documentation identifies this page as the place where the Tor
.onionaddress is displayed (Reverse proxy to Tor). - Copy the complete onion hostname, including its suffix, and open it in a Tor-capable browser.
The settings page is preferable for routine administration because it shows the address generated for that instance rather than relying on a presumed file location.
From the documented Docker volume
For the standard Docker arrangement described by BTCPay, the deployment FAQ gives this command:
cat /var/lib/docker/volumes/generated_tor_servicesdir/_data/BTCPayServer/hostnameRun it on the host that runs the BTCPay Docker deployment. The command prints the hostname stored in the generated Tor services volume. The path is specific to that documented layout: custom Compose projects, renamed volumes, non-Docker installations and manually managed Tor directories may use a different location. If the file is absent, use Server Settings or inspect the deployment’s actual volume and Tor-service configuration rather than creating a file with a guessed name.
Opening the address safely
- Use a browser configured to reach onion services; an ordinary browser will not resolve a
.onionhostname through public DNS. - Enter the full hostname exactly as displayed. A single missing character produces a different, unreachable address.
- Bookmark the address only after verifying that it belongs to your server through the administrator settings or host file.
- Keep a separate record of the address and recovery credentials. Losing the generated service data can change or remove the address after a rebuild.
Standard Docker Tor versus a reverse proxy to Tor
BTCPay documents more than one operating pattern. They solve different network problems, so the advanced reverse-proxy guide should not be treated as a prerequisite for ordinary onion access.
Rank #3
- Unparalleled Security: Protect your assets with EAL 6+ Secure Element, offering robust defense and complete transparency
- Simple & Secure Interface: Manage your digital assets easily with a clear OLED screen for secure on-device confirmations
- Supports 1000s of Coins & Tokens: Securely handle thousands of assets, including Bitcoin, Ethereum, and more, all in one wallet
- Effortless Asset Management: Monitor and transact seamlessly with Trezor Suite, our intuitive desktop and mobile app
- Enhanced Backup Solution: Multi-share Backup eliminates single points of failure for secure cold wallet recovery
| Approach | What it provides | Infrastructure described by BTCPay | Best fit |
|---|---|---|---|
| Standard Docker deployment | Bundled Tor hidden services and selected Tor connectivity, with an onion address shown in BTCPay settings | The services included by the official Docker deployment; no separate VPS or public domain is required by the onion-access instructions | Operators who want private onion reachability, including some home or office hosts |
| Manual reverse-proxy-to-Tor setup | A separately configured proxy that can expose selected BTCPay payment-gateway or API traffic through a chosen public-facing arrangement | The guide lists a VPS, root access and a domain as requirements | Operators who need deliberate proxying and control over which traffic is exposed |
The reverse-proxy pattern involves more moving parts: a proxy host, DNS and certificates where clearnet access is used, firewall policy and a Tor service on the BTCPay side. It can be appropriate when an operator wants to publish only selected endpoints rather than make the whole administration surface available. It is not necessary merely to use the onion address generated by a standard Docker deployment.
What onion access does—and does not—hide
It can hide the ordinary server endpoint from onion visitors
A visitor using the onion hostname connects through Tor rather than directly addressing the server’s public IP. That can be useful when the operator does not want to publish a home or office address as the normal web endpoint. It can also avoid the need to expose the web service through a conventional inbound port.
It does not make the operator anonymous
BTCPay explicitly cautions that enabling Tor cannot guarantee that no information leaves in clear or that nobody can connect over clearnet. A merchant can still reveal identity through domain registrations, payment metadata, email, support channels, browser fingerprints, server logs, plugin requests or an intentionally published clearnet URL. Tor protects a route; it does not rewrite application behavior or operational practices.
Plugins and integrations remain part of the trust boundary
BTCPay’s service and plugin ecosystem changes over time. A plugin may call an external service, receive a webhook or process data in a way that is not covered by the onion route. Review each integration’s network behavior and data handling. If an integration requires a public callback, Tor access to the BTCPay interface alone will not satisfy that requirement.
Rank #4
- Dual-chip architecture for maximum protection: The next-gen, fully auditable TROPIC01 chip works alongside a certified EAL6+ Secure Element—completely NDA-free—to deliver radically transparent, industry-leading defense against physical attacks.
- Quantum-ready security: Get protection against future threats with the first-ever hardware wallet designed with quantum-ready architecture.
- See every detail with confidence: Our largest high-resolution color touchscreen makes it easy to navigate your assets, review transactions and manage your coins with clarity.
- Wireless freedom with encrypted Bluetooth control: Manage, buy, swap and stake securely using Trezor Suite on desktop or mobile. Qi2-compatible wireless charging keeps your Trezor powered up. No cables required—security meets convenience.
- Works seamlessly with Android, iOS and desktop: Connect wirelessly or via USB-C to your phone or computer. Manage your crypto anywhere with our companion Trezor Suite app.
Bitcoin peer-to-peer access and the P2P onion address
BTCPay’s FAQ says the Bitcoin P2P port is not exposed externally by default and that a P2P connection is available over Tor (BTCPay Server repository). That default limits unsolicited clearnet connections, but it does not make every peer safe.
Do not distribute the P2P onion service indiscriminately
BTCPay warns that sharing the Bitcoin P2P onion service with untrusted parties can let malicious peers target the node and potentially DDoS it. Treat that address as operational infrastructure, not as a public marketing URL. Share it only with peers or services you understand and monitor.
Be cautious with port 8333 on clearnet
The same guidance cautions against unsafe clearnet exposure of Bitcoin’s port 8333. If clearnet P2P access is required, limit it to a trusted LAN or use host-whitelisting firewall rules. Do not open the port broadly simply because a peer connection is not working; first determine whether the intended peers can use the Tor endpoint.
Free tools Windows power users keep installed
One-click scans. No signup required.
Configuration options and version boundaries
The BTCPay configuration reference lists several Tor-related options (Configuration Reference):
Best Value
- Effortlessly build your crypto portfolio via the all in one Ledger Wallet app: buy, sell, send, receive, swap, stake and more across popular blockchains. 15,000+ coins & tokens in a single dashboard. Keep a close eye on the market. Compare service providers. Track performance. Get timely alerts. Build your portfolio with confidence.
- Enjoy Bluetooth connectivity, iOS access, and hours of battery use with this mobile-first, secure backup signer. Freedom you can depend on.
- Genuine Check: confirm your signer is authentic during setup with the Ledger Wallet app.
- Protect your signer: keep it in mint condition at all times with a bespoke Pod or Case to avoid scratches and everyday wear and tear.
torrcfilespecifies the path to atorrcfile containing hidden-service directories.torservicessupplies Tor hostnames that are added to Server Settings and to the BTCPay onion header.socksendpointspecifies a SOCKS endpoint used to connect to onion URLs.
These names are configuration reference entries, not universal instructions to edit a file on every deployment. The reference is generated from options registered by the standard Bitcoin build and warns that settings and defaults can change. Check the reference corresponding to the deployed version, preserve a backup of the current configuration and restart only through the deployment method documented for that installation.
A practical setup and verification checklist
- Identify the deployment. Confirm whether the server uses the official Docker deployment, a custom Docker layout or a manually proxied installation.
- Confirm Tor is running. In the standard Docker case, Tor is expected to be enabled by default; custom deployments require checking their own service definitions and logs.
- Retrieve the hostname. Use Server Settings > Services, or the documented Docker-volume command when that path applies.
- Test from a Tor-capable browser. Verify that the onion page loads and that the certificate or browser security state is consistent with the onion service.
- Test the functions you actually need. Log in, open the store or payment page, and test any API or webhook separately. An onion homepage does not prove that every integration works through Tor.
- Review exposure. Check router rules, cloud firewalls, reverse-proxy routes and port 8333. Remove broad rules that are not required.
- Protect the address and service data. Restrict access to the P2P onion hostname, back up the deployment data and document how to recover the service after a host migration.
Troubleshooting common failures
The onion hostname does not load
First verify that the client is using a Tor-capable browser. Then confirm the hostname character by character against Server Settings or the host file. If the service recently moved, check that the generated Tor volume and its permissions survived the migration.
The hostname file is missing
The published path applies to the documented Docker volume layout only. List the deployment’s actual volumes and inspect its configuration, or retrieve the address from Server Settings. Do not assume that a differently named Compose project uses generated_tor_servicesdir.
Recommended Free Tools
The web interface works but an integration fails
Separate the interface test from the integration test. Payment callbacks, external APIs and plugins may require clearnet reachability or their own proxy settings. Review the integration’s endpoint requirements and the BTCPay logs before changing Tor or firewall rules.
Peers cannot connect to Bitcoin
Check whether the peer is expected to use Tor or clearnet. Avoid opening port 8333 to everyone. Use the Tor P2P endpoint for compatible peers, or apply a narrowly scoped firewall allowlist for trusted hosts on a private network.
Choosing the appropriate pattern
Choose the standard Docker onion service when the goal is straightforward private access to a self-hosted BTCPay instance and you do not need a separately managed public proxy. Consider the reverse-proxy-to-Tor design when you have the VPS, root access and domain required by that guide and need to expose only selected payment-gateway or API traffic under your own routing policy. In either case, treat Tor as one layer of network design: continue hardening accounts, plugins, backups, firewall rules and operational procedures.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
