Get Started (Install)
BasicSwap is a cross-chain and highly secure DEX (decentralized exchange) that lets you trade cryptocurrencies without middleman interference using atomic swaps. Its distributed ledger technology enables users to place or accept swap offers without fees, promoting a free and open trading environment devoid of central points of failure.
BasicSwap is crafted to uphold the highest standards of freedom in direct opposition to the growing threats to our sovereignty in the digital age.
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 the code from source 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
Begin by completing the prerequisites listed on the Docker Desktop WSL 2 backend page. This involves activating the WSL2 feature on Windows.
Proceed to download Docker Desktop for Windows.
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.
Install the Docker engine on your device
Install the required dependencies.
apt-get install curl jq git
Check if Docker is already installed on your system.
docker -v
If you see a message indicating Docker version (…), Docker is already installed and you can move on to the next steps without reinstalling it.
Install Docker by following the instructions on their website.
Configuring Docker to run without sudo is recommended, as outlined in this guide. Without this setup, you’ll need to include sudo before every docker-compose command.
Create the Docker Image
Create BasicSwap’s docker image, which you’ll need to run whenever you want to launch the DEX.
Open a WSL (Linux) terminal.
Windows + R > “wsl” -> ENTER.
Install Git.
sudo apt update sudo apt install git jq curl
Download the BasicSwap code.
git clone https://github.com/basicswap/basicswap.git
Navigate to BasicSwap’s Docker folder.
cd basicswap/docker/
Copy the default environment file.
cp example.env .env
(Optional) Set a custom coin data path by modifying the target path in your .env file.
nano .env
Create the BasicSwap Docker image (make sure you are in basicswap/docker.
docker-compose build
Open a terminal.
Install Git.
sudo apt update sudo apt install git jq curl
Download the BasicSwap code.
git clone https://github.com/basicswap/basicswap.git
Navigate to BasicSwap’s Docker folder.
cd basicswap/docker/
Copy the default environment file.
cp example.env .env
(Optional) Set a custom coin data path by modifying the target path in your .env file.
nano .env
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.
Open a WSL (Linux) terminal.
Windows + R > “wsl” -> ENTER.
Navigate to BasicSwap’s Docker folder.
cd basicswap/docker/
Set xmrrestoreheight to Monero’s current chain height.
CURRENT_XMR_HEIGHT=$(curl -s http://node2.monerodevs.org:18089/get_info | jq .height)
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.
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.
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
Securely record and store the mnemonic provided by the above command. It serves as your wallet’s backup key.
Safely note the result of the following command, it is useful if you need to recover your Monero wallet.
echo $CURRENT_XMR_HEIGHT
(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.
Open a terminal.
Navigate to BasicSwap’s Docker folder.
cd basicswap/docker/
Set xmrrestoreheight to Monero’s current chain height.
CURRENT_XMR_HEIGHT=$(curl -s http://node2.monerodevs.org:18089/get_info | jq .height)
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.
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.
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
Securely record and store the mnemonic provided by the above command. It serves as your wallet’s backup key.
Safely note the result of the following command, it is useful if you need to recover your Monero wallet.
echo $CURRENT_XMR_HEIGHT
(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.
Open a WSL (Linux) terminal.
Windows + R > “wsl” -> ENTER.
Navigate to BasicSwap’s Docker folder.
cd basicswap/docker/
Start the Docker image. This will launch BasicSwap’s startup process.
export COINDATA_PATH=/var/data/coinswaps docker-compose up
Wait for BasicSwap to start fully, then open it up in your favorite web browser by navigating to the following address.
http://localhost:12700
Open a terminal.
Navigate to BasicSwap’s Docker folder.
cd basicswap/docker/
Start the Docker image. This will launch BasicSwap’s startup process.
export COINDATA_PATH=/var/data/coinswaps docker-compose up
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.
Open Terminal (i.e., COMMAND ⌘ + SPACE and type “terminal” > hit ENTER ↵).
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)"
Install the required dependencies
brew install python git gnupg pkg-config jq
Close the terminal and open a new one. This will update the python symlinks and allow you to progress through the next steps.
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 python3 -m venv "$SWAP_DATADIR/venv" . $SWAP_DATADIR/venv/bin/activate && python3 -V cd $SWAP_DATADIR git clone https://github.com/basicswap/basicswap.git cd $SWAP_DATADIR/basicswap
Install root SSL certificates for the SSL module (more information here).
sudo python3 bin/install_certifi.py
Continue with the BasicSwap installation, executing the following two commands.
pip3 install --require-hashes -r requirements.txt pip3 install .
Install the required dependencies
apt-get install --no-install-recommends git python3-venv libpython3-dev gnupg pkg-config gcc libc-dev curl jq
Execute the commands below sequentially to setup the environment
export SWAP_DATADIR=$HOME/coinswaps python3 -m venv "$SWAP_DATADIR/venv" . $SWAP_DATADIR/venv/bin/activate && python3 -V
cd $SWAP_DATADIR git clone https://github.com/basicswap/basicswap.git cd $SWAP_DATADIR/basicswap pip3 install --require-hashes -r requirements.txt pip3 install .
Configure BasicSwap
After the installation, configure BasicSwap according to your requirements.
Open Terminal (i.e., COMMAND ⌘ + SPACE and type “terminal” > hit ENTER ↵).
Navigate to your BasicSwap folder.
cd /Users/$USER/coinswaps
Set xmrrestoreheight to Monero’s current chain height.
CURRENT_XMR_HEIGHT=$(curl -s http://node2.monerodevs.org:18089/get_info | jq .height)
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.
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.
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
Open a terminal.
Navigate to your BasicSwap folder.
cd $HOME/coinswaps
Set xmrrestoreheight to Monero’s current chain height.
CURRENT_XMR_HEIGHT=$(curl -s http://node2.monerodevs.org:18089/get_info | jq .height)
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.
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.
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.
Open Terminal (i.e., COMMAND ⌘ + SPACE and type “terminal” > hit ENTER ↵).
Navigate to your BasicSwap folder.
cd /Users/$USER/coinswaps
Launch BasicSwap.
basicswap-run --datadir=$SWAP_DATADIR
Open BasicSwap’s user interface in your favorite web browser by navigating to the following address.
http://localhost:12700
Open a terminal.
Navigate to your BasicSwap folder.
cd $HOME/coinswaps
Launch BasicSwap.
basicswap-run --datadir=$SWAP_DATADIR
Open BasicSwap’s user interface in your favorite web browser by navigating to the following address.
http://localhost:12700
See also
BasicSwap Explained - BasicSwap Explained
BasicSwap Guides - Update BasicSwap
BasicSwap Guides - Make an Offer
BasicSwap Guides - Take an Offer