> For the complete documentation index, see [llms.txt](https://docs.qtum.info/qtum-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.qtum.info/qtum-documentation/qtum-deployment/guidance-for-exchange-deployment.md).

# 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](https://docs.docker.com/get-docker/))
* Sufficient disk space (minimum 100GB recommended for mainnet)
* Stable network connection

#### Pull Qtum Docker Image

```bash
docker pull qtum/qtum:latest
```

For a specific version:

```bash
docker pull qtum/qtum:v29.1
```

#### Create Data Directory

Create a persistent directory for blockchain data and wallet:

```bash
mkdir -p /opt/qtum-data
```

#### Create Configuration File

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

```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:**

```bash
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:**

```bash
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

```bash
# 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

```bash
# 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

```bash
# 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`:

```yaml
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:

```bash
docker-compose up -d
```

***

### Binary Deployment

#### Download Prebuilt Binaries

Download the latest release from the [GitHub Releases page](https://github.com/qtumproject/qtum/releases):

**Current stable version: 29.1**

```bash
# 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:

```bash
# 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

```bash
./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`:

```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

```bash
./qtum-cli getblockchaininfo
```

Monitor the `blocks` and `headers` fields. When they match the latest block on [Qtum Explorer](https://qtumexplorer.io/), the node is fully synchronized.

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

#### Shutdown Node

```bash
./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.

```bash
# 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

```bash
./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

```bash
# 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

```bash
./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

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

Returns address validity and ownership information.

#### Check Received Amount

```bash
./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

```bash
# 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

```bash
./qtum-cli gettransaction "transaction_id"
```

Check the `confirmations` field before crediting user accounts.

***

### Processing Withdrawals

#### Send Transaction

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

**Examples:**

```bash
# 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`:

```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:

```bash
# 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`:

```conf
logevents=1
txindex=1
```

**Important:** If blockchain is already synced, reindex:

```bash
./qtumd -daemon -reindex -staking=0
```

Reindexing takes several hours.

#### QRC20 RPC Calls

```bash
# 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](https://docs.qtum.info/) for detailed token integration.

***

### Troubleshooting

#### Node Won't Sync

```bash
# 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

```bash
# 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

* **Official Website:** [https://qtum.org](https://qtum.org/)
* **Block Explorer:** [https://qtumexplorer.io](https://qtumexplorer.io/)
* **GitHub Repository:** <https://github.com/qtumproject/qtum>
* **Documentation:** [https://docs.qtum.info](https://docs.qtum.info/)
* **Docker Hub:** <https://hub.docker.com/r/qtum/qtum>
* **API Documentation:** <https://docs.qtum.info/qtum-documentation/>

***

### Support

For integration support:

* **Developer Telegram:** <https://t.me/qtumofficial>
* **Discord:** <https://discord.gg/qtum>
* **Email:** <dev@qtum.org>

***

### 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+