Bisq Logo

Introduction[edit]

Bisq is an open-source, peer-to-peer (P2P) application that went into production on 19 April, 2016. Bisq is designed to allow for a safe, private and decentralized method of exchanging national currencies for cryptocurrencies. Primary features include: ^[1] ^[2] ^[3]

no registration is required - identity theft is impossible
fully decentralized and censorship resistant design:
- multi-signature escrow transactions without a third party
- security deposits encourage safe, successful trades ^[4]
- resolution of disputes with a decentralized arbitration system
protection of user privacy via a custom P2P network of users running Bisq over Tor
no data is stored regarding who trades with whom -- end-to-end data encryption ensures trade details are only readable by counterparties
no approval wait times
resistant against spam or flooding
a cross-platform desktop application is available for Linux, macOS and Windows
the project is funded directly by its users through trading fees and donations

Bisq holds a lot of promise, since it eliminates the risk associated with theft of funds from centralized exchanges, removes the threat of interference with trades from third parties, and separates users' personal information from associated transactions. To learn more, refer to:

the original Bisq whitepaper ^[archive]; and/or
Phase Zero: A plan for bootstrapping the Bisq DAO ^[archive] for a comprehensive overview of the application.

Installation[edit]

This application requires incoming connections through a Tor onion service. Supported Whonix-Gateway ™ modifications are therefore necessary for full functionality; see instructions below.

For better security, consider using Multiple Whonix-Gateway ™ and Multiple Whonix-Workstation ™. In any case, Whonix ™ is the safest choice for running it. ^[5]

Whonix-Gateway ™ Installation Steps[edit]

onion-grater Profile[edit]

On Whonix-Gateway ™.

Extend the onion-grater whitelist in Whonix-Gateway ™ (sys-whonix).

On Whonix-Gateway ™. ^[6] ^[7]

Add onion-grater profile.

sudo onion-grater-add 40_bisq

sudo onion-grater-add 40_bisq

Whonix-Workstation ™ Installation Steps[edit]

Firewall Settings[edit]

Modify the Whonix-Workstation ™ (anon-whonix) user firewall settings and reload them.

Modify Whonix-Workstation ™ User Firewall Settings

Note: If no changes have yet been made to Whonix ™ Firewall Settings, then the Whonix ™ User Firewall Settings File /etc/whonix_firewall.d/50_user.conf appears empty (because it does not exist). This is expected.

If using Qubes-Whonix ™, complete these steps.
In Whonix-Workstation ™ App Qube. Make sure folder /usr/local/etc/whonix_firewall.d exists.

sudo mkdir -p /usr/local/etc/whonix_firewall.d

sudo mkdir -p /usr/local/etc/whonix_firewall.d

Qubes App Launcher (blue/grey "Q") → Whonix-Workstation ™ App Qube (commonly called anon-whonix) → Whonix ™ User Firewall Settings

If using a graphical Whonix-Workstation ™, complete these steps.

Start Menu → Applications → System → User Firewall Settings

If using a terminal-only Whonix-Workstation ™, complete these steps.

Open /usr/local/etc/whonix_firewall.d/50_user.conf with root rights.

sudoedit /usr/local/etc/whonix_firewall.d/50_user.conf

sudoedit /usr/local/etc/whonix_firewall.d/50_user.conf

For more help, press on Expand on the right.

Note: This is for informational purposes only! Do not edit /etc/whonix_firewall.d/30_whonix_workstation_default.conf.

The Whonix ™ Global Firewall Settings File /etc/whonix_firewall.d/30_whonix_workstation_default.conf contains default settings and explanatory comments about their purpose. By default, the file is opened read-only and is not meant to be directly edited. Below, it is recommended to open the file without root rights. The file contains an explanatory comment on how to change firewall settings.

## Please use "/etc/whonix_firewall.d/50_user.conf" for your custom configuration,
## which will override the defaults found here. When {{project_name}} is updated, this
## file may be overwritten.

To view the file, follow these instructions.

If using Qubes-Whonix ™, complete these steps.

Qubes App Launcher (blue/grey "Q") → Template: whonix-ws-16 → Whonix Global Firewall Settings

If using a graphical Whonix-Workstation ™, complete these steps.

Start Menu → Applications → Settings → Global Firewall Settings

If using a terminal-only Whonix-Workstation ™, complete these steps.

In Whonix-Workstation ™, open the whonix_firewall configuration file in an editor.

nano /etc/whonix_firewall.d/30_whonix_workstation_default.conf

nano /etc/whonix_firewall.d/30_whonix_workstation_default.conf

Add. TODO: EXTERNAL_OPEN_ALL=true is non-ideal.

EXTERNAL_OPEN_ALL=true

EXTERNAL_OPEN_ALL=true

Save.

