---

name: bitcoin-privacy-tor description: | Bitcoin over Tor: Tor v3 hidden services, onion-only nodes, bitcoind torcontrol integration, Lightning over Tor. USE WHEN: hardening node privacy, configuring onion-only setups, debugging Tor + bitcoind interaction. allowed-tools: Read, Grep, Glob

Bitcoin over Tor

Bitcoin Core has built-in support for routing P2P traffic over Tor. Both inbound and outbound. Same for Lightning impls.

Configuration (bitcoind)

proxy=127.0.0.1:9050
listen=1
listenonion=1
torcontrol=127.0.0.1:9051
torpassword=...           # OR cookie auth
externalip=...           # auto-discovered via Tor v3 hidden service

# Onion-only: drop all clearnet
onlynet=onion

bitcoind connects to Tor's controlport, creates a Tor v3 hidden service automatically, advertises it via gossip.

tor is no longer accepted as a network name: Bitcoin Core 31.0 (April 2026) removed it, having deprecated it in favour of onion back in v0.17.0. Write onlynet=onion, never onlynet=tor.

Tor v3 only

BIP155 addrv2 introduced support for Tor v3. Tor v2 deprecated by Tor project + Bitcoin Core.

Format: 56-character .onion (Tor v3 vs the older 16-char v2).

Lightning over Tor

LND, CLN, LDK all support Tor:

• Inbound via tor.v3=true or similar config.
• Outbound: SOCKS5 to Tor proxy.
• Hidden service for receiving connections + invoices via private routes.

Privacy benefit

• IP address concealment — peers don't learn your IP.
• Geographic concealment — no inferring location.
• Censorship resistance — Tor circumvents IP-based blocks.

Private broadcast (Core 31.0+)

Bitcoin Core 31.0 (April 2026) added -privatebroadcast. Transactions submitted via sendrawtransaction are broadcast over short-lived connections through the Tor or I2P networks, without entering the local mempool first:

privatebroadcast=1

Two gains: recipients never learn the originator's IP, and two otherwise unrelated txs are not linkable, because a separate connection is used per transaction.

• getprivatebroadcastinfo lists txs currently being privately broadcast; abortprivatebroadcast drops them from the queue.
• A separate connection is not by itself a separate Tor circuit: bitcoind warns at startup when -proxyrandomize is disabled that private-broadcast circuits may be correlated with other connections over Tor. Keep -proxyrandomize=1 (the default).
• Wallet-submitted transactions are not affected by the option.
• Incompatible with -connect; bitcoind refuses to start if neither Tor nor I2P is reachable.

Run 31.1 or later. A disclosure of 6 June 2026 ("Private Broadcast May Reveal Sender IP Address in Bitcoin Core 31.0", credited to Eugene Siegel) describes an IP leak in 31.0: when private broadcast picks an IPv4/IPv6 peer advertising BIP324 v2 transport and the v2 handshake fails, the v1 retry does not go through the proxy and connects directly, revealing the originator's IP to the recipient. Onion and I2P peers are out of scope, as is the wallet broadcast path — and so is any node that cannot make direct clearnet outbound connections in the first place (onlynet=onion or a global proxy=). Upstream workarounds for a node stuck on 31.0: -privatebroadcast=0, -v2transport=0, or -proxy=127.0.0.1:9050 so IPv4/IPv6 outbound is proxied too. Fixed in 31.1 (8 July 2026), PRs #35032 and #35410.

Privacy gotchas

• Tx broadcast leaks if you broadcast a tx to a random peer that knows your IP. With onlynet=onion, all P2P over Tor → no leak.
• Block download also goes over Tor → slower IBD.
• DNS leak if proxy is set but DNS queries go elsewhere → use dns=0 and pre-bootstrap nodes via addnode=.
• Time correlation — even over Tor, tx timing can leak info. Mitigation in Core is -privatebroadcast (31.0+, see above). Dandelion++ (BIP156) was never merged into Core and the BIP is marked Closed in the BIPs repo (as of September 2026).

Performance

• Tor v3 hidden service: ~50-100 ms RTT typical.
• IBD over Tor: ~2-3x slower than clearnet.
• Lightning channel ops: minor latency hit.

I2P alternative

Bitcoin Core supports I2P via SAM:

i2psam=127.0.0.1:7656

Less common than Tor but provides a different network.

CJDNS

Mesh-network IPv6 (fc00::/7). Bitcoin nodes can reach each other without exiting to clearnet:

cjdnsreachable=1

Niche; mostly used by experimental peer-to-peer enthusiasts.

Common bugs

• Forgetting listenonion=1 → no inbound from Tor peers.
• Mixing clearnet + Tor without onlynet=onion → mixed routing.
• Tor circuit failures cause peer drops; bitcoind retries automatically.
• externalip= set incorrectly → wrong gossip advertisement.

See also

• ../../core/operations/SKILL.md
• ../../protocol/p2p/SKILL.md
• dandelion/SKILL.md