mirror of
https://github.com/bisq-network/bisq-api-reference.git
synced 2026-01-26 17:33:33 +00:00
[WIP] Save java-examples/README.md
This commit is contained in:
ghubstan
parent
195b62c477
commit
28deeb81e0
@ -1,11 +1,207 @@
|
||||
# Bisq API Java Examples
|
||||
# Bisq API Java Examples And Bots
|
||||
|
||||
This subproject contains Java classes demonstrating API gRPC method calls.
|
||||
This subproject contains:
|
||||
* [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.
|
||||
|
||||
Each class in
|
||||
* [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
|
||||
other languages supported by [gRPC](https://grpc.io/docs/languages), please use these Java bot examples, not the
|
||||
Python 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)
|
||||
that could be used as a template for your own API bot project.
|
||||
|
||||
## Risks And Warnings
|
||||
|
||||
### 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
|
||||
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.
|
||||
|
||||
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)
|
||||
|
||||
[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
|
||||
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.
|
||||
|
||||
TODO Add warning about this to Python Examples README.
|
||||
|
||||
## 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 repo](https://github.com/bisq-network/bisq/tree/master/proto/src/main/proto).
|
||||
|
||||
You can download them by running
|
||||
[this script](https://github.com/bisq-network/bisq-api-reference/blob/main/proto-downloader/download-bisq-protos.sh)
|
||||
from your IDE or a shell:
|
||||
```asciidoc
|
||||
$ proto-downloader/download-bisq-protos.sh
|
||||
```
|
||||
|
||||
The java-examples [build file](https://github.com/bisq-network/bisq-api-reference/blob/main/java-examples/build.gradle)
|
||||
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:
|
||||
```asciidoc
|
||||
$ cd java-examples
|
||||
$ ./gradlew clean build
|
||||
```
|
||||
|
||||
## Java API Method Examples
|
||||
|
||||
Each class in
|
||||
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.
|
||||
|
||||
The subproject uses a
|
||||
a [Gradle build file](https://github.com/bisq-network/bisq-api-reference/blob/main/java-examples/build.gradle), also
|
||||
demonstrating how to generate the necessary protobuf classes from the Bisq .proto files.
|
||||
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 was successful if
|
||||
no gRPC StatusRuntimeException was received from 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 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
|
||||
[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"
|
||||
exception.
|
||||
|
||||
## Java API Bots
|
||||
|
||||
### Purpose
|
||||
|
||||
The Java API bots in this project are meant run on mainnet, provide a base for more complex bots, and guide you in
|
||||
developing your own bots.
|
||||
|
||||
### 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
|
||||
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.
|
||||
|
||||
#### 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 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).
|
||||
|
||||
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:
|
||||
```asciidoc
|
||||
#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.
|
||||
$ ./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**.
|
||||
|
||||
#### Creating And Using Runnable Bot Jars
|
||||
|
||||
TODO (more later)
|
||||
|
||||
### Take BSQ / BTC / XMR / Offer Bots
|
||||
|
||||
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)
|
||||
* [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)
|
||||
|
||||
* [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)
|
||||
* [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)
|
||||
|
||||
* [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** 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. The Bisq API *cannot automate the fiat or XMR trade payment and
|
||||
receipt confirmation steps of the protocol*. When an offer is taken by the API, the trade payment steps of the protocol
|
||||
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
|
||||
(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.
|
||||
|
||||
#### [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)
|
||||
|
||||
**Purpose**
|
||||
|
||||
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.
|
||||
|
||||
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 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.
|
||||
Also, 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 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.
|
||||
|
||||
**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
|
||||
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
|
||||
|
||||
**Class Doc Link**
|
||||
|
||||
**Configuration**
|
||||
|
||||
* Param 1
|
||||
* Param 2
|
||||
* Param 3
|
||||
* ...
|
||||
|
||||
**Usage**
|
||||
|
||||
```asciidoc
|
||||
$ java -jar x.jar --password=xyz --conf=[path.conf] --dryrun=true
|
||||
```
|
||||
|
||||
## Gradle Build File
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user