About TOR and BTCPay Server

BTCPay Server
4 min readFeb 28, 2019

Tor, without privacy

Why we can’t claim privacy for BTCPay Server even if TOR is supported

We received lot’s of demand to make BTCPay Server work with TOR.
It turns out that I was opposed to it for a simple reason:

Having a false sense of privacy is more dangerous than having no privacy and knowing about it.

Now, BTCPay Server is plugging together lot’s of services which are beyond our control. This is kind of safe as BTCPay Server does not handle any private key.

But since we support Lightning, BTCPay still have access to a hot wallet so support of third party services (services like Ride the Lightning, Spark, Charge, or Jeff’s plugins) is a bit more dangerous. A bad plugin might compromise your lightning wallet, and there is no way around that as long as there is no hardware wallet support for lightning. This is why there is big scary warning for lightning users inside BTCPay Server. At this stage, put in Lightning only what you can afford to lose and not give a fuck about it.

I myself pushed a version of Ride the Lightning which could have been used to compromise your lightning wallet (fixed by this commit). Luckily I noticed it within a few hour after the new version push. I reverted Ride the Lightning support until the fix was included in the latest docker image.
Such systemic risk is the reason why there is no auto update in BTCPay: Do not update if you don’t care about a new feature and things run well.

Using TOR for privacy in an app is even harder than making sure your wallet is not compromised. As a developer, you need to be careful that all the code paths sending HTTP requests in your application forward the request to the SOCKS proxy. Any mistake, and you are leaking DNS queries and information which can be used to expose you. And because we don’t control all plugins and third party code interacting with BTCPay, we can’t ensure any guarantee.

We could theoretically limit the third party services we rely to, but even in BTCPay Server code we are depending on a third party library to fetch the rates which does not allow setting up the proxy. And even if we could, I would be too stressed about the slightest mistake. The services allowed by BTCPay Server are quite wide and we need to do HTTP requests for lot’s of reasons.

Good privacy can be achieved by routing all traffic outgoing from a machine through a router that tunnel it through TOR or VPN. How to do this for your case is outside of my reach, find a good opsec guy to advise you properly.

Still, we want to add TOR support

Despite of this, I decided to work on TOR support (still work in progress) and the main reason is ease of use.

Right now, when you setup BTCPay Server you need:

  • Opening the firewall to accept incoming traffic through several ports (lightning, HTTP, HTTPS)
  • Configuring the NAT to route to your machine
  • Setup a DNS name so we can get you HTTPS certificate
  • Have a fixed IP for lightning

While all of those are quite easy when you setup BTCPay Server on a VPS like LunaNode, Digital Ocean or anything else, it is far from easy when you want to setup BTCPay Server in your home or office.

  • Office policies might not allow you to configure the NAT
  • Your ISP might give you a dynamic IP (temporarily solvable via dynDNS, until they reach Let’s encrypt quotas)
  • Many thing can go wrong
  • You might not have the technical skills to do it

Casa Hodl tried to solve this with proper documentation and good UX for troubleshooting those issues, but my guess is that a significant part of their support time is spent on supporting people not managing to setup their node.
At BTCPay Server the majority of our issues and questions are about this.

Supporting TOR allows us to fix all those issues in one shot.
If BTCPay Server is shipped on a raspberry PI, one can just plug it to the local network (just direct plug ethernet cable to the router) and have a way to access it with zero configuration. This is good enough for any point of sale system.

If you still need HTTPS, we can then propose lightweight reverse proxy routing HTTPS requests to the TOR address. (The dirtiest cheapest offer on any VPS would be good enough for this)

Lastly, we expect in the future that some third party services will only work with TOR (for example if Wasabi wallet one day release a deamon or pay to endpoint)


Expect advances on TOR solution with BTCPay Server for improving setup experience when you physically host it.
However, do not expect it to have perfect privacy, clear HTTPS/HTTP/DNS requests leaks to your ISP, as we can’t guarantee you anything more.