What is ElectrumX?
ElectrumX is a lightweight, efficient reimplementation of an Electrum Server written in Python. It acts as a bridge between your **Bitcoin Full Node** (which holds the blockchain data) and your **Electrum Wallet** (which needs to query that data quickly).
Why run it?
By default, Electrum connects to random public servers. These servers can see your IP address and all your transaction history. By running ElectrumX, you keep this data on your own hardware.
Prerequisites
1. Hardware
SSD is mandatory. HDD syncs will be too slow. You need roughly 60-80GB of space for the ElectrumX database (in addition to the ~600GB for Bitcoin Core).
2. Bitcoin Core Configuration
You must have a running Bitcoin node (`bitcoind`). It MUST have transaction indexing enabled. Add this to your `bitcoin.conf`:
txindex=1
If you didn't have this set before, you must restart bitcoind with `-reindex`. This takes time.
3. Software Dependencies
Python 3.10 or higher is required.
sudo apt-get install python3-pip python3-dev libleveldb-dev
Installation Guide
1 Step 1: Install ElectrumX
We will install directly from the source to ensure we have the latest version.
# Clone the repository git clone https://github.com/spesmilo/electrumx.git cd electrumx # Install with pip sudo pip3 install .
2 Step 2: Generate SSL Certificates
Electrum wallets require a secure SSL connection. You must generate a self-signed certificate.
mkdir ssl cd ssl openssl genrsa -out server.key 2048 openssl req -new -key server.key -out server.csr # (Press enter through prompts) openssl x509 -req -days 1825 -in server.csr -signkey server.key -out server.crt
3 Step 3: Configuration (Environment Variables)
ElectrumX is configured via environment variables. You will typically put these in a systemd service file or a script.
- COIN=Bitcoin
- DB_DIRECTORY=/path/to/your/db (SSD location)
- DAEMON_URL=http://user:[email protected]:8332/ (Your local Bitcoin node creds)
- SERVICES=tcp://:50001,ssl://:50002 (Ports to listen on)
- SSL_CERTFILE=/path/to/ssl/server.crt
- SSL_KEYFILE=/path/to/ssl/server.key
- NET=mainnet
4 Step 4: Persistence with Systemd
To keep the server running in the background and starting on boot:
Create a file at /etc/systemd/system/electrumx.service:
[Unit] Description=ElectrumX After=network.target [Service] User=yourusername EnvironmentFile=/etc/electrumx.conf ExecStart=/usr/local/bin/electrumx_server TimeoutStopSec=30m [Install] WantedBy=multi-user.target
Note: TimeoutStopSec=30m is critical. ElectrumX takes time to flush data to disk when stopping. If systemd kills it too early, the database will corrupt.
Connecting Your Wallet
Once your server is synced (check logs with journalctl -u electrumx -f), connect your desktop wallet.
Command Line Launch:
electrum --oneserver --server localhost:50002:s
The :s tells the wallet to use SSL. Since you are using a self-signed certificate, the wallet might warn you—this is expected and safe for localhost connections.
Official Documentation
For advanced peer discovery and RPC commands:
Conclusion
You are now running a sovereign Bitcoin infrastructure. Your Electrum wallet is communicating directly with your own node via ElectrumX, ensuring no third party can spy on your addresses or balances.
Back to Tutorials
