Skip to main content

​
Overview

Bitcoin Core can run as a Tor onion service and connect to other onion services, providing enhanced privacy and resistance to network surveillance. Tor routes your traffic through multiple relays, making it difficult to trace your connection origin.
Starting with Bitcoin Core 22.0, only Tor v3 addresses are supported. Tor v2 addresses are ignored and neither relayed nor stored.

​
Quick Start

1

Install Tor

Install Tor on your system:
# Debian/Ubuntu
sudo apt install tor

# macOS
brew install tor
2

Start Tor Service

sudo systemctl start tor
sudo systemctl enable tor
3

Run Bitcoin Core Behind Tor

bitcoind -proxy=127.0.0.1:9050
This configuration anonymizes all outbound Bitcoin connections through the Tor network.

​
Compatibility

  • Bitcoin Core 22.0+: Tor v3 only
  • Tor 0.4.6+: v2 support removed
  • Recommended Tor version: 0.4.6 or later
Tor v2 addresses are no longer supported. Ensure you’re using Tor v3 addresses ending in .onion (56 characters).

​
Configuration Methods

There are three main ways to configure Tor with Bitcoin Core:

​
1. Run Behind a Tor Proxy

The simplest method - route all connections through Tor: 
bitcoind -proxy=127.0.0.1:9050
Configuration options: 
# Generic proxy (used for all networks including .onion)
-proxy=ip[:port]

# Tor-specific proxy
-proxy=ip[:port]=tor
# or
-onion=ip[:port]

# Explicitly disable onion access
-onion=0
# or
-noonion
The Tor Browser Bundle uses port 9150 by default, while system Tor installations typically use port 9050.

​
UNIX Domain Sockets

You can use UNIX domain sockets for proxy connections: 
bitcoind -onion=unix:/home/user/torsocket

​
2. Automatic Onion Service

Bitcoin Core can automatically create ephemeral onion services using Tor’s control socket API.
1

Configure Tor Control Port

Edit /etc/tor/torrc and add/uncomment:
ControlPort 9051
CookieAuthentication 1
CookieAuthFileGroupReadable 1
DataDirectoryGroupReadable 1
2

Restart Tor

sudo systemctl restart tor
3

Configure Permissions (if needed)

If you see authentication errors:
# Find Tor group
getent group | cut -d: -f1 | grep -i tor

# Add user to Tor group
sudo usermod -a -G debian-tor $USER

# Restart computer or log out/in
4

Enable in Bitcoin Core

bitcoind -proxy=127.0.0.1:9050 -listen -debug=tor
Configuration options: 
# Enable/disable onion service creation
-listenonion=1  # default when -listen is set
-listenonion=0  # disable

# Tor control settings
-torcontrol=127.0.0.1:9051
-torpassword=yourpassword

​
Authentication Methods

Cookie Authentication (recommended): Automatic if the user running bitcoind has read access to Tor’s cookie file (/run/tor/control.authcookie). Password Authentication: 
# Generate hashed password
tor --hash-password mypassword

# Add to /etc/tor/torrc
HashedControlPassword 16:872860B76453A77C...

# Use in Bitcoin Core
bitcoind -torpassword=mypassword

​
3. Manual Onion Service

Create a persistent onion service manually:
1

Configure Tor

Add to /etc/tor/torrc:
HiddenServiceDir /var/lib/tor/bitcoin-service/
HiddenServicePort 8333 127.0.0.1:8334
Virtual port (8333) should match Bitcoin’s P2P port. Target address (127.0.0.1:8334) is where Tor forwards connections.
2

Restart Tor

sudo systemctl restart tor
3

Get Your Onion Address

sudo cat /var/lib/tor/bitcoin-service/hostname
Example output: 7zvj7a2imdgkdbg4f2dryd5rgtrn7upivr5eeij4cicjh65pooxeshid.onion
4

Run Bitcoin Core

bitcoind -proxy=127.0.0.1:9050 \
  -externalip=7zvj7a2imdgkdbg4f2dryd5rgtrn7upivr5eeij4cicjh65pooxeshid.onion \
  -listen

​
Advanced Configuration

​
Tor-Only Mode

