Bisq API Java Examples And Bots
This subproject contains:
-
Java API rpc examples demonstrating how to send API gRPC requests, and handle responses.
-
Java API bots to use as is on mainnet, and demonstrate how to write new API bots. If interested in porting any bot code to other languages supported by gRPC, please use these Java bot examples, not the Python examples. The Python examples were written by a Python noob, and don't handle errors.
-
A Gradle build file that could be used as a template for your own Java API bot project.
Risks, Warnings and Flaws
Never Run API Daemon and Bisq GUI On Same Host At Same Time
The API daemon and the GUI share the same default wallet and connection ports. Beyond inevitable failures due to fighting over the wallet and ports, doing so will probably corrupt your wallet. Before starting the API daemon, make sure your GUI is shut down, and vice-versa. Please back up your mainnet wallet early and often with the GUI.
Go Slow (But Much Faster Than You Click Buttons In The GUI)
Bisq was designed to respond to manual clicks in the user interface. It is not a high-throughput, high-performance system supporting atomic transactions. Care must be taken to avoid problems due to slow wallet updates on your disk, and Tor network latency. The API daemon enforces limits on request frequency via call rate metering, but you cannot assume bots can perform tasks as rapidly as the API daemon's call rate meters allow.
Run Bots On Mainnet At Your Own Risk
This document would not state "these bots can be run on mainnet, as is" without reasonable confidence on the part of the code's author, but if you do, you do so at your own risk. Copious details about running them on a local BTC regtest network, running on mainnet in dryrun mode, and each bot's configuration is provided in this document. Please put some effort into understanding a bot's code and its configuration before trying it on mainnet.
Why There Is Duplicated Code In The Bots
The TakeBestPricedOffer* bots could be combined into a single class, and use multithreaded task scheduling instead of loops with Thread sleep instructions, but we want them to be easily understood by people who are not necessarily experienced Java coders (and be easily portable to other gRPC supported language bindings). For non-developers, splitting up a one-size-fits-all TakeBestPricedOffer also makes them easier to configure for various BTC/Fiat, XMR/BTC, and BSQ/BTC market use cases.
Generating Protobuf Code
Download IDL (.proto) Files From The Bisq Repo
The protobuf IDL files are not part of this project, and must be downloaded from the Bisq repository's protobuf file directory.
TODO @ripcurlx, please review https://github.com/ghubstan/bisq-api-reference/pull/11
You can download them by running this script from your IDE or a shell:
$ proto-downloader/download-bisq-protos.sh
The java-examples build file will generate the code from the downloaded IDL (.proto) files.
You should be able to generate the protobuf Java sources and all Java examples in your IDE.
In a terminal:
$ cd java-examples $ ./gradlew clean build
Java API Method Examples
Each class in the bisq.rpccalls package is named for the RPC method call being demonstrated.
Their purpose is to show how to construct a gRPC service method request with parameters, send the request, and print a response object if there is one. As a rule, the request is successful if a gRPC StatusRuntimeException is not thrown by the API daemon.
Their usage is simple; there are no program arguments for any of them. Just run them with an IDE program launcher or your shell. However, you will usually need to edit the Java class and re-compile it before running it because these examples know nothing about real Payment Account IDs, Offer IDs, etc. To run the GetOffer.java example, your will need to change the hard-coded offer ID to a real offer ID to avoid a "not found" gRPC StatusRuntimeException from the API daemon.
Java API Bots
Purpose
The Java API bots in this project are meant to be run on mainnet, provide a base for more complex bots, and guide you in developing your own bots.
Put some effort into understanding a bot's code and its configuration before trying it on mainnet. While you get familiar with a bot example, you can run it in dryrun mode to see how it behaves with different configurations (more later). Even better: run it while your Bisq API daemons (seednode, arbitration-node, and a trading peer) are connected to a local BTC regtest network. The API test harness is convenient for this.
Quick And Dirty Test Harness
If you are already familiar with building Bisq source code, and have bitcoin-core binaries on your system's $PATH, you might skip the API test harness setup guide.
Before you try the test harness, make sure your host is not running any bitcoind or Bisq nodes.
Clone the Bisq master branch to your host, build and start it:
# Clone Bisq source repo.
$ git clone https://github.com/bisq-network/bisq.git [some folder]
$ cd [some folder]
# Build Bisq source, install DAO/Regtest wallet files (with coins).
$ ./gradlew clean build :apitest:installDaoSetup -x test
# Start local bitcoind (regtest) node and headless test harness nodes.
$ ./bisq-apitest --apiPassword=xyz --supportingApps=bitcoind,seednode,arbdaemon,alicedaemon,bobdaemon --shutdownAfterTests=false
To shut down the test harness, enter ^C.
Take BSQ / BTC / XMR / Offer Bots
There are six bots for taking offers:
The Take Buy/Sell BTC and XMR Offer bots take 1 or more offers for a given criteria as defined in each bot's configuration file (more later). After the configured maximum number of offers have been taken, the bot shuts down the API daemon and itself because trade payments are made outside Bisq. Bisq nodes (UI or API) do not communicate with your banks and XMR wallets, and cannot automate fiat and XMR trade payments and deposit confirmations.
The Bisq trade payment protocol steps of the Bisq protocol can be performed in the UI, or you can finish the trade with an API daemon and manual CLI commands:
# If you are a BTC buyer, notify peer you have initiated fiat or XMR payment.
$ ./bisq-cli --password=xyz --port=9998 confirmpaymentstarted --trade-id=<trade-id>
# If you are a BTC seller, notify peer your have received fiat or XMR payment.
$ ./bisq-cli --password=xyz --port=9998 confirmpaymentreceived --trade-id=<trade-d>
# Close your completed trade (move it to your trade history).
$ ./bisq-cli --password=xyz --port=9998 closetrade --trade-id=<trade-id>
The Take Buy/Sell BSQ bots take 1 or more offers for a given criteria as defined in each bot's configuration file (more later). After the configured maximum number of offers have been taken, the bot shuts down itself, but not the API daemon. BSQ Swaps can be fully automated by the API because the swap transaction is completed within seconds of taking a BSQ Swap offer.
Take Best Priced Offer To Buy Btc
Purpose (Sell High)
This bot waits for attractively priced BUY BTC (with fiat) offers to appear, and takes 1 or more of them according to the bot's configuration. The bot will consider only those offers created with the same payment method associated with your bot's configured payment account id.
The benefit this bot provides is freeing up user time spent watching the offer book in the UI, waiting for the right offer to take. The disadvantage is having to perform some trade protocol steps outside the API daemon. Fiat payment confirmations must be done as they are when using the Bisq UI -- outside the Bisq application. After bank payments are confirmed in your online banking system, trades can be completed in the desktop UI, or via API CLI commands.
Warning
Take special care to not run the Bisq API daemon and the desktop application at the same time on the same host.
Use Cases, Usage and Configuration
This information is found in the source code's Java class level documentation .
Creating And Using Runnable TakeBestPricedOfferToBuyBtc Jar
To create a runnable jar, see Creating Runnable Jars. To run the jar, edit the conf file for your use case, and use the java -jar command:
$ java -jar take-best-priced-offer-to-buy-btc.jar \
--password=xyz \
--dryrun=false \
--conf=take-best-priced-offer-to-buy-btc.conf
Take Best Priced Offer To Sell Btc
Purpose (Buy Low)
This bot waits for attractively priced SELL BTC (for fiat) offers to appear, and takes 1 or more of them according to the bot's configuration. The bot will consider only those offers created with the same payment method associated with your bot's configured payment account id.
The benefit this bot provides is freeing up user time spent watching the offer book in the UI, waiting for the right offer to take. Low-priced BTC offers are taken relatively quickly; this bot increases the chance of beating other nodes to the offer. The disadvantage is having to perform some trade protocol steps outside the API daemon. Fiat payments must be sent as they are when using the Bisq UI -- outside the Bisq application. After bank payments are made in your online banking system, trades can be completed in the desktop UI, or via API CLI commands.
Warning
Take special care to not run the Bisq API daemon and the desktop application at the same time on the same host.
Use Cases, Usage and Configuration
This information is found in the source code's Java class level documentation .
Creating And Using Runnable TakeBestPricedOfferToSellBtc Jar
To create a runnable jar, see Creating Runnable Jars. To run the jar, edit the conf file for your use case, and use the java -jar command:
$ java -jar take-best-priced-offer-to-sell-btc.jar \
--password=xyz \
--dryrun=false \
--conf=take-best-priced-offer-to-sell-btc.conf
Take Best Priced Offer To Buy Bsq
Purpose (Sell High)
This bot waits for attractively priced BUY BSQ (with BTC) offers to appear, and takes 1 or more of them according to the bot's configuration. The bot will consider only those offers created with the same payment method associated with your bot's configured payment account id.
Warning
Take special care to not run the Bisq API daemon and the desktop application at the same time on the same host.
Use Cases, Usage and Configuration
This information is found in the source code's Java class level documentation .
Creating And Using Runnable TakeBestPricedOfferToBuyBsq Jar
To create a runnable jar, see Creating Runnable Jars. To run the jar, edit the conf file for your use case, and use the java -jar command:
$ java -jar take-best-priced-offer-to-buy-bsq.jar \
--password=xyz \
--dryrun=false \
--conf=take-best-priced-offer-to-buy-bsq.conf
Take Best Priced Offer To Sell Bsq
Purpose (Buy Low)
This bot waits for attractively priced SELL BSQ (for BTC) offers to appear, and takes 1 or more of them according to the bot's configuration. The bot will consider only those offers created with the same payment method associated with your bot's configured payment account id.
Warning
Take special care to not run the Bisq API daemon and the desktop application at the same time on the same host.
Use Cases, Usage and Configuration
This information is found in the source code's Java class level documentation .
Creating And Using Runnable TakeBestPricedOfferToSellBsq Jar
To create a runnable jar, see Creating Runnable Jars. To run the jar, edit the conf file for your use case, and use the java -jar command:
$ java -jar take-best-priced-offer-to-sell-bsq.jar \
--password=xyz \
--dryrun=false \
--conf=take-best-priced-offer-to-sell-bsq.conf
Take Best Priced Offer To Buy Xmr
Purpose (Sell High)
This bot waits for attractively priced BUY XMR (with BTC) offers to appear, and takes 1 or more of them according to the bot's configuration. The bot will consider only those offers created with the same payment method associated with your bot's configured payment account id.
Warning
Take special care to not run the Bisq API daemon and the desktop application at the same time on the same host.
Use Cases, Usage and Configuration
This information is found in the source code's Java class level documentation .
Creating And Using Runnable TakeBestPricedOfferToBuyXmr Jar
To create a runnable jar, see Creating Runnable Jars. To run the jar, edit the conf file for your use case, and use the java -jar command:
$ java -jar take-best-priced-offer-to-buy-xmr.jar \
--password=xyz \
--dryrun=false \
--conf=take-best-priced-offer-to-buy-xmr.conf
Take Best Priced Offer To Sell Xmr
Purpose (Buy Low)
This bot waits for attractively priced SELL XMR (for BTC) offers to appear, and takes 1 or more of them according to the bot's configuration. The bot will consider only those offers created with the same payment method associated with your bot's configured payment account id.
Warning
Take special care to not run the Bisq API daemon and the desktop application at the same time on the same host.
Use Cases, Usage and Configuration
This information is found in the source code's Java class level documentation .
Creating And Using Runnable TakeBestPricedOfferToSellXmr Jar
To create a runnable jar, see Creating Runnable Jars. To run the jar, edit the conf file for your use case, and use the java -jar command:
$ java -jar take-best-priced-offer-to-sell-xmr.jar \
--password=xyz \
--dryrun=false \
--conf=take-best-priced-offer-to-sell-xmr.conf
Creating Runnable Jars
You can create runnable jars for these bots and run them in a terminal. After building the java-examples project, run the script java-examples/scripts/create-bot-jars.sh. You can run the jar from the java-examples/scripts/java-examples folder created by the script, or copy that folder where you like and run it from there.
Here are the steps to create runnable bot jars.
# Build the java-examples project.
$ cd java-examples
$ ./gradlew clean build
# Build the runnable bot jars. Each jar contains one class, with its dependencies defined in its MANIFEST.MF.
$ scripts/create-bot-jars.sh
Each jar has its own conf file, generated from the bot source code's properties file. For example,
- take-best-priced-offer-to-buy-btc.jar
- take-best-priced-offer-to-buy-btc.conf
are created from
- TakeBestPricedOfferToBuyBtc.java
- TakeBestPricedOfferToBuyBtc.properties
To run it, edit the conf file for your use case and run a java -jar command:
$ java -jar take-best-priced-offer-to-sell-btc.jar \
--password=xyz \
--dryrun=false \
--conf=take-best-priced-offer-to-sell-btc.conf
You can rename a conf file as you like, and save several copies for specific use cases.
Gradle Build File
This project's Gradle build file, shows how to generate the necessary protobuf classes from the Bisq .proto files.