Bitweb API Server

REST + WebSocket backend for the Bitweb wallet. Bridges HTTP/WS clients to an ElectrumX node over TLS, providing address balances, UTXO sets, transaction history, and real-time push notifications via Socket.IO.

---

Architecture

Browser / Wallet
│ REST + Socket.IO
▼
Nginx (TLS termination, rate limiting)
│ HTTP proxy
▼
Gunicorn + gevent (app.py → server/)
│ ElectrumX JSON-RPC over TLS
▼
ElectrumX node (electrumx.example.com:20002)

The server maintains:

• Connection pool (ElectrumPool) — N parallel persistent TLS connections to ElectrumX, used for all REST calls.
• Subscriber (ElectrumSubscriber) — one dedicated persistent connection for server-push notifications (new blocks, scripthash changes).
• In-memory caches — coinbase cache, TX cache, history cache, tip-height cache; all bounded and self-evicting.

---

API Endpoints

Method	Path	Description
GET	/info	Current block height
GET	/balance/<address>	Confirmed + unconfirmed balance (satoshis)
GET	/unspent/<address>	UTXO list. Optional: ?amount=<min_sat>?confirmed=true
GET	/history/<address>	Last N txs with direction/amount. Optional: ?limit=<n> (max 50)
GET	/tx/<txid>	Verbose transaction (vout includes value_sat)
GET	/rawtx/<txid>	Raw transaction hex
GET	/fee	Fixed fee rate (satoshis)
POST	/broadcast	Broadcast raw tx hex (form field raw or raw body)

Response envelope

{ "error": null, "id": "api-server", "result": { ... } }
{ "error": { "code": 400, "message": "..." }, "id": "api-server", "result": null }

WebSocket (Socket.IO)

Connect to wss://api.example.com/socket.io/.

Client → Server

socket.emit("subscribe",{address: "WxxxYour address here"})

Server → Client

Event	Payload
subscribed	{ address }
balance_changed	{ balance, confirmed, unconfirmed, pending_out, utxos[], height }
block	{ height }
error	{ message }

---

Requirements

System

• OS: Ubuntu 22.04 / 24.04 LTS (or any systemd-based Linux)
• Python: 3.10 or newer
• Nginx: 1.18+ (for TLS termination and rate limiting)
• Certbot: for Let's Encrypt certificates (optional but recommended)

Python packages

Listed in requirements.txt:

flask
flask-cors
flask-socketio
gevent
gevent-websocket
bech32
base58
gunicorn
python-dotenv

---

Install

1. Create a dedicated user

sudo useradd -r -m -s /bin/bash bitweb

2. Clone / copy the project

sudo mkdir -p /opt/bitweb-api
sudo cp -r . /opt/bitweb-api/
sudo chown -R bitweb:bitweb /opt/bitweb-api

3. Create a virtual environment and install dependencies

cd /opt/bitweb-api
python3 -m venv venv
venv/bin/pip install --upgrade pip
venv/bin/pip install -r requirements.txt

4. Configure environment variables

Copy the example and edit:

sudo cp /opt/bitweb-api/env.example /opt/bitweb-api/.env
sudo nano /opt/bitweb-api/.env
sudo chown bitweb:bitweb /opt/bitweb-api/.env
sudo chmod 600 /opt/bitweb-api/.env

See Configuration for all available variables.

5. Create the systemd service

sudo nano /etc/systemd/system/bitweb-api.service

[Unit]Description=Bitweb API Server
After=network.target
[Service]User=bitweb
Group=bitweb
WorkingDirectory=/opt/bitweb-api
EnvironmentFile=/opt/bitweb-api/.env
Environment="PATH=/opt/bitweb-api/venv/bin"ExecStart=/opt/bitweb-api/venv/bin/gunicorn \
--bind 127.0.0.1:21223 \
--worker-class gevent \
--workers 1 \
--timeout 0 \
--keep-alive 75 \
app:app
Restart=on-failure
RestartSec=5s
[Install]WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now bitweb-api
sudo systemctl status bitweb-api

6. Configure Nginx

See the included api2.bitwebcore.example for a production-ready Nginx config. Replace api.example.com with your domain.

sudo cp api2.bitwebcore.example /etc/nginx/conf.d/bitweb-api.conf
# edit domain
sudo nginx -t && sudo systemctl reload nginx

7. Obtain a TLS certificate (Let's Encrypt)

sudo certbot --nginx -d your.domain.com

---

Configuration

All settings are read from a .env file in the project root (via python-dotenv).

Variable	Default	Description
SECRET_KEY	change-me-in-production	Flask session secret — change this
HOST	0.0.0.0	Bind address (Gunicorn listens here)
PORT	21223	Bind port
DEBUG	false	Flask debug mode — never enable in production
ELECTRUM_HOST	electrumx.example.com	ElectrumX hostname
ELECTRUM_PORT	20002	ElectrumX TLS port
ELECTRUM_TIMEOUT	15	Per-call timeout in seconds
ELECTRUM_VERIFY_SSL	true	Set false only for self-signed certs
ELECTRUM_POOL_SIZE	4	Number of parallel ElectrumX connections
FIXED_FEE_SATOSHIS	10000	Reported fee rate from /fee

Example .env

SECRET_KEY=replace-with-a-long-random-stringHOST=0.0.0.0PORT=21223DEBUG=falseELECTRUM_HOST=electrumx.example.comELECTRUM_PORT=20002ELECTRUM_TIMEOUT=15ELECTRUM_VERIFY_SSL=trueELECTRUM_POOL_SIZE=4FIXED_FEE_SATOSHIS=10000

Security note:.env contains secrets. It is owned by the service user (bitweb) with mode 600 and must never be committed to version control. Add .env to .gitignore.

---

Running

Via systemd (production)

sudo systemctl start bitweb-api
sudo systemctl stop bitweb-api
sudo systemctl restart bitweb-api
sudo systemctl status bitweb-api

Logs

sudo journalctl -u bitweb-api -f # follow live
sudo journalctl -u bitweb-api -n 100 # last 100 lines
sudo journalctl -u bitweb-api --since today

Development (local)

python3 -m venv venv &&source venv/bin/activate
pip install -r requirements.txt
cp env.example .env # edit as needed
python3 app.py

---

Tests

python3 test_address.py

Tests cover base58check decoding, all version bytes (mainnet/testnet P2PKH and P2SH), bech32 P2WPKH/P2WSH with the web HRP, and script-hash derivation.

---

Project Structure

.
├── app.py Entry point (gevent monkey-patch + gunicorn target)
├── requirements.txt Python dependencies
├── env.example Configuration template
├── server/
│ ├── __init__.py Flask app factory, SocketIO init
│ ├── rest.py All REST routes + WebSocket event handlers
│ ├── electrum.py ElectrumX client / pool / subscriber
│ ├── address.py Address → scriptPubKey / scriptHash conversion
│ ├── segwit_addr.py Bech32 / Bech32m reference implementation
│ └── utils.py JSON response helpers
├── test_address.py Unit tests for address.py
└── api.example_nginx Production Nginx config example

---

License

MIT — see LICENSE.md.