nik/bisq-api-reference
1
0
Fork 0
mirror of https://github.com/bisq-network/bisq-api-reference.git synced 2026-01-26 17:33:33 +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
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)).
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.
experienced Java coders (and be easily portable to
other [gRPC supported language bindings](https://grpc.io/docs/languages)). 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](#generating-protobuf-code)
### 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).
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.
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.
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
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](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.
## [Java API Bots](#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.
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.
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](https://github.com/bisq-network/bisq/blob/master/apitest/docs/api-beta-test-guide.md) is
convenient for this.
@ -131,22 +132,23 @@ To shut down the test harness, enter **^C**.
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)
* [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)
* [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
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 **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
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:
```asciidoc
# 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>
@ -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
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
and itself (the bot). The user should then proceed to start the desktop UI application and complete the new trades.
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 the 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
nodes at taking the offer.
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.
The disadvantage is that if the user takes offers with the API, she must complete the trades with the desktop UI. This
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.
**Warning**
The criteria for determining which offers to take are defined in the bot's configuration file
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.
Take special care to not run the Bisq API daemon and the desktop application at the same time on the same host.
**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
GBP at or below the current market GBP price if:
* 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
* ...
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/TakeBestPricedOfferToBuyBtc.java)
.
**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
$ java -jar take-best-priced-offer-to-buy-btc.jar \
--password=xyz \
@ -216,12 +238,13 @@ $ java -jar take-best-priced-offer-to-buy-btc.jar \
### [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
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.
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.
```asciidoc
# Build the java-examples project.
$ cd java-examples
@ -231,22 +254,20 @@ $ ./gradlew clean build
$ 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
are created from
* TakeBestPricedOfferToBuyBtc.java
* TakeBestPricedOfferToBuyBtc.java
* TakeBestPricedOfferToBuyBtc.properties
To run it, edit the conf file for your use case and run a java -jar command:
```asciidoc
$ java -jar take-best-priced-offer-to-buy-btc.jar \
--password=xyz \
--dryrun=false \
--conf=take-best-priced-offer-to-buy-btc.conf
$ 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.