Installation

BTQ Core can be built from source on Linux, macOS, and Windows. This guide covers the Linux build process.

Requirements

System Requirements

OS: Linux (Ubuntu 20.04+), macOS 13+, or Windows 10+
RAM: 4GB minimum, 8GB recommended
Disk: 10GB for build, 50GB+ for blockchain
CPU: Multi-core recommended for faster builds

Dependencies (Ubuntu/Debian)

sudo apt-get update
sudo apt-get install -y \
  build-essential \
  libtool \
  autotools-dev \
  automake \
  pkg-config \
  bsdmainutils \
  python3 \
  libevent-dev \
  libboost-dev \
  libsqlite3-dev \
  libminiupnpc-dev \
  libnatpmp-dev \
  libzmq3-dev \
  systemtap-sdt-dev

Optional Dependencies

# For GUI (Qt)
sudo apt-get install -y \
  libqt5gui5 \
  libqt5core5a \
  libqt5dbus5 \
  qttools5-dev \
  qttools5-dev-tools

# For legacy wallet support (BDB)
sudo apt-get install -y libdb-dev libdb++-dev

Building from Source

Clone the Repository

git clone https://github.com/btq-ag/btq-core.git
cd btq-core

Generate Build System

./autogen.sh

Configure

# Standard build
./configure

# With GUI
./configure --with-gui=qt5

# Without wallet (node only)
./configure --disable-wallet

# With legacy wallet support
./configure --with-incompatible-bdb

Compile

# Use all available cores
make -j$(nproc)

Compilation takes 15-60 minutes depending on your hardware.

Install (Optional)

sudo make install

Or run directly from the build directory:

./src/btqd
./src/btq-cli

Quick Start

Start the Node

# Mainnet
btqd -daemon

# Testnet
btqd -testnet -daemon

# Regtest (for development)
btqd -regtest -daemon

Create a Wallet

btq-cli createwallet "my_wallet"

Generate a Dilithium Address

btq-cli -rpcwallet="my_wallet" getnewdilithiumaddress

Check Blockchain Status

btq-cli getblockchaininfo

Configuration

Data Directory

OS	Path
Linux	`~/.btq/`
macOS	`~/Library/Application Support/BTQ/`
Windows	`%APPDATA%\BTQ\`

Configuration File

Create btq.conf in your data directory:

# Network
server=1
rpcuser=btqrpc
rpcpassword=your_secure_password

# Performance
dbcache=4096
maxconnections=125

# Pruning (optional, saves disk space)
# prune=550

Network Ports

Network	P2P Port	RPC Port
Mainnet	9333	8332
Testnet	19333	18332
Signet	38333	38332
Regtest	19444	18443

For the full port reference including Tor onion service ports, see Architecture — Ports.

Running Modes

Full Node

btqd -daemon

Validates all blocks and transactions. Requires full blockchain (~50GB+).

Pruned Node

btqd -prune=550 -daemon

Keeps only recent blocks. Minimum 550MB.

Regtest (Development)

btqd -regtest -daemon

Private network for testing. Mine blocks instantly:

btq-cli -regtest generatetoaddress 101 "$(btq-cli -regtest getnewaddress)"

Verify Installation

Check Version

btqd --version
# BTQ Core version v0.1.0

btq-cli --version
# BTQ Core RPC client version v0.1.0

Test Dilithium

# Start regtest
btqd -regtest -daemon

# Create wallet
btq-cli -regtest createwallet "test"

# Generate Dilithium address (returns a JSON object; P2MR addresses read qcrt1z... on regtest)
btq-cli -regtest -rpcwallet="test" getnewdilithiumaddress
# Should return: {"address":"qcrt1z...","p2mr_id":"...","scriptPubKey":"...","merkle_root":"..."}

# Sign a message
btq-cli -regtest -rpcwallet="test" signmessagewithdilithium \
  "qcrt1z..." \
  "Hello BTQ!"
# Should return: base64 signature (~3KB)

Troubleshooting

Build Errors

Missing dependencies:

# Re-run dependency installation
sudo apt-get install -y build-essential libtool autotools-dev automake

Configure fails:

# Clean and retry
make distclean
./autogen.sh
./configure

Runtime Errors

Port already in use:

# Check for existing processes
pgrep -a btqd
# Kill if needed
pkill btqd

RPC connection refused:

# Ensure server=1 in btq.conf
# Check RPC credentials match

Disk space:

# Check available space
df -h ~/.btq
# Consider pruning
btqd -prune=550

Next Steps

Wallet Basics - Managing keys and transactions
Dilithium Overview - Understanding quantum resistance
RPC Reference - Full API documentation

Installation

On this page