Guidance for Exchange Deployment

Qtum Exchange Integration Guide

This guide provides comprehensive instructions for deploying and integrating Qtum into cryptocurrency exchanges, covering both traditional binary deployments and Docker-based solutions.

Quick Start: Recommended Deployment Methods

Exchanges typically use one of two deployment methods:

  1. Docker Deployment (Recommended) - Containerized, easier to maintain and scale

  2. Binary Deployment - Direct installation on host systems

Docker Deployment (Recommended for Exchanges)

Docker provides a consistent, isolated environment that simplifies deployment and maintenance. This is the preferred method for modern exchange infrastructure.

Prerequisites

  • Docker installed and running (Install Docker)

  • Sufficient disk space (minimum 100GB recommended for mainnet)

  • Stable network connection

Pull Qtum Docker Image

docker pull qtum/qtum:latest

For a specific version:

docker pull qtum/qtum:v29.1

Create Data Directory

Create a persistent directory for blockchain data and wallet:

mkdir -p /opt/qtum-data

Create Configuration File

Create /opt/qtum-data/qtum.conf:

# RPC Configuration
rpcuser=your_secure_username
rpcpassword=your_secure_password
rpcallowip=172.17.0.0/16
rpcbind=0.0.0.0:3889
server=1

# Disable staking (CRITICAL for exchanges)
staking=0

# Network
listen=1
maxconnections=125

# Logging (optional but recommended)
logtimestamps=1

# Optional: Enable for QRC20 token support
#logevents=1
#txindex=1

Start Qtum Container

Production mainnet deployment:

docker run -d \
  --name qtum-node \
  --restart unless-stopped \
  -v /opt/qtum-data:/root/.qtum \
  -p 3888:3888 \
  -p 3889:3889 \
  qtum/qtum:latest \
  qtumd

With explicit staking disabled:

docker run -d \
  --name qtum-node \
  --restart unless-stopped \
  -v /opt/qtum-data:/root/.qtum \
  -p 3888:3888 \
  -p 3889:3889 \
  qtum/qtum:latest \
  qtumd -staking=0

Verify Container Status

# Check container is running
docker ps | grep qtum-node

# View logs
docker logs -f qtum-node

# Check sync status
docker exec qtum-node qtum-cli getblockchaininfo

Using qtum-cli with Docker

# Execute commands
docker exec qtum-node qtum-cli getblockchaininfo
docker exec qtum-node qtum-cli getnewaddress ""
docker exec qtum-node qtum-cli getbalance

# Interactive shell
docker exec -it qtum-node /bin/sh

Docker Maintenance Commands

# Stop container
docker stop qtum-node

# Restart container
docker restart qtum-node

# Remove container (data persists in volume)
docker rm qtum-node

# View resource usage
docker stats qtum-node

Docker Compose (Alternative)

Create docker-compose.yml:

version: '3.8'

services:
  qtum:
    image: qtum/qtum:latest
    container_name: qtum-node
    restart: unless-stopped
    volumes:
      - /opt/qtum-data:/root/.qtum
    ports:
      - "3888:3888"
      - "3889:3889"
    command: qtumd -staking=0
    healthcheck:
      test: ["CMD", "qtum-cli", "getblockchaininfo"]
      interval: 30s
      timeout: 10s
      retries: 3

Deploy with:

docker-compose up -d

Binary Deployment

Download Prebuilt Binaries

Download the latest release from the GitHub Releases page:

Current stable version: 29.1

# Example for Linux x86_64
wget https://github.com/qtumproject/qtum/releases/download/mainnet-v29.1/qtum-29.1-x86_64-linux-gnu.tar.gz
tar -xzf qtum-29.1-x86_64-linux-gnu.tar.gz
cd qtum-29.1/bin

The bin directory contains:

  • qtumd - Qtum daemon

  • qtum-cli - Command-line interface

Compile from Source (Alternative)

If compiling from source on Ubuntu/Debian:

# Install dependencies
sudo apt update
sudo apt install build-essential cmake git \
  libboost-all-dev libssl-dev libevent-dev \
  libgmp3-dev pkg-config python3

# Clone repository (--recursive is important!)
git clone --recursive https://github.com/qtumproject/qtum.git
cd qtum
git checkout mainnet-v29.1  # Use latest stable release

# Configure with CMake
cmake -B build

# Build (use -j N for N parallel jobs)
cmake --build build -j$(nproc)

# Optional: Install binaries system-wide
sudo cmake --install build

Binaries will be in the build/src/ directory.

CMake Build Notes

Qtum 29.1 uses CMake (migrated from Autotools in Bitcoin Core 29.1):

  • Minimum CMake version: 3.22

  • Configuration: cmake -B build (creates build directory)

  • Compilation: cmake --build build

  • Installation: cmake --install build (optional)

