nik/bisq-api-reference
1
0
Fork 0
mirror of https://github.com/bisq-network/bisq-api-reference.git synced 2026-08-29 04:57:08 +00:00
Code Issues Packages Projects Releases Wiki Activity

Describe btc bots, refer to class javadocs

Browse Source
This commit is contained in:
ghubstan 2022-07-04 15:04:22 -03:00
parent fd31922e97
commit 618268805f
No known key found for this signature in database
GPG Key ID: E35592D6800A861E
1 changed files with 87 additions and 66 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

153
java-examples/README.md
View File

@ -39,15 +39,16 @@ some effort into understanding a bot's code and its configuration before trying
The TakeBestPricedOffer* bots could be combined into a single class, and use multithreaded task scheduling instead of 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 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](https://grpc.io/docs/languages)). experienced Java coders (and be easily portable to
For non-developers, splitting up a one-size-fits-all TakeBestPricedOffer also makes them easier to configure for various other [gRPC supported language bindings](https://grpc.io/docs/languages)). For non-developers, splitting up a
BTC/Fiat, XMR/BTC, and BSQ/BTC market use cases. 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](#generating-protobuf-code) ## [Generating Protobuf Code](#generating-protobuf-code)
### Download IDL (.proto) Files From The [Bisq Repo](https://github.com/bisq-network/bisq) ### Download IDL (.proto) Files From The [Bisq Repo](https://github.com/bisq-network/bisq)
The protobuf IDL files are not part of this project, and must be downloaded from the Bisq repository's The protobuf IDL files are not part of this project, and must be downloaded from the Bisq repository's
[protobuf file directory](https://github.com/bisq-network/bisq/tree/master/proto/src/main/proto). [protobuf file directory](https://github.com/bisq-network/bisq/tree/master/proto/src/main/proto).
TODO @ripcurlx, please review https://github.com/ghubstan/bisq-api-reference/pull/11 TODO @ripcurlx, please review https://github.com/ghubstan/bisq-api-reference/pull/11
@ -78,27 +79,27 @@ the [bisq.rpccalls](https://github.com/bisq-network/bisq-api-reference/tree/main
package is named for the RPC method call being demonstrated. 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 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 response object if there is one. As a rule, the request is successful if a gRPC StatusRuntimeException is not thrown by
by the API daemon. 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 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 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 examples know nothing about real Payment Account IDs, Offer IDs, etc. To run the
[GetOffer.java](https://github.com/bisq-network/bisq-api-reference/blob/main/java-examples/src/main/java/bisq/rpccalls/GetOffer.java) [GetOffer.java](https://github.com/bisq-network/bisq-api-reference/blob/main/java-examples/src/main/java/bisq/rpccalls/GetOffer.java)
example, your will need to change the hard-coded offer ID to a real offer ID to avoid a "not found" gRPC 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. StatusRuntimeException from the API daemon.
## [Java API Bots](#java-api-bots) ## [Java API Bots](#java-api-bots)
### Purpose ### 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 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
in developing your own bots. developing your own bots.
Put some effort into understanding a bot's code and its configuration before trying it on mainnet. While you get 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 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 (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. connected to a local BTC regtest network.
The [API test harness](https://github.com/bisq-network/bisq/blob/master/apitest/docs/api-beta-test-guide.md) is The [API test harness](https://github.com/bisq-network/bisq/blob/master/apitest/docs/api-beta-test-guide.md) is
convenient for this. convenient for this.
@ -131,22 +132,23 @@ To shut down the test harness, enter **^C**.
There are six bots for taking offers: There are six bots for taking offers:
* [TakeBestPricedOfferToBuyBtc](#take-best-priced-offer-to-buy-btc)
* [TakeBestPricedOfferToSellBtc](#take-best-priced-offer-to-sell-btc)
* [TakeBestPricedOfferToBuyBsq (From You)](https://github.com/bisq-network/bisq-api-reference/blob/split-up-take-btc-offer-bots/java-examples/src/main/java/bisq/bots/TakeBestPricedOfferToBuyBsq.java) * [TakeBestPricedOfferToBuyBsq (From You)](https://github.com/bisq-network/bisq-api-reference/blob/split-up-take-btc-offer-bots/java-examples/src/main/java/bisq/bots/TakeBestPricedOfferToBuyBsq.java)
* [TakeBestPricedOfferToSellBsq (To You)](https://github.com/bisq-network/bisq-api-reference/blob/split-up-take-btc-offer-bots/java-examples/src/main/java/bisq/bots/TakeBestPricedOfferToSellBsq.java) * [TakeBestPricedOfferToSellBsq (To You)](https://github.com/bisq-network/bisq-api-reference/blob/split-up-take-btc-offer-bots/java-examples/src/main/java/bisq/bots/TakeBestPricedOfferToSellBsq.java)
* [TakeBestPricedOfferToBuyBtc (From You)](https://github.com/bisq-network/bisq-api-reference/blob/split-up-take-btc-offer-bots/java-examples/src/main/java/bisq/bots/TakeBestPricedOfferToBuyBtc.java)
* [TakeBestPricedOfferToSellBtc (To You)](https://github.com/bisq-network/bisq-api-reference/blob/split-up-take-btc-offer-bots/java-examples/src/main/java/bisq/bots/TakeBestPricedOfferToSellBtc.java)
* [TakeBestPricedOfferToBuyXmr (From You)](https://github.com/bisq-network/bisq-api-reference/blob/split-up-take-btc-offer-bots/java-examples/src/main/java/bisq/bots/TakeBestPricedOfferToBuyXmr.java) * [TakeBestPricedOfferToBuyXmr (From You)](https://github.com/bisq-network/bisq-api-reference/blob/split-up-take-btc-offer-bots/java-examples/src/main/java/bisq/bots/TakeBestPricedOfferToBuyXmr.java)
* [TakeBestPricedOfferToSellXmr (To You)](https://github.com/bisq-network/bisq-api-reference/blob/split-up-take-btc-offer-bots/java-examples/src/main/java/bisq/bots/TakeBestPricedOfferToSellXmr.java) * [TakeBestPricedOfferToSellXmr (To You)](https://github.com/bisq-network/bisq-api-reference/blob/split-up-take-btc-offer-bots/java-examples/src/main/java/bisq/bots/TakeBestPricedOfferToSellXmr.java)
The **Take Buy/Sell BTC and XMR Offer** bots take 1 or more offers for a given criteria as defined in each bot's 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 configuration file (more later). After the configured maximum number of offers have been taken, the bot shuts down the
the API daemon and itself because trade payments are made outside Bisq. Bisq nodes (UI or API) do not communicate API daemon and itself because trade payments are made outside Bisq. Bisq nodes (UI or API) do not communicate with your
with your banks and XMR wallets, and *cannot automate fiat and XMR trade payments and deposit confirmations*. 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 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: an API daemon and manual CLI commands:
```asciidoc ```asciidoc
# If you are a BTC buyer, notify peer you have initiated fiat or XMR payment. # 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> $ ./bisq-cli --password=xyz --port=9998 confirmpaymentstarted --trade-id=<trade-id>
@ -163,50 +165,70 @@ The **Take Buy/Sell BSQ** bots take 1 or more offers for a given criteria as def
daemon. BSQ Swaps can be fully automated by the API because the swap transaction is completed within seconds of taking a daemon. BSQ Swaps can be fully automated by the API because the swap transaction is completed within seconds of taking a
BSQ Swap offer. BSQ Swap offer.
#### [TakeBestPricedOfferToSellBtc (To You)](https://github.com/bisq-network/bisq-api-reference/blob/split-up-take-btc-offer-bots/java-examples/src/main/java/bisq/bots/TakeBestPricedOfferToSellBtc.java) ### [TakeBestPricedOfferToBuyBtc (From You)](#take-best-priced-offer-to-buy-btc)
**Purpose** **Purpose (Sell High)**
This bot waits for attractively priced SELL BTC offers to appear, takes the offers, then shuts down both the API daemon This bot waits for attractively priced BUY BTC (with fiat) offers to appear, and takes 1 or more of them according to
and itself (the bot). The user should then proceed to start the desktop UI application and complete the new trades. 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 the user time spent watching the offer book in the UI, waiting for the right 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 the other offer to take. The disadvantage is having to perform some trade protocol steps outside the API daemon.
nodes at taking the offer. 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.
The disadvantage is that if the user takes offers with the API, she must complete the trades with the desktop UI. This **Warning**
problem is due to the inability of the API to fully automate every step of the trading protocol. Sending fiat or XMR
payments, and confirming their receipt, are manual activities performed outside the Bisq daemon and desktop UI. When you
switch back and forth between the API daemon and UI, be careful not to let them run at the same time.
The criteria for determining which offers to take are defined in the bot's configuration file Take special care to not run the Bisq API daemon and the desktop application at the same time on the same host.
TakeBestPricedOfferToSellBtc.properties (located in project's src/main/resources directory). The individual
configurations are commented in the existing TakeBestPricedOfferToSellBtc.properties, which should be used as a template
for your own use case.
**Use Cases** **Use Cases, Usage and Configuration**
One possible use case for this bot is to buy BTC with GBP, e.g., take a "Faster Payment" offer to sell BTC (to you) for This information is found in
GBP at or below the current market GBP price if: the [source code's Java class level documentation](https://github.com/bisq-network/bisq-api-reference/blob/split-up-take-btc-offer-bots/java-examples/src/main/java/bisq/bots/TakeBestPricedOfferToBuyBtc.java)
.
* the offer maker is a preferred trading peer
* the offer's BTC amount is between 0.10 and 0.25 BTC
* the current transaction mining fee rate is less than or equal 20 sats / byte
**Usage**
**Configuration**
* Param 1
* Param 2
* Param 3
* ...
**Creating And Using Runnable TakeBestPricedOfferToSellBtc Jar** **Creating And Using Runnable TakeBestPricedOfferToSellBtc Jar**
To create the runnable jar, see [Creating Runnable Jars](#creating-runnable-jars). To create a runnable jar, see [Creating Runnable Jars](#creating-runnable-jars). To run the jar, edit the conf file for
your use case, and use the java -jar command:
```asciidoc
$ java -jar take-best-priced-offer-to-sell-btc.jar \
--password=xyz \
--dryrun=false \
--conf=take-best-priced-offer-to-sell-btc.conf
```
### [TakeBestPricedOfferToSellBtc (To You)](#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](https://github.com/bisq-network/bisq-api-reference/blob/split-up-take-btc-offer-bots/java-examples/src/main/java/bisq/bots/TakeBestPricedOfferToSellBtc.java)
.
**Creating And Using Runnable TakeBestPricedOfferToSellBtc Jar**
To create a runnable jar, see [Creating Runnable Jars](#creating-runnable-jars). To run the jar, edit the conf file for
your use case, and use the java -jar command:
To run the jar, edit the conf file for your use case, and run it:
```asciidoc ```asciidoc
$ java -jar take-best-priced-offer-to-buy-btc.jar \ $ java -jar take-best-priced-offer-to-buy-btc.jar \
--password=xyz \ --password=xyz \
@ -216,12 +238,13 @@ $ java -jar take-best-priced-offer-to-buy-btc.jar \
### [Creating Runnable Jars](#creating-runnable-jars) ### [Creating Runnable Jars](#creating-runnable-jars)
You can create runnable jars for these bots and run them in a terminal. After building the java-examples project, run 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 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 **java-examples/scripts/java-examples** folder created by the script, or copy that folder where you like and run it from
from there. there.
Here are the steps to create runnable bot jars. Here are the steps to create runnable bot jars.
```asciidoc ```asciidoc
# Build the java-examples project. # Build the java-examples project.
$ cd java-examples $ cd java-examples
@ -231,22 +254,20 @@ $ ./gradlew clean build
$ scripts/create-bot-jars.sh $ scripts/create-bot-jars.sh
``` ```
Each jar has its own conf file, generated from the bot source code's properties file. For example, 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.jar
* take-best-priced-offer-to-buy-btc.conf * take-best-priced-offer-to-buy-btc.conf
are created from are created from
* TakeBestPricedOfferToBuyBtc.java
* TakeBestPricedOfferToBuyBtc.java
* TakeBestPricedOfferToBuyBtc.properties * TakeBestPricedOfferToBuyBtc.properties
To run it, edit the conf file for your use case and run a java -jar command: To run it, edit the conf file for your use case and run a java -jar command:
```asciidoc ```asciidoc
$ java -jar take-best-priced-offer-to-buy-btc.jar \ $ java -jar take-best-priced-offer-to-sell-btc.jar \ --password=xyz \ --dryrun=false \ --conf=take-best-priced-offer-to-sell-btc.conf
--password=xyz \
--dryrun=false \
--conf=take-best-priced-offer-to-buy-btc.conf
``` ```
You can rename a conf file as you like, and save several copies for specific use cases. You can rename a conf file as you like, and save several copies for specific use cases.