diff --git a/java-examples/README.md b/java-examples/README.md index ab12cd5..2f78b97 100644 --- a/java-examples/README.md +++ b/java-examples/README.md @@ -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= @@ -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.