Get Started (Install)

BasicSwap DEX is a cross-chain and privacy-centric DEX (decentralized exchange) that lets you trade cryptocurrencies without middleman interference. This guide walks you through all the steps required to install it and set it up to your liking.

Tip

If you want to further protect your network information (i.e., IP address, location), you can run BasicSwap through the Tor network. Jump to the BasicSwap Tor Guide for detailed instructions on how to do so.

Attention

When compiling a full BasicSwap node, it is very important to monitor the outputs given by the commands you enter. Ensure that, for every step of the process, the terminal doesn’t mention anything about errors. If errors occur, it is important to fix them. DO NOT blindly enter commands without making sure that no errors occur; BasicSwap will not launch successfully if the steps are not properly completed.

Install Using Docker

Because BasicSwap is still in early beta, there is no ready-made executable or convenient integrations (i.e., Particl Desktop, web gateway, third-party platforms, etc.) yet; you must compile and run a full BasicSwap node. For this reason, the first step to get started is to compile the application locally on your computer.

Install Docker

The easiest way to set up BasicSwap is through Docker. Note that this setup method is not available for OSX, so if you’ve got a Mac device, please refer to the next section.

Install the Docker engine on your device

  1. Complete the prerequisites on the Docker Desktop WSL 2 backend page. This includes enabling the WSL2 feature on Windows.

  2. Download Docker Desktop for Windows.

  3. Install Docker with WSL 2 by following the instructions on the Docker Desktop WSL 2 backend page.

Note

Some versions of Docker may have incompatibility issues with Windows 11. If the problem persists, consider using an older version of Docker.

Note

Changing certain BIOS settings, such as enabling hardware-assisted virtualization, may be required to run Docker successfully — follow the prompts’ instructions if that is the case.

Create the Docker Image

Create BasicSwap’s docker image. You need to run this image whenever you want to run the DEX.

  1. Open a WSL (Linux) terminal.

    Windows + R > “wsl” -> ENTER.

  2. Install Git.

    sudo apt update