Reload Whonix-Workstation ™ Firewall.

If you are using Qubes-Whonix ™, complete the following steps.

Qubes App Launcher (blue/grey "Q") → Whonix-Workstation ™ AppVM (commonly named anon-whonix) → Reload Whonix ™ Firewall

If you are using a graphical Whonix-Workstation ™, complete the following steps.

Start Menu → Applications → System → Reload Whonix ™ Firewall

If you are using a terminal-only Whonix-Workstation ™, run.

sudo whonix_firewall

sudo whonix_firewall

Get the Signing Key[edit]

On Whonix-Workstation ™.

Digital signatures can increase security but this requires knowledge. Learn more about digital software signature verification.

Securely download the signing key.

scurl-download https://github.com/bisq-network/bisq/releases/download/v1.7.4/29CDFD3B.asc

scurl-download https://github.com/bisq-network/bisq/releases/download/v1.7.4/29CDFD3B.asc

Display the key's fingerprint.

gpg --keyid-format long --import --import-options show-only --with-fingerprint 29CDFD3B.asc

gpg --keyid-format long --import --import-options show-only --with-fingerprint 29CDFD3B.asc

Verify the fingerprint. Should show.

Key fingerprint = 6694 D8DE 7BE8 EE56 31BE D950 2BD5 824B 7F94 70E6

The most important check is confirming the key fingerprint exactly matches the output below. ^[8]

Warning:

Do not continue if the fingerprint does not match! This risks using infected or erroneous files! The whole point of verification is to confirm file integrity.

Add the signing key.

gpg --import 29CDFD3B.asc

gpg --import 29CDFD3B.asc

Download[edit]

On Whonix-Workstation ™.

Check the latest version number and read the release notes here ^[archive].

Download bisq.

scurl-download https://github.com/bisq-network/bisq/releases/download/v1.7.4/Bisq-64bit-1.7.4.deb

scurl-download https://github.com/bisq-network/bisq/releases/download/v1.7.4/Bisq-64bit-1.7.4.deb

Download OpenPGP signature.

scurl-download https://github.com/bisq-network/bisq/releases/download/v1.7.4/Bisq-64bit-1.7.4.deb.asc

scurl-download https://github.com/bisq-network/bisq/releases/download/v1.7.4/Bisq-64bit-1.7.4.deb.asc

Verification[edit]

On Whonix-Workstation ™.

Verify OpenPGP signature.

gpg --verify Bisq*.asc

gpg --verify Bisq*.asc

If the file is verified successfully, the output will include Good signature.

gpg: WARNING: This key is not certified with a trusted signature!
gpg:          There is no indication that the signature belongs to the owner.

The above "gpg: WARNING" can be ignored since it does not alter the validity of the signature related to the downloaded key. Rather, this warning refers to the level of trust placed in the developers signing key and the web of trust. To remove this warning, the developers signing key must be personally signed with your own key.

Tor over Tor Prevention[edit]

On Whonix-Workstation ™.

Follow these steps to avoid a Tor over Tor scenario.

Create folder /home/user/.local/share/Bisq/btc_mainnet/tor/.

mkdir -p /home/user/.local/share/Bisq/btc_mainnet/tor/

mkdir -p /home/user/.local/share/Bisq/btc_mainnet/tor/

Create a dummy Tor binary /home/user/.local/share/Bisq/btc_mainnet/tor/tor.

sudo touch /home/user/.local/share/Bisq/btc_mainnet/tor/tor

sudo touch /home/user/.local/share/Bisq/btc_mainnet/tor/tor

xdg-desktop-menu Bug Workaround[edit]

On Whonix-Workstation ™.

Use the following workaround to avoid a known bug in xdg which fails to find a writable system menu directory. ^[9]

sudo mkdir -p /usr/share/desktop-directories

sudo mkdir -p /usr/share/desktop-directories

Install[edit]

On Whonix-Workstation ™.

Install Bisq.

sudo dpkg -i Bisq*.deb

sudo dpkg -i Bisq*.deb

Usage[edit]

On Whonix-Workstation ™.

Start Bisq.

/opt/bisq/bin/Bisq --torControlPort=9051 --torControlPassword=notrequired --socks5ProxyBtcAddress=127.0.0.1:9050 --useTorForBtc=true --daoActivated=false

/opt/bisq/bin/Bisq --torControlPort=9051 --torControlPassword=notrequired --socks5ProxyBtcAddress=127.0.0.1:9050 --useTorForBtc=true --daoActivated=false

Figure: Bisq Launch in Whonix ™

Figure: Bisq Client ^[10]

If you would like to use the DAO ^[archive], you could drop --daoActivated=false. If you are unfamiliar with DAO, refer to the prior reference before deciding whether it is necessary in your circumstances. When DAO is activated, Bisq will consume a lot more resources, and you will probably need to increase VCPUs/RAM.

