Get Started (Install)

BasicSwap DEX is a cross-chain and privacy-first decentralized exchange (DEX) enabling direct cryptocurrency trades without intermediaries, restrictions, or fees. This guide provides comprehensive instructions for installing and configuring it according to your needs.

Tip

To significantly improve your network privacy (e.g., masking your IP address and location), consider running BasicSwap via the Tor network. For step-by-step guidance, refer to the BasicSwap Tor Guide.

Attention

During the installation of a full BasicSwap node, closely monitor the terminal’s output. It’s crucial to ensure there are no error messages at any step. Errors must be addressed immediately; failure to do so may prevent BasicSwap from launching successfully.

Automated Installation Methods

Windows Installation Wizard (.exe)

Install BasicSwap on Windows effortlessly with a graphical installation wizard by downloading the .exe installer from this Github link. This intuitive installer streamlines the setup process via an easy-to-navigate menu. Note that you must run it as an administrator for it to work properly.

Linux Installation Scripts Suite

For Linux users, the simplest installation method is through the use of community-developed scripts, available here on Github. This collection of scripts automates common setup tasks, including installing, adding/removing/updating coin cores, updating BasicSwap, and enabling Tor.

Install Using Docker

As BasicSwap is currently in early beta, it lacks ready-made executables or in-app integrations (such as Particl Desktop, web gateways, or third-party services). Thus, the initial step involves compiling and running a full BasicSwap node on your device.

Install Docker

Docker offers a straightforward method for setting up BasicSwap without one of the automated solutions. Please note, this installation method does not support OSX. If you are using a Mac, refer to the subsequent section for alternative setup instructions.

Install the Docker engine on your device

  1. Begin by completing the prerequisites listed on the Docker Desktop WSL 2 backend page. This involves activating the WSL2 feature on Windows.

  2. Proceed to download Docker Desktop for Windows.

  3. Follow the detailed installation guide for Docker with WSL 2 on the Docker Desktop WSL 2 backend page.

Note

Be aware that certain versions of Docker might not be fully compatible with Windows 11. Should issues arise, trying an earlier version of Docker could be beneficial.

Note

You may need to adjust BIOS settings, such as enabling hardware-assisted virtualization, to ensure Docker runs smoothly. Please adhere to any guidance provided during the setup process if that’s the case.

Create the Docker Image

Create BasicSwap’s docker image, which you’ll need to run whenever you want to launch 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. Copy the default environment file.

    cp example.env .env

  6. (Optional) Set a custom coin data path by modifying the target path in your .env file.

    nano .env

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

    docker-compose build

Configure the Docker Image

After creating BasicSwap’s Docker image, it’s time to configure it to your preferences.

  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. Select the cryptocurrencies you want to activate (Particl is activated by default). You must specify your choices in the configuration command. See here for a complete list of compatible currencies on BasicSwap.

  5. Decide on whether to perform a fast sync of the Bitcoin blockchain using a checkpoint or to synchronize from the beginning. This choice affects whether you include the –usebtcfastsync parameter in your configuration command.

  6. Execute the following command to configure your BasicSwap Docker image, adjusting it according to your preferences as described above.

    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. Securely record and store the mnemonic provided by the above command. It serves as your wallet’s backup key.

  8. Safely note the result of the following command, it is useful if you need to recover your Monero wallet.

    echo $CURRENT_XMR_HEIGHT

  9. (Optional) Adjust your timezone by specifying the appropriate TZ value in your .env file, located within the BasicSwap Docker directory. Use the timedatectl list-timezones command to view valid timezone options.

    nano .env

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

Start BasicSwap

After configuring your Docker image, the next step is to run it. Doing so will launch BasicSwap, making it accessible through 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 by executing the following command in the Terminal. Homebrew extends MacOS with a wealth of Linux-style package management capabilities.

    /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 commands below sequentially to setup the environment. Each line must be run one-by-one to prevent errors and ensure successful execution.

    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

After the installation, configure BasicSwap according to your requirements.

  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)

  1. Select the cryptocurrencies you want to activate (Particl is activated by default). You must specify your choices in the configuration command. See here for a complete list of compatible currencies on BasicSwap.

  2. Decide on whether to perform a fast sync of the Bitcoin blockchain using a checkpoint or to synchronize from the beginning. This choice affects whether you include the –usebtcfastsync parameter in your configuration command.

  3. Execute the following command to configure your BasicSwap Docker image, adjusting it according to your preferences as described above.

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

Start BasicSwap

After configuring your Docker image, the next step is to run it. Doing so will launch BasicSwap, making it accessible through 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