sudo apt install git jq curl

  3. Download the BasicSwap code.

    git clone https://github.com/tecnovert/basicswap.git

  4. Navigate to BasicSwap’s Docker folder.

    cd basicswap/docker/

  5. Set your COINDATA_PATH.

    export COINDATA_PATH=/var/data/coinswaps

  6. (Optional) You can alternatively set the COINDATA_PATH value by default. To do so, delete the # at the beginning of the related line in the .env file, located in basicswap/docker.

    nano .env

  7. Create the BasicSwap Docker image (make sure you are in basicswap/docker.

    docker-compose build

Configure the Docker Image

Now that BasicSwap’s image has been created, you need to configure it to your liking.

  1. Open a WSL (Linux) terminal.

    Windows + R > “wsl” -> ENTER.

  2. Navigate to BasicSwap’s Docker folder.

    cd basicswap/docker/

  3. Set xmrrestoreheight to Monero’s current chain height.

    CURRENT_XMR_HEIGHT=$(curl https://localmonero.co/blocks/api/get_stats | jq .height)

  4. Choose what coins you want to enable (Particl will be enabled by default). You will need to write them in the configuration command. Click here for a full list of available coins on BasicSwap.

  5. Decide whether you want to fast sync the Bitcoin blockchain by downloading a checkpoint or sync from scratch. This will be determined by whether or not you add the –usebtcfastsync argument to the next step’s configuration command.

  6. Configure your BasicSwap Docker image by typing the following configuration command. Make sure to change it according to your preferences as mentioned in the previous two steps.

    export COINDATA_PATH=/var/data/coinswaps
docker run --rm -t --name swap_prepare -v $COINDATA_PATH:/coindata i_swapclient basicswap-prepare --datadir=/coindata --withcoins=monero,bitcoin --htmlhost="0.0.0.0" --wshost="0.0.0.0" --xmrrestoreheight=$CURRENT_XMR_HEIGHT --usebtcfastsync

  7. Note the mnemonic that the previous command will give you somewhere safe. This is your wallet backup key.

  8. Note the output of the following command somewhere safe. It is useful if you need to restore your Monero wallet later on.

    echo $CURRENT_XMR_HEIGHT

  9. (Optional) Set your timezone by setting the correct TZ value in your .env file (located in BasicSwap’s docker folder). List valid timezone options by typing the timedatectl list-timezones command.

    nano .env

    To save changes, press CTRL + X, then Y + ENTER.

Start BasicSwap

Now that you’ve configured your docker image, it’s time to run it. This will start BasicSwap and make it accessible from web browsers.

  1. Open a WSL (Linux) terminal.

    Windows + R > “wsl” -> ENTER.

  2. Navigate to BasicSwap’s Docker folder.

    cd basicswap/docker/

  3. Start the Docker image. This will launch BasicSwap’s startup process.

    export COINDATA_PATH=/var/data/coinswaps
docker-compose up

  4. Wait for BasicSwap to start fully, then open it up in your favorite web browser by navigating to the following address.

    http://localhost:12700

Install Without Docker

Build BasicSwap

The first step to running BasicSwap without docker is to build it locally on your device.

  1. Open Terminal (i.e., COMMAND ⌘ + SPACE and type “terminal” > hit ENTER ↵).

  2. Install Homebrew, which will let you execute Linux-like commands right from your Mac OS terminal.

    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

  3. Install the required dependencies

    brew install wget unzip python git protobuf gnupg automake libtool pkg-config curl jq

  4. Close the terminal and open a new one. This will update the python symlinks and allow you to progress through the next steps.

  5. Execute the following commands one by one (do NOT copy-paste the entire block at once, each line is an independent command). Ensure that the terminal doesn’t return any error for each command entered. If it does, carefully look at what the error is and fix it before moving to the next step; entering the following command without fixing a previous issue will break the installation process.

    export SWAP_DATADIR=/Users/$USER/coinswaps
mkdir -p "$SWAP_DATADIR/venv"
python3 -m venv "$SWAP_DATADIR/venv"
. $SWAP_DATADIR/venv/bin/activate && python -V
cd $SWAP_DATADIR
wget -O coincurve-anonswap.zip https://github.com/tecnovert/coincurve/archive/refs/tags/anonswap_v0.1.zip
unzip -d coincurve-anonswap coincurve-anonswap.zip
mv ./coincurve-anonswap/*/{.,}* ./coincurve-anonswap || true
cd $SWAP_DATADIR/coincurve-anonswap
pip3 install .
cd $SWAP_DATADIR
git clone https://github.com/tecnovert/basicswap.git
cd $SWAP_DATADIR/basicswap

  6. Install root SSL certificates for the SSL module (more information here).

    sudo python3 bin/install_certifi.py

  7. Continue with the BasicSwap installation, executing the following two commands one by one.

    protoc -I=basicswap --python_out=basicswap basicswap/messages.proto
pip3 install .

Configure BasicSwap

Now that your BasicSwap instance has been created, you need to configure it to your liking.

  1. Open Terminal (i.e., COMMAND ⌘ + SPACE and type “terminal” > hit ENTER ↵).

  2. Navigate to your BasicSwap folder.

    cd /Users/$USER/coinswaps

  3. Set xmrrestoreheight to Monero’s current chain height.

    CURRENT_XMR_HEIGHT=$(curl https://localmonero.co/blocks/api/get_stats | jq .height)

  4. Choose what coins you want to enable (Particl will be enabled by default). You will need to write them in the configuration command. Click here for a full list of available coins on BasicSwap.

  5. Decide whether you want to fast-sync the Bitcoin blockchain by downloading a checkpoint or sync from scratch. This will be determined by whether or not you add the –usebtcfastsync argument to the configuration command.

  6. Configure your BasicSwap Docker image by typing the following configuration command. Make sure to change it according to your preferences, as determined in the previous two steps.

    basicswap-prepare --datadir=$SWAP_DATADIR --withcoins=monero,bitcoin --xmrrestoreheight=$CURRENT_XMR_HEIGHT --usebtcfastsync

Start BasicSwap

Now that you’ve configured your BasicSwap instance, it’s time to run it. This will start BasicSwap and make it accessible from web browsers.

  1. Open Terminal (i.e., COMMAND ⌘ + SPACE and type “terminal” > hit ENTER ↵).

  2. Navigate to your BasicSwap folder.

    cd /Users/$USER/coinswaps

  3. Launch BasicSwap.

    basicswap-run --datadir=$SWAP_DATADIR

  4. Open BasicSwap’s user interface in your favorite web browser by navigating to the following address.

    http://localhost:12700

See also