If the fonts are too small, you could alternatively use the following command. ^[11]

GDK_SCALE=2 /opt/bisq/bin/Bisq --torControlPort=9051 --torControlPassword=notrequired --socks5ProxyBtcAddress=127.0.0.1:9050 --useTorForBtc=true --daoActivated=false

GDK_SCALE=2 /opt/bisq/bin/Bisq --torControlPort=9051 --torControlPassword=notrequired --socks5ProxyBtcAddress=127.0.0.1:9050 --useTorForBtc=true --daoActivated=false

Refer to the official Bisq documentation ^[archive] to learn about trading essentials, including:

an introduction to Bisq
quick start guide to trading in minutes
wallet information and security
backup and recovery
how to stay private
trading rules and dispute resolution
fees and security deposits
payments methods

Forum Discussion[edit]

Bisq - The P2P Exchange Network ^[archive]

Donations[edit]

After installing Bisq, please consider making a donation to Whonix ™ to keep it running for years to come.

Donate Bitcoin (BTC) to Whonix ™.

35wdTVzyYGzRd7W2Wb2dunw3v5Am14sxPX

Footnotes[edit]

↑ https://github.com/bisq-network/bisq ^[archive]
↑ https://bisq.network/ ^[archive]
↑ https://docs.bisq.network/exchange/whitepaper.html#introduction ^[archive]
↑ A current limit of at most 1 Bitcoin per transaction applies.
↑
Security considerations:
- By using Whonix ™, additional protections are in place for greater security.
- This application requires access to Tor's control protocol.
- In the Whonix ™ context, Tor's control protocol has dangerous features. The Tor control command GETINFO address reveals the real, external IP of the Tor client.
- Whonix ™ provides onion-grater, a Tor Control Port Filter Proxy - filtering dangerous Tor Control Port commands.
- When this application is run inside Whonix ™ with an onion-grater whitelist extension, this will limit application rights to Tor control protocol access only. Non-whitelisted Tor control commands such as GETINFO address are rejected by onion-grater in these circumstances.
- During the application's normal operations it should not attempt to use dangerous Tor control commands such as GETINFO address. In the event the application or Whonix-Workstation ™ are compromised, this command would be rejected.
- In comparison, if the application is run on a non-Tor focused operating system like Debian, it will have unlimited access to Tor's control protocol (a less secure configuration).
- If the (non-)Whonix platform is used to host onion services, then running applications are more vulnerable to attacks against the Tor network compared to when Tor is solely used as a client; see also Onion Services Security.
In conclusion, Whonix ™ is the safest and correct choice for running this application.
↑ Using /usr/local/etc/onion-grater-merger.d/ because that onion-grater settings folder is persistent in Qubes-Whonix ™ TemplateBased ProxyVMs i.e. Whonix-Gateway ™ (commonly called sys-whonix). Non-Qubes-Whonix ™ users could also utilize /etc/onion-grater-merger.d/. Qubes-Whonix ™ users could also utilize /etc/onion-grater-merger.d/ but then /etc/onion-grater-merger.d/ must be made persistent, which means doing this procedure inside the Whonix-Gateway ™ TemplateVM (commonly called whonix-gw-16) and then restarting the Whonix-Gateway ™ ProxyVM or using bind-dirs ^[archive]. Both techniques are more complicated than simply using /usr/local/etc/onion-grater-merger.d/, since it is persistent either way. Further, it even allows multiple Whonix-Gateway ™ ProxyVMs based on the same Whonix-Gateway ™ TemplateVM; for example, one Whonix-Gateway ™ ProxyVM extending and relaxing onion-grater's whitelist and the other Whonix-Gateway ™ ProxyVM having the default onion-grater whitelist which is more restrictive.
↑
Previously manual instructions. No longer needed. onion-grater-add automates that.
```
sudo mkdir -p /usr/local/etc/onion-grater-merger.d/
```
sudo mkdir -p /usr/local/etc/onion-grater-merger.d/
Symlink the onion-grater profile to the onion-grater settings folder.
```
sudo ln -s {{{filename_new}}}.yml /usr/local/etc/onion-grater-merger.d/
```
sudo ln -s {{{filename_new}}}.yml /usr/local/etc/onion-grater-merger.d/
Restart onion-grater.
```
sudo service onion-grater restart
```
sudo service onion-grater restart
↑ Minor changes in the output such as new uids (email addresses) or newer expiration dates are inconsequential.
↑ https://github.com/bisq-network/bisq/issues/848 ^[archive]
↑ https://docs.bisq.network/getting-started.html ^[archive]
↑ It is the same as above but prepended with GDK_SCALE=2. https://github.com/bisq-network/bisq/issues/1425 ^[archive]