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.



This is where you want to start. It's quick and gives you a "look and feel". Private chains maintained by Exchange Union cloud instances, we automatically open channels to you and allocate you some precious simnet tokens. Trade against our bots. Consider restarting the setup once after starting for the first time (down, exit, bash ~/, 1).

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.

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


Real money - only with #reckless hat.

Status: live (with very low limits) | Setup time: ~1-3 days | Disk space: 500 GB


Producing blocks locally, mainly for development

Status: not available| Setup time: fast | Disk space: 1 GB


  1. Linux or macOS. Windows WSL 2 support is currently experimental.

  2. 8GB RAM (we saw some weird container states with less on testnet and mainnet). The more, the better. geth likes RAM. A lot.

  3. Run on a SSD. 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.

  5. Current user can run docker (without adding sudo). Test with docker run hello-world. If this fails, follow these instructions.

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

  • 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 ~/