Connect exclusively to Tor peers: 
bitcoind -onlynet=onion -proxy=127.0.0.1:9050
Using -onlynet=onion may make your node more susceptible to Sybil attacks. Consider combining with other networks for better security.

​
Dual-Stack Configuration

Run reachable from both Tor and clearnet: 
# Allow discovery of clearnet addresses
bitcoind -proxy=127.0.0.1:9050 \
  -externalip=your.onion.address \
  -discover
Dual-stack nodes help strengthen the Bitcoin network but may allow traffic analysis to correlate your clearnet and Tor identities.

​
Tor for Onion Access Only

Use Tor only for .onion addresses, clearnet for others: 
bitcoind -onion=127.0.0.1:9050 \
  -externalip=your.onion.address \
  -discover

​
Bind to Specific Interface

Prevent clearnet connections to your onion-only node: 
bitcoind -proxy=127.0.0.1:9050 \
  -bind=127.0.0.1:8334=onion \
  -externalip=your.onion.address \
  -listen

​
Multiple External IPs

Advertise multiple addresses: 
bitcoind -externalip=203.0.113.5 \
  -externalip=your.onion.address
Bitcoin Core will advertise the most compatible address to each peer using heuristics.

​
Monitoring and Verification

​
Check Your Onion Address

# CLI netinfo
bitcoin-cli -netinfo

# RPC call
bitcoin-cli getnetworkinfo | grep onion

# Debug log
grep "AddLocal" ~/.bitcoin/debug.log | grep ".onion"

​
View Onion Peers

# Count of known onion addresses
bitcoin-cli -addrinfo

# Get specific onion peers
bitcoin-cli getnodeaddresses 10 "onion"

# Detailed peer info
bitcoin-cli getpeerinfo | grep -A 10 "onion"

​
Enable Tor Debug Logging

bitcoind -debug=tor
Check ~/.bitcoin/debug.log for Tor-related messages: 
tail -f ~/.bitcoin/debug.log | grep "tor:"

​
Troubleshooting

tor: Authentication cookie could not be opened (check permissions)
Solution: 
# Find Tor group
TORGROUP=$(stat -c '%G' /run/tor/control.authcookie)

# Add user to group
sudo usermod -a -G ${TORGROUP} ${USER}

# Restart or log out/in

​
Connection Issues

# Verify Tor is running
systemctl status tor

# Test Tor connectivity
curl --socks5-hostname 127.0.0.1:9050 https://check.torproject.org

# Check Bitcoin Core logs
bitcoin-cli -netinfo

​
Port Conflicts

If using Tor Browser Bundle, it may use port 9150 instead of 9050: 
bitcoind -proxy=127.0.0.1:9150

​
Privacy Recommendations

Best Practices:
  1. Dedicated onion service: Don’t add other services to the same onion address
  2. Single network: Use -onlynet=onion for maximum privacy
  3. No dual-stack: Avoid running on multiple networks if unlinkability is required
  4. Block-relay connections: Consider using block-relay-only connections for additional privacy
  5. Regular monitoring: Check connections regularly with -netinfo
Operating bridge nodes (listening on both Tor and clearnet) can be correlated through timing analysis and shared runtime characteristics. Only use bridge mode if you don’t require strict identity separation.

​
Configuration Examples

​
Maximum Privacy

bitcoin.conf
# Tor-only mode
proxy=127.0.0.1:9050
onlynet=onion
listen=1
listenonion=1
debug=tor

​
Bridge Node

bitcoin.conf
# Accessible via both Tor and clearnet
proxy=127.0.0.1:9050
externalip=your.onion.address
listen=1
discover=1

​
Automatic Ephemeral Service

bitcoin.conf
proxy=127.0.0.1:9050
listen=1
listenonion=1
torcontrol=127.0.0.1:9051
debug=tor

​
Performance Considerations

Tor connections are generally slower than clearnet due to routing through multiple relays:
  • Latency: 3-10x higher than direct connections
  • Bandwidth: Limited by slowest relay in circuit
  • Initial sync: Significantly slower, consider using clearnet initially
For faster initial blockchain download, sync over clearnet first, then switch to Tor-only mode.

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us