User Guide

This guide is written for users who want to buy and sell cryptocurrency via xud. It explains how to use xud-docker, the recommended and easiest way to get up and running.



Private chains which are maintained by us. We’ll automatically open channels to you and push over some coins, you’ll be trading against our bots and anyone else running simnet. It’s the perfect playground to see how things work and play around with xucli commands. It’s easy: run one script, wait for about 10 minutes and you are ready to go. You want to start with this!

Status: live | Setup time: ~15 mins | Disk space: 5 GB


bitcoin testnet 3, litecoin testnet 4, ethereum ropsten. Faucets: t-BTC, t-LTC, t-ETH 1 & 2. Quite a bit of manual work to be done here. If you need help or some channels with testnet coins, hit us up on Discord!

Status: live | Setup time: ~5-24h | Disk space: 120 GB


Real money - only with #reckless hat.

Status: live (with $10-per-trade limit) | Setup time: ~1-3 days | Disk space: 500 GB


  1. Linux or macOS. Windows WSL 2 support is currently experimental and not tested regularly.

  2. 12GB RAM for testnet & mainnet (we saw some weird container states with less). geth likes RAM. A lot. If you have >=24GB RAM available, you can significantly shorten geth's syncing time by increasing its --cache=1024 flag for testnet or mainnet to something larger.

  3. A SSD for testnet & mainnet. Based on painful experience: geth cannot catch up with the chain when running on a regular HDD. Read about it here.

  4. docker >= 18.09 & docker-compose >= 1.24. Check with docker --version & docker-compose --version. If you do not have these installed yet, follow the official install instructions for docker and docker-compose. Also make sure that the current user can run docker (without adding sudo). Test with docker run hello-world. If it fails, follow these instructions.

  5. Python 2.7+ or 3+ (pre-installed on most systems, check with python --version )

How to run

Start the environment with

curl -o ~/
bash ~/

This guides you through a setup on first run, pulls containers, starts syncing chains and opens

.___ __ .__
___ _____ __ __| _/ _____/ |_| |
\ \/ / | \/ __ | _/ ___\ __\ |
> <| | / /_/ | \ \___| | | |__
/__/\_ \____/\____ | \___ >__| |____/
\/ \/ \/

The status command shows status of underlying clients, which is especially useful to track the sync status. If you are syncing full nodes on Testnet/Mainnet, this takes several hours or even days. All clients should show Ready before you continue.

btc Ready
lndbtc Ready
ltc Syncing 2.40% (26887/1116528)
lndltc Waiting for sync
geth Syncing 42.61% (2489756/5842588)
raiden Waiting for sync
xud Waiting for sync

xud ctl takes xucli commands, like getinfo. Once everything is up and running, you can check existing orders of your connected peers with orderbook and issue an order, e.g. sell 0.1 btc/dai 9998. Check your balance before and after the swap to see it changing.


Raiden currently requires direct channels with trading partners to swap reliably. We have a temporary check in place, that discards raiden-related orders (all pairs which include WETH, DAI...), if xud can't find a direct channel to the trading partner. You can switch this check off by setting raidenDirectChannelChecks=false in your xud.conf. Before you do that, read this explainer of the issue.


Please report issues/bugs by running report from within xud ctl.

Tips 'n Tricks

  • Docker might not play nicely with a VPN you are running on the same machine. If you see Failed to launch simnet environment, try disconnecting the VPN.

  • We placed xud & lnd behind TOR by default, which improves privacy and does away with the need to open ports

  • If you want to test pre-release builds, follow these instructions.

  • xud ctl allows to use an underlying client's cli:

    ltcctl --help
    bitcoin-cli --help
    lndbtc-lncli --help
    litecoin-cli --help
    lndltc-lncli --help
    geth --help
    raiden --help
    xucli --help
  • Permanently set xud alias to launch xud ctl from anywhere: Add the line alias xud="bash ~/" to the end of ~/.bashrc on Linux or bash_profile on Mac, then source the file.

  • To inspect logs (use logs -f if you want to follow the log live):

    logs ltcd/geth/lndbtc/lndltc/raiden/xud
    logs bitcoind/litecoind/geth/lndbtc/lndltc/raiden/xud
  • Blockchain & wallet data is stored in ~/.xud-docker by default:

  • Customize this directory with --home-dir, which you need to append every time you run

    bash ~/ --home-dir /path/to/your/xud-docker/home
  • You can also customize the directory of L1 clients with:

    bash ~/ --bitcoind-dir /path/to/your/bitcoind/dir
    bash ~/ --litecoind-dir /path/to/your/litecoind/dir
    #geth (all on SSD)
    bash ~/ --geth-dir /path/to/your/geth/ssd/dir
    #geth split (chain-data on HDD)
    bash ~/ --geth-dir /path/to/your/geth/ssd/dir --geth-chaindata-dir /path/to/your/geth/hdd/dir
  • Shutdown environment & remove all data

    docker-compose down
    # Use with caution: this step removes all `xud` blockchain and wallet data from your system. If you still have channels open or lost your seed mnemonic, you are risking to loose funds.
    rm -rf ~/.xud-docker/
    rm -rf ~/