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!
live | Setup time:
~15 mins | Disk space:
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!
live | Setup time:
~5-24h | Disk space:
Real money - only with #reckless hat.
live (with $10-per-trade limit) | Setup time:
~1-3 days | Disk space:
Linux or macOS. Windows WSL 2 support is currently experimental and not tested regularly.
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.
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.
Python 2.7+ or 3+ (pre-installed on most systems, check with
python --version )
Start the environment with
curl https://raw.githubusercontent.com/ExchangeUnion/xud-docker/master/xud.sh -o ~/xud.shbash ~/xud.sh
This guides you through a setup on first run, pulls containers, starts syncing chains and opens
.___ __ ._____ _____ __ __| _/ _____/ |_| |\ \/ / | \/ __ | _/ ___\ __\ |> <| | / /_/ | \ \___| | | |__/__/\_ \____/\____ | \___ >__| |____/\/ \/ \/--------------------------------------------------------------
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 Readylndbtc Readyltc Syncing 2.40% (26887/1116528)lndltc Waiting for syncgeth Syncing 42.61% (2489756/5842588)raiden Waiting for syncxud 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
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.
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:
#Simnetltcctl --help#Testnet/Mainnetbitcoin-cli --helplndbtc-lncli --helplitecoin-cli --helplndltc-lncli --helpgeth --helpraiden --helpxucli --help
Permanently set xud alias to launch
xud ctl from anywhere: Add the line
alias xud="bash ~/xud.sh" 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):
#Simnetlogs ltcd/geth/lndbtc/lndltc/raiden/xud#Testnet/Mainnetlogs 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 ~/xud.sh --home-dir /path/to/your/xud-docker/home
You can also customize the directory of L1 clients with:
#bitcoindbash ~/xud.sh --bitcoind-dir /path/to/your/bitcoind/dir#litecoindbash ~/xud.sh --litecoind-dir /path/to/your/litecoind/dir#geth (all on SSD)bash ~/xud.sh --geth-dir /path/to/your/geth/ssd/dir#geth split (chain-data on HDD)bash ~/xud.sh --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 ~/xud.sh