nik/bisq-api-reference
1
0
Fork 0
mirror of https://github.com/bisq-network/bisq-api-reference.git synced 2026-05-21 12:34:14 +00:00
Code Issues Packages Projects Releases Wiki Activity

Save README work in progress

Browse Source
This commit is contained in:
ghubstan 2022-07-02 11:59:17 -03:00
parent 4133a4c047
commit 483b2d8eab
No known key found for this signature in database
GPG Key ID: E35592D6800A861E
1 changed files with 86 additions and 82 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

130
java-examples/README.md
View File

@ -1,56 +1,61 @@
# Bisq API Java Examples And Bots # Bisq API Java Examples And Bots
This subproject contains: This subproject contains:
* [Java API rpc examples](https://github.com/bisq-network/bisq-api-reference/tree/main/java-examples/src/main/java/bisq/rpccalls) * [Java API rpc examples](https://github.com/bisq-network/bisq-api-reference/tree/main/java-examples/src/main/java/bisq/rpccalls)
demonstrating how to send API gRPC requests, and handle responses. demonstrating how to send API gRPC requests, and handle responses.
* [Java API bots](https://github.com/bisq-network/bisq-api-reference/tree/main/java-examples/src/main/java/bisq/bots) * [Java API bots](https://github.com/bisq-network/bisq-api-reference/tree/main/java-examples/src/main/java/bisq/bots)
to use as is on mainnet, and demonstrate how to write new API bots. If interested in porting any bot code to to use as is on mainnet, and demonstrate how to write new API bots. If interested in porting any bot code to other
other languages supported by [gRPC](https://grpc.io/docs/languages), please use these Java bot examples, not the languages supported by [gRPC](https://grpc.io/docs/languages), please use these Java bot examples, not the Python
Python examples. The Python examples were written by a Python noob, and don't handle errors. examples. The Python examples were written by a Python noob, and don't handle errors.
TODO Add warning about this to Python Examples README.
* A [Gradle build file](https://github.com/bisq-network/bisq-api-reference/blob/main/java-examples/build.gradle) * A [Gradle build file](https://github.com/bisq-network/bisq-api-reference/blob/main/java-examples/build.gradle)
that could be used as a template for your own API bot project. that could be used as a template for your own Java API bot project.
## Risks And Warnings ## Risks, Warnings and Flaws
### Never Run API Daemon and [Bisq GUI](https://bisq.network) On Same Host At Same Time ### Never Run API Daemon and [Bisq GUI](https://bisq.network) 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 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, fighting over the wallet and ports, doing so will probably corrupt your wallet. Before starting the API daemon, make
make sure your GUI is shut down, and vice-versa. Please back up your mainnet wallet early and often with the GUI. sure your GUI is shut down, and vice-versa. Please back up your mainnet wallet early and often with the GUI.
TODO Add warning about this to Python Examples README, Api Reference, and Beta Test Guide.
### Go Slow (But Much Faster Than You Click Buttons In The GUI) ### Go Slow (But Much Faster Than You Click Buttons In The GUI)
[Bisq](https://bisq.network) was designed to respond to manual clicks in the user interface. It is not a [Bisq](https://bisq.network) 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 high-throughput, high-performance system supporting atomic transactions. Care must be taken to avoid problems due to
problems due to slow wallet updates on your disk, and Tor network latency. The API daemon enforces limits on request slow wallet updates on your disk, and Tor network latency. The API daemon enforces limits on request frequency via call
frequency via call rate metering, but you cannot assume bots can perform tasks as rapidly as the API daemon's call rate metering, but you cannot assume bots can perform tasks as rapidly as the API daemon's call rate meters allow.
rate meters allow.
### Run Bots On Mainnet At Your Own Risk ### 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 This document would not state "these bots can be run on mainnet, as is" without reasonable confidence on the part of the
the code's author, but if you do, you do so at your own risk. Copious details about running them on a local BTC code's author, but if you do, you do so at your own risk. Copious details about running them on a local BTC regtest
regtest network, running on mainnet in **dryrun** mode, and each bot's configuration is provided in this document. network, running on mainnet in **dryrun** mode, and each bot's configuration is provided in this document. Please put
Please put some effort into understanding a bot's code and its configuration before trying it on mainnet. some effort into understanding a bot's code and its configuration before trying it on mainnet.
TODO Add warning about this to Python Examples README. ### 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](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) ### 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 The protobuf IDL files are not part of this project, and must be downloaded from the Bisq repository's
[Bisq repo](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
You can download them by running You can download them by running
[this script](https://github.com/bisq-network/bisq-api-reference/blob/main/proto-downloader/download-bisq-protos.sh) [this script](https://github.com/bisq-network/bisq-api-reference/blob/main/proto-downloader/download-bisq-protos.sh)
from your IDE or a shell: from your IDE or a shell:
```asciidoc ```asciidoc
$ proto-downloader/download-bisq-protos.sh $ proto-downloader/download-bisq-protos.sh
``` ```
@ -61,9 +66,9 @@ 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. You should be able to generate the protobuf Java sources and all Java examples in your IDE.
In a terminal: In a terminal:
```asciidoc ```asciidoc
$ cd java-examples $ cd java-examples $ ./gradlew clean build
$ ./gradlew clean build
``` ```
## Java API Method Examples ## Java API Method Examples
@ -72,46 +77,44 @@ Each class in
the [bisq.rpccalls](https://github.com/bisq-network/bisq-api-reference/tree/main/java-examples/src/main/java/bisq/rpccalls) the [bisq.rpccalls](https://github.com/bisq-network/bisq-api-reference/tree/main/java-examples/src/main/java/bisq/rpccalls)
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 Their purpose is to show how to construct a gRPC service method request with parameters, send the request, and print a
request, and print a response object if there is one. As a rule, the request was successful if response object if there is one. As a rule, the request is successful if a gRPC StatusRuntimeException is not thrown
no gRPC StatusRuntimeException was received from the API daemon. by the API daemon.
Their usage is simple; there are no program arguments for any of them. Just run them with an IDE Their usage is simple; there are no program arguments for any of them. Just run them with an IDE program launcher or
program launcher or your shell. your shell. However, you will usually need to edit the Java class and re-compile it before running it because these
However, you will often 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" example, your will need to change the hard-coded offer ID to a real offer ID to avoid a "not found" gRPC
exception. StatusRuntimeException from the API daemon.
## Java API Bots ## Java API Bots
### Purpose ### Purpose
The Java API bots in this project are meant run on mainnet, provide a base for more complex bots, and guide you in The Java API bots in this project are meant to be run on mainnet, provide a base for more complex bots, and guide you
developing your own bots. in developing your own bots.
### Run on mainnet at your own risk! ### Run on mainnet at your own risk!
You need to understand a bot's code and its configuration before trying it on mainnet. While you get familiar with You need to understand a bot's code and its configuration before trying it on mainnet. While you get familiar with a bot
a bot example, you can run it in **dryrun** mode to see how it behaves with different configurations (more later). example, you can run it in **dryrun** mode to see how it behaves with different configurations (more later). Even
Even better: run it while your Bisq API daemons (seednode, arbitration-node, and a trading peer) are connected to a better: run it while your Bisq API daemons (seednode, arbitration-node, and a trading peer) are connected to a local
local BTC regtest network. 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.
#### Quick And Dirty Test Harness #### Quick And Dirty Test Harness
TODO: Create issue for out of date https://bisq.wiki/Downloading_and_installing#Build_from_source? If you are already familiar
with [building Bisq source code](https://github.com/bisq-network/bisq/blob/master/docs/build.md), and
If you are already familiar with [building Bisq source code](https://github.com/bisq-network/bisq/blob/master/docs/build.md), have [bitcoin-core binaries](https://github.com/bitcoin/bitcoin) on your system's $PATH, you might skip the
and have [bitcoin-core binaries](https://github.com/bitcoin/bitcoin) on your system's $PATH, you might skip the
[API test harness setup guide](https://github.com/bisq-network/bisq/blob/master/apitest/docs/api-beta-test-guide.md). [API test harness setup guide](https://github.com/bisq-network/bisq/blob/master/apitest/docs/api-beta-test-guide.md).
Before you try the test harness, make sure your host is not running any bitcoind or Bisq nodes. 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 the Bisq master branch to your host, build and start it:
```asciidoc ```asciidoc
#Clone Bisq source repo. #Clone Bisq source repo.
$ git clone https://github.com/bisq-network/bisq.git [some folder] $ git clone https://github.com/bisq-network/bisq.git [some folder]
@ -123,6 +126,7 @@ $ ./gradlew clean build :apitest:installDaoSetup -x test
#Start local bitcoind (regtest) node and headless test harness nodes. #Start local bitcoind (regtest) node and headless test harness nodes.
$ ./bisq-apitest --apiPassword=xyz --supportingApps=bitcoind,seednode,arbdaemon,alicedaemon,bobdaemon --shutdownAfterTests=false $ ./bisq-apitest --apiPassword=xyz --supportingApps=bitcoind,seednode,arbdaemon,alicedaemon,bobdaemon --shutdownAfterTests=false
``` ```
To shut down the test harness, enter **^C**. To shut down the test harness, enter **^C**.
#### Creating And Using Runnable Bot Jars #### Creating And Using Runnable Bot Jars
@ -133,16 +137,15 @@ TODO (more later)
There are four bots for taking offers: There are four bots for taking offers:
* [TakeBestPricedOfferToBuyBsq (From You)](https://github.com/bisq-network/bisq-api-reference/blob/update-java-examples-readme/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/update-java-examples-readme/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/update-java-examples-readme/java-examples/src/main/java/bisq/bots/TakeBestPricedOfferToBuyBtc.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/update-java-examples-readme/java-examples/src/main/java/bisq/bots/TakeBestPricedOfferToSellBtc.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** bots take 1 or more offers for a given criteria as defined in each bot's configuration file The **Take Buy/Sell BTC** 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 (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. The Bisq API *cannot automate the fiat or XMR trade payment and itself because trade payments are made outside Bisq. The Bisq API *cannot automate the fiat or XMR trade payment and
@ -150,36 +153,36 @@ receipt confirmation steps of the protocol*. When an offer is taken by the API,
must be performed in the UI. must be performed in the UI.
The **Take Buy/Sell BSQ** bots take 1 or more offers for a given criteria as defined in each bot's configuration file 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 (more later). After the configured maximum number of offers have been taken, the bot shuts down itself, but not the API
API daemon. BSQ Swaps can be fully automated by the API because the swap transaction is completed within seconds of daemon. BSQ Swaps can be fully automated by the API because the swap transaction is completed within seconds of taking a
taking a BSQ Swap offer. BSQ Swap offer.
#### [TakeBestPricedOfferToSellBtc (To You)](https://github.com/bisq-network/bisq-api-reference/blob/update-java-examples-readme/java-examples/src/main/java/bisq/bots/TakeBestPricedOfferToSellBtc.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)
**Purpose** **Purpose**
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 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. and itself (the bot). The user should then proceed to start the desktop UI application and complete the new trades.
The benefit this bot provides is freeing up the user time spent watching the offer book in the UI, waiting for the The benefit this bot provides is freeing up the user time spent watching the offer book in the UI, waiting for the right
right offer to take. Low-priced BTC offers are taken relatively quickly; this bot increases the chance of beating offer to take. Low-priced BTC offers are taken relatively quickly; this bot increases the chance of beating the other
the other nodes at taking the offer. nodes at taking the offer.
The disadvantage is that if the user takes offers with the API, she must complete the trades with the desktop UI. The disadvantage is that if the user takes offers with the API, she must complete the trades with the desktop UI. This
This problem is due to the inability of the API to fully automate every step of the trading protocol. Sending fiat or problem is due to the inability of the API to fully automate every step of the trading protocol. Sending fiat or XMR
XMR payments, and confirming their receipt, are manual activities performed outside the Bisq daemon and desktop UI. payments, and confirming their receipt, are manual activities performed outside the Bisq daemon and desktop UI. Also,
Also, the API and the desktop UI cannot run at the same time. Care must be taken to shut down one before starting the API and the desktop UI cannot run at the same time. Care must be taken to shut down one before starting the other.
the other.
The criteria for determining which offers to take are defined in the bot's configuration file 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 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 configurations are commented in the existing TakeBestPricedOfferToSellBtc.properties, which should be used as a template
template for your own use case. for your own use case.
**Use Cases** **Use Cases**
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 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: GBP at or below the current market GBP price if:
* the offer maker is a preferred trading peer * the offer maker is a preferred trading peer
* the offer's BTC amount is between 0.10 and 0.25 BTC * 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 * the current transaction mining fee rate is less than or equal 20 sats / byte
@ -201,7 +204,8 @@ $ java -jar x.jar --password=xyz --conf=[path.conf] --dryrun=true
## Gradle Build File ## Gradle Build File
This project's [Gradle build file](https://github.com/bisq-network/bisq-api-reference/blob/main/java-examples/build.gradle), This
project's [Gradle build file](https://github.com/bisq-network/bisq-api-reference/blob/main/java-examples/build.gradle),
shows how to generate the necessary protobuf classes from the Bisq .proto files. shows how to generate the necessary protobuf classes from the Bisq .proto files.