Node Configuration

Initial Startup

./qtumd -daemon -staking=0

CRITICAL: Always use -staking=0 or set staking=0 in qtum.conf for exchange wallets.

Configuration File

Create ~/.qtum/qtum.conf:

# RPC Credentials (required for remote access)
rpcuser=exchange_user
rpcpassword=secure_random_password_here
server=1

# Disable staking (CRITICAL for exchanges)
staking=0

# Network settings
listen=1
maxconnections=125

# Optional: RPC access control
rpcallowip=127.0.0.1
#rpcallowip=10.0.0.0/8  # Allow internal network

# Optional: Enable for QRC20 tokens
#logevents=1
#txindex=1

# Optional: Logging
logtimestamps=1
logips=1

Restart the node after creating or modifying the configuration file.

Check Sync Status

./qtum-cli getblockchaininfo

Monitor the blocks and headers fields. When they match the latest block on Qtum Explorer, the node is fully synchronized.

Initial sync time: 30 minutes to 2 hours depending on network speed and hardware.

Shutdown Node

./qtum-cli stop

Critical Exchange Configuration

Why Disable Staking?

WARNING: Staking MUST be disabled for exchange wallets.

When staking is enabled:

  • Coins used for staking become locked for 500 blocks (~20 hours)

  • This creates unpredictable fund accessibility

  • Can cause failed withdrawals if staked funds are needed

  • Complicates balance accounting

Always set: staking=0

Wallet Management

Backup Wallet

Location: ~/.qtum/wallet.dat (or /opt/qtum-data/wallet.dat for Docker)

CRITICAL: Always stop the node before backing up to prevent corruption.

# Stop node
./qtum-cli stop  # or: docker stop qtum-node

# Backup wallet
cp ~/.qtum/wallet.dat /secure/backup/location/wallet-$(date +%Y%m%d).dat

# Restart node
./qtumd -daemon -staking=0  # or: docker start qtum-node

Encrypt Wallet

./qtum-cli encryptwallet "your_strong_passphrase"

Important:

  • Node automatically stops after encryption

  • MUST create a new backup after encryption

  • Encrypted wallets cannot be decrypted (only unlocked temporarily)

  • Lost passphrase = permanently lost coins

Recommendation for Exchanges:

  • Hot wallets: Do NOT encrypt (requires manual unlocking for withdrawals)

  • Cold wallets: Encrypt for additional security

Unlock Encrypted Wallet

# Unlock for 3600 seconds (1 hour)
./qtum-cli walletpassphrase "your_strong_passphrase" 3600

# Unlock for staking only (not recommended for exchanges)
./qtum-cli walletpassphrase "your_strong_passphrase" 9999999 true

Note: Unlocking is only required to send transactions. Receiving and viewing transactions works with a locked wallet.

Receiving Deposits

Generate New Address

./qtum-cli getnewaddress ""

Returns a unique address. Generate a new address for each user.

Address formats:

  • Standard (P2PKH): Starts with Q

  • Multi-signature (P2SH): Starts with M

Validate Address

./qtum-cli validateaddress "QAddress..."

Returns address validity and ownership information.

Check Received Amount

./qtum-cli getreceivedbyaddress "QAddress..." 10

The number 10 is minimum confirmations required. Returns total received by that address with at least 10 confirmations.

List All Transactions

# Recent transactions
./qtum-cli listtransactions "*" 100 0

# Parameters: account, count, skip
# count: max 100 recommended
# skip: for pagination

WARNING: This includes unconfirmed transactions. Always verify confirmations before crediting deposits.

Get Transaction Details

./qtum-cli gettransaction "transaction_id"

Check the confirmations field before crediting user accounts.

Processing Withdrawals

Send Transaction

./qtum-cli sendtoaddress "destination_address" amount "comment" "to_comment" subtractfee

Examples:

# Send 10 QTUM, fee paid by exchange
./qtum-cli sendtoaddress "QUserAddress..." 10.0 "" "" false

# Send 10 QTUM, fee deducted from amount
./qtum-cli sendtoaddress "QUserAddress..." 10.0 "" "" true

Parameters:

  • destination_address: Recipient address (must start with Q or M)

  • amount: Amount in QTUM

  • comment: Internal note (stored locally)

  • to_comment: Internal note (stored locally)

  • subtractfee:

    • true = fee deducted from amount sent

    • false = fee paid separately by sender (exchange)

Important Notes

  • Cannot specify source address - Qtum automatically selects UTXOs

  • Smart contract addresses (0x...) are rejected - Use proper Qtum addresses only

  • Transaction returns a transaction ID for tracking

