₿ Bitcoin Core Node for Home Assistant

Monitor one or more Bitcoin Core nodes in Home Assistant using the node's local JSON-RPC API. The integration is deliberately read-only: it never accesses wallets, keys, seed phrases, signing, or transaction broadcasting.

What it provides

• Blockchain synchronization progress, height, headers, and blocks behind
• Node availability, initial block download, sync completion, and pruning state
• Peer connections, mempool size and transaction count, network, and uptime
• Optional difficulty, chain-size, and relay-fee sensors
• A Home Assistant device per configured node, with diagnostics that redact secrets

Install with HACS

Click the button above, select Download, then restart Home Assistant. Alternatively:

1. Open HACS in Home Assistant.
2. Select Integrations and use the three-dot menu to add this custom repository: https://github.com/mroxso/home-assistant-bitcoin-node.
3. Choose category Integration, download Bitcoin Core Node, and restart Home Assistant.
4. Go to Settings → Devices & services → Add integration, then select Bitcoin Core Node.

Configure Bitcoin Core safely

Keep RPC access on your local network. Do not expose port 8332 to the public internet. Create a dedicated RPC user and limit which hosts may connect. A minimal bitcoin.conf example:

server=1
rpcbind=127.0.0.1
# Add the Home Assistant IP only when it is on another machine.
rpcallowip=192.168.1.50
rpcauth=<generate-with-bitcoin-core-rpcauth-tool>

Restart Bitcoin Core after changing its configuration. In the integration setup form, enter the node host, port, generated RPC username/password, and TLS settings. The default RPC port is 8332.

For a remote Home Assistant instance, use a private network or VPN. HTTPS is supported; disabling certificate verification should only be used for a deliberately trusted, local self-signed endpoint.

Entities

Entity	Meaning
Blockchain sync progress	Bitcoin Core verification progress as a percentage
Current block height / header height / blocks behind	Chain state and header gap
Network connections	Active peer count, with inbound/outbound attributes when supplied
Mempool transactions / size	Current mempool activity
Uptime / network / pruning status	Basic node information
RPC available / IBD / synchronized / pruned blockchain	Node health binary sensors

Enable optional sensors in the integration options to show difficulty, chain size, and relay fee when your Bitcoin Core version reports them.

Troubleshooting

• Cannot connect: confirm server=1, the hostname and port, rpcbind, firewall rules, and rpcallowip.
• Invalid credentials: check the dedicated RPC username/password or rpcauth entry and restart Bitcoin Core after editing bitcoin.conf.
• TLS error: use a certificate Home Assistant can validate, or explicitly choose the local-only certificate-verification override.
• Some entities are unavailable: older Bitcoin Core versions and disabled features may omit optional RPC fields; the essential chain and network entities remain available.

Development

Run tests in a Home Assistant development environment:

pytest
ruff check .

This project is a monitoring integration only. It does not manage Bitcoin Core, wallets, or funds.