Network Parameters

Transaction Fees

Recommended: 0.004 QTUM per kilobyte (400,000 satoshis/KB)

Typical transaction size: 1-2 KB

Expected fee: 0.004 - 0.008 QTUM per transaction

Configure in qtum.conf:

paytxfee=0.004

Required Confirmations

Recommended by Qtum Foundation:

  • Large amounts (>10,000 QTUM): 20 confirmations

  • Medium amounts (100-10,000 QTUM): 10 confirmations

  • Small amounts (<100 QTUM): 6 confirmations

For new exchanges or high-risk periods: Use higher confirmation requirements initially.

Minimum Withdrawal Amount

Recommended: 0.01 QTUM

This ensures transaction fees don't consume a disproportionate amount of the withdrawal.

Network Port

P2P Port: 3888 (TCP)

Requirements:

  • Must allow outbound connections on port 3888

  • Port forwarding is NOT required (incoming connections are optional)

  • Firewall should allow daemon to reach external peers

RPC Port: 3889 (TCP)

  • Only expose to trusted internal networks

  • Never expose directly to the internet

Security Best Practices

Network Security

  1. Never expose RPC port (3889) to the internet

  2. Use firewall rules to restrict RPC access to internal IPs only

  3. Use strong, random RPC credentials

  4. Consider using VPN or SSH tunnels for remote access

Wallet Security

  1. Hot Wallet:

    • Keep minimum balance needed for daily withdrawals

    • Do NOT encrypt (requires manual unlocking)

    • Regular automated backups

    • Monitor for unusual activity

  2. Cold Wallet:

    • Store majority of funds offline

    • Encrypt wallet with strong passphrase

    • Store backups in multiple secure locations

    • Use multi-signature if possible

  3. Backup Strategy:

    • Automate daily backups

    • Store backups in multiple geographic locations

    • Encrypt backup files

    • Test restore procedures regularly

Monitoring

Monitor these metrics:

# Node health
./qtum-cli getnetworkinfo
./qtum-cli getblockchaininfo

# Wallet balance
./qtum-cli getbalance

# Mempool size
./qtum-cli getmempoolinfo

# Peer connections
./qtum-cli getpeerinfo

Set up alerts for:

  • Node synchronization issues

  • Low peer connections (< 8)

  • Unexpected balance changes

  • Failed RPC requests

QRC20 Token Support (Optional)

If your exchange supports QRC20 tokens, enable event logging:

Configuration

Add to qtum.conf:

logevents=1
txindex=1

Important: If blockchain is already synced, reindex:

./qtumd -daemon -reindex -staking=0

Reindexing takes several hours.

QRC20 RPC Calls

# Get token balance
./qtum-cli callcontract "contract_address" "data"

# Send QRC20 tokens
./qtum-cli sendtocontract "contract_address" "data" amount gas_limit gas_price "sender_address"

Refer to QRC20 Integration Guide for detailed token integration.

Troubleshooting

Node Won't Sync

# Check peer connections
./qtum-cli getpeerinfo | grep -c "addr"

# If no peers, add nodes manually
./qtum-cli addnode "seed.qtum.org" "add"
./qtum-cli addnode "node.qtum.org" "add"

RPC Connection Refused

  1. Verify qtum.conf has server=1

  2. Check RPC credentials match

  3. Verify rpcallowip includes your IP

  4. Restart node after configuration changes

Wallet Not Sending Transactions

  1. Check if wallet is encrypted and locked

  2. Verify sufficient balance (including fee)

  3. Check if address is valid Qtum address

  4. Review debug.log for error messages

Docker Container Issues

# Check logs
docker logs qtum-node

# Restart container
docker restart qtum-node

# Access container shell
docker exec -it qtum-node /bin/sh

# Check data volume permissions
ls -la /opt/qtum-data

Additional Resources

Support

For integration support:

Summary: Quick Exchange Integration Checklist

  • [ ] Deploy Qtum node (Docker recommended)

  • [ ] Configure qtum.conf with staking=0

  • [ ] Wait for full blockchain sync

  • [ ] Implement deposit detection (minimum 10 confirmations)

  • [ ] Test withdrawal process

  • [ ] Set up wallet backup automation

  • [ ] Implement security measures (firewall, monitoring)

  • [ ] Document hot/cold wallet procedures

  • [ ] Set appropriate minimum withdrawal (0.01 QTUM)

  • [ ] Configure transaction fees (0.004 QTUM/KB)

  • [ ] Set up monitoring and alerts

  • [ ] Test emergency procedures

Last Updated: November 2025 Qtum Core Version: 29.1 Build System: CMake 3.22+

PreviousBuilding Qtum on LinuxNextQRC20 Token integration

Last updated