mirrors/bisq
1
0
Fork 0
mirror of https://github.com/bisq-network/bisq.git synced 2024-11-19 01:41:11 +01:00
Code Issues Packages Projects Releases Wiki Activity

Update for bticoind v23 + IDE format

Browse Source
This commit is contained in:
ghubstan 2023-02-13 19:09:01 -03:00
parent b4822761a8
commit f69fb3a959
No known key found for this signature in database
GPG Key ID: 46F220FBD5637C5D
1 changed files with 147 additions and 63 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

210
apitest/docs/api-beta-test-guide.md
View File

@ -10,16 +10,16 @@ Knowledge of Git, Java, and installing bitcoin-core is required.
**Hardware**: A reasonably fast development machine is recommended, with at least 16 Gb RAM and 8 cores.
None of the headless apps use a lot of RAM, but build times can be long on machines with less RAM and fewer cores.
In addition, a slow machine may run into race conditions if asynchronous wallet changes are not persisted to disk
fast enough. Test harness startup and shutdown times may also not happen fast enough, and require test harness
fast enough. Test harness startup and shutdown times may also not happen fast enough, and require test harness
option adjustments to compensate.
**OS**: Linux or Mac OSX
**Shell**: Bash
**Java SDK**: Version 11 - 15 (src and class generation version 11)
**Java SDK**: Version 11 - 16 (src and class generation version 11)
**Bitcoin-Core**: Version 0.19 - 22
**Bitcoin-Core**: Version 0.19 - 23
**Git Client**
@ -27,14 +27,16 @@ option adjustments to compensate.
Beta testing can be done with no knowledge of how git works, but you need a git client to get the source code.
Clone the Bisq master branch into a project folder of your choice. In this document, the root project folder is
Clone the Bisq master branch into a project folder of your choice. In this document, the root project folder is
called `api-beta-test`.
```
$ git clone https://github.com/bisq-network/bisq.git api-beta-test
```
Change your current working directory to `api-beta-test`, build the source, and download / install Bisq’s
pre-configured DAO / dev / regtest setup files.
```
$ cd api-beta-test
$ ./gradlew clean build :apitest:installDaoSetup -x test # if you want to skip Bisq tests
@ -45,14 +47,15 @@ $ ./gradlew clean build :apitest:installDaoSetup # if you want to run
#### Warning: Never run an API daemon and the [Bisq GUI](https://bisq.network) on the same host at the 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.
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.
### Configuration And Start Command
If your bitcoin-core binaries are in your system `PATH`, start bitcoind in regtest-mode, Bisq seednode and arbitration
node daemons, plus Bob & Alice daemons in a bash terminal with the following bash command:
```
$ ./bisq-apitest --apiPassword=xyz \
--supportingApps=bitcoind,seednode,arbdaemon,alicedaemon,bobdaemon \
@ -61,6 +64,7 @@ $ ./bisq-apitest --apiPassword=xyz \
If your bitcoin-core binaries are not in your system `PATH`, you can specify the bitcoin-core bin directory with the
`-–bitcoinPath=<path>` option:
```
$ ./bisq-apitest --apiPassword=xyz \
--supportingApps=bitcoind,seednode,arbdaemon,alicedaemon,bobdaemon \
@ -70,6 +74,7 @@ $ ./bisq-apitest --apiPassword=xyz \
If your bitcoin-core binaries are not statically linked to your BerkleyDB library, you can specify the path to it
with the `–-berkeleyDbLibPath=<path>` option:
```
$ ./bisq-apitest --apiPassword=xyz \
--supportingApps=bitcoind,seednode,arbdaemon,alicedaemon,bobdaemon \
@ -82,6 +87,7 @@ Alternatively, you can specify any or all of these bisq-apitest options in a pro
`apitest/src/main/resources/apitest.properties`.
In this example, a beta tester uses the `apitest.properties` below, instead of `bisq-cli` options.
```
supportingApps=bitcoind,seednode,arbdaemon,alicedaemon,bobdaemon
apiPassword=xyz
@ -90,12 +96,14 @@ bitcoinPath=/home/beta-tester/path-to-my-bitcoin-core/bin
```
Start up the test harness with without command options:
```
$ ./bisq-apitest
```
If you edit `apitest.properties`, do not forget to re-build the source. You do not need to do a full clean and
build, or run tests. The following build command should finish quickly.
If you edit `apitest.properties`, do not forget to re-build the source. You do not need to do a full clean and
build, or run tests. The following build command should finish quickly.
```
$ ./gradlew build :apitest:installDaoSetup -x test
```
@ -125,6 +133,7 @@ accounts for Bob and Alice, create an offer, take the offer, and complete a trad
follow in real time, so let the script complete before studying the output from start to finish.
The script takes four options:
```
-d=<direction> The trade direciton, BUY or SELL.
-c=<country> The two letter country code, US, FR, AT, RU, etc.
@ -136,16 +145,18 @@ The script takes four options:
### Examples
This simulation creates US / USD face-to-face payment accounts for Bob and Alice. Alice (always the trade maker)
This simulation creates US / USD face-to-face payment accounts for Bob and Alice. Alice (always the trade maker)
creates a SELL / USD offer for the amount of 0.1 BTC, at a price 2% below the current market price.
Bob (always the taker), will use his face-to-face account to take the offer, then the two sides will complete
the trade, checking their trade status along the way, and their BSQ / BTC balances when the trade is closed.
```
$ apitest/scripts/trade-simulation.sh -d sell -c us -m 2.00 -a 0.1
```
In the next example, Bob and Alice create Austrian face-to-face payment accounts. Alice creates a BUY/ EUR
offer to buy 0.125 BTC at a fixed price of 30,800 EUR.
In the next example, Bob and Alice create Austrian face-to-face payment accounts. Alice creates a BUY/ EUR
offer to buy 0.125 BTC at a fixed price of 30,800 EUR.
```
$ apitest/scripts/trade-simulation.sh -d buy -c at -f 30800 -a 0.125
```
@ -156,8 +167,8 @@ The test harness used by the simulation script described in the previous section
testing, and you can leave it running as you try the commands described below.
The API’s default server listening port is `9998`, and you do not need to specify a `–port=<port>` option in a
CLI command unless you change the server’s `–apiPort=<listening-port>`. In the test harness, Alice’s API port is
`9998`, Bob’s is `9999`. When you manually test the API using the test harness, be aware of the port numbers being
CLI command unless you change the server’s `–apiPort=<listening-port>`. In the test harness, Alice’s API port is
`9998`, Bob’s is `9999`. When you manually test the API using the test harness, be aware of the port numbers being
used in the CLI commands, so you know which server (Bob’s or Alice’s) the CLI is sending requests to.
### CLI Help
@ -165,44 +176,52 @@ used in the CLI commands, so you know which server (Bob’s or Alice’s) the CL
Useful information can be found using the CLI’s `--help` option.
For list of supported CLI commands:
```
$ ./bisq-cli --help (the –password option is not needed because there is no server request)
```
For help with a specific CLI command:
```
$ ./bisq-cli --password=xyz --help getbalance
OR
$ ./bisq-cli --password=xyz getbalance --help
```
The position of `--help` option does not matter. If a supported positional command option is present,
method help will be returned from the server. Also note an api password is required to get help from the server.
The position of `--help` option does not matter. If a supported positional command option is present,
method help will be returned from the server. Also note an api password is required to get help from the server.
### Working With Encrypted Wallet
There is no need to secure your regtest Bisq wallet with an encryption password when running these examples,
but you should encrypt your mainnet wallet as you probably already do when using the Bisq UI to transact in
real BTC. This section explains how to encrypt your Bisq wallet with the CLI, and unlock it before performing wallet
real BTC. This section explains how to encrypt your Bisq wallet with the CLI, and unlock it before performing wallet
related operations such as creating and taking offers, checking balances, and sending BSQ and BTC to external wallets.
Encrypt your wallet with a password:
```
$ ./bisq-cli --password=xyz setwalletpassword --wallet-password=<wallet-password>
```
Set a new password on your already encrypted wallet:
```
$ ./bisq-cli --password=xyz setwalletpassword --wallet-password=<wallet-password> \
--new-wallet-password=<new-wallet-password>
```
Unlock your password encrypted wallet for N seconds before performing sensitive wallet operations:
```
$ ./bisq-cli --password=xyz unlockwallet --wallet-password=<wallet-password> --timeout=<seconds>
```
You can override a `timeout` before it expires by calling `unlockwallet` again.
Lock your wallet before the `unlockwallet` timeout expires:
```
$ ./bisq-cli --password=xyz lockwallet
```
@ -210,17 +229,21 @@ $ ./bisq-cli --password=xyz lockwallet
### Checking Balances
Show full BSQ and BTC wallet balance information:
```
$ ./bisq-cli --password=xyz --port=9998 getbalance
```
Show full BSQ wallet balance information:
```
$ ./bisq-cli --password=xyz --port=9999 getbalance --currency-code=bsq
```
_Note: The example above is asking for Bob’s balance (using port `9999`), not Alice’s balance._
Show Bob’s full BTC wallet balance information:
```
$ ./bisq-cli --password=xyz --port=9999 getbalance --currency-code=btc
```
@ -230,23 +253,29 @@ $ ./bisq-cli --password=xyz --port=9999 getbalance --currency-code=btc
#### Receiving BTC
To receive BTC from an external wallet, find an unused BTC address (with a zero balance) to receive the BTC.
```
$ ./bisq-cli --password=xyz --port=9998 getfundingaddresses
```
You can check a block explorer for the status of a transaction, or you can check your Bisq BTC wallet address directly:
```
$ ./bisq-cli --password=xyz --port=9998 getaddressbalance --address=<btc-address>
```
#### Receiving BSQ
To receive BSQ from an external wallet, find an unused BSQ address:
```
$ ./bisq-cli --password=xyz --port=9998 getunusedbsqaddress
```
Give the public address to the sender. After the BSQ is sent, you can check block explorers for the status of
the transaction. There is no support (yet) to check the balance of an individual BSQ address in your wallet,
Give the public address to the sender. After the BSQ is sent, you can check block explorers for the status of
the transaction. There is no support (yet) to check the balance of an individual BSQ address in your wallet,
but you can check your BSQ wallet’s balance to determine if the new funds have arrived:
```
$ ./bisq-cli --password=xyz --port=9999 getbalance --currency-code=bsq
```
@ -256,21 +285,27 @@ $ ./bisq-cli --password=xyz --port=9999 getbalance --currency-code=bsq
Below are commands for sending BSQ and BTC to external wallets.
Send BSQ:
```
$ ./bisq-cli --password=xyz --port=9998 sendbsq --address=<bsq-address> --amount=<bsq-amount>
```
_Note: Sending BSQ to non-Bisq wallets is not supported and highly discouraged._
Send BSQ with a withdrawal transaction fee of 10 sats/byte:
```
$ ./bisq-cli --password=xyz --port=9998 sendbsq --address=<bsq-address> --amount=<bsq-amount> --tx-fee-rate=10
```
Send BTC:
```
$ ./bisq-cli --password=xyz --port=9998 sendbtc --address=<btc-address> --amount=<btc-amount>
```
Send BTC with a withdrawal transaction fee of 20 sats/byte:
```
$ ./bisq-cli --password=xyz --port=9998 sendbtc --address=<btc-address> --amount=<btc-amount> --tx-fee-rate=20
```
@ -278,27 +313,33 @@ $ ./bisq-cli --password=xyz --port=9998 sendbtc --address=<btc-address> --amount
### Withdrawal Transaction Fees
If you have traded using the Bisq UI, you are probably aware of the default network bitcoin withdrawal transaction
fee and custom withdrawal transaction fee user preference in the UI’s setting view. The API uses these same
fee and custom withdrawal transaction fee user preference in the UI’s setting view. The API uses these same
withdrawal transaction fee rates, and affords a third – as mentioned in the previous section -- withdrawal
transaction fee option in the `sendbsq` and `sendbtc` commands. The `sendbsq` and `sendbtc` commands'
transaction fee option in the `sendbsq` and `sendbtc` commands. The `sendbsq` and `sendbtc` commands'
`--tx-fee-rate=<sats/byte>` options override both the default network fee rate, and your custom transaction fee
setting for the execution of those commands.
#### Using Default Network Transaction Fee
If you have not set your custom withdrawal transaction fee setting, the default network transaction fee will be used
when withdrawing funds. In either case, you can check the current (default or custom) withdrawal transaction fee rate:
when withdrawing funds. In either case, you can check the current (default or custom) withdrawal transaction fee rate:
```
$ ./bisq-cli --password=xyz gettxfeerate
```
#### Setting Custom Transaction Fee Preference
To set a custom withdrawal transaction fee rate preference of 50 sats/byte:
```
$ ./bisq-cli --password=xyz settxfeerate --tx-fee-rate=50
```
#### Removing User’s Custom Transaction Fee Preference
To remove a custom withdrawal transaction fee rate preference, and revert to the network fee rate:
```
$ ./bisq-cli --password=xyz unsettxfeerate
```
@ -307,35 +348,35 @@ $ ./bisq-cli --password=xyz unsettxfeerate
Creating a fiat payment account using the API involves three steps:
1. Find the payment-method-id for the payment account type you wish to create. For example, if you want to
create a face-to-face type payment account, find the face-to-face payment-method-id (`F2F`):
```
$ ./bisq-cli --password=xyz --port=9998 getpaymentmethods
```
1. Find the payment-method-id for the payment account type you wish to create. For example, if you want to
create a face-to-face type payment account, find the face-to-face payment-method-id (`F2F`):
```
$ ./bisq-cli --password=xyz --port=9998 getpaymentmethods
```
2. Use the payment-method-id `F2F` found in the `getpaymentmethods` command output to create a blank payment account
form:
```
$ ./bisq-cli --password=xyz --port=9998 getpaymentacctform --payment-method-id=F2F
```
This `getpaymentacctform` command generates a json file (form) for creating an `F2F` payment account,
prints the file’s contents, and tells you where it is. In this example, the sever created an `F2F` account
form named `f2f_1612381824625.json`.
2. Use the payment-method-id `F2F` found in the `getpaymentmethods` command output to create a blank payment account
form:
```
$ ./bisq-cli --password=xyz --port=9998 getpaymentacctform --payment-method-id=F2F
```
This `getpaymentacctform` command generates a json file (form) for creating an `F2F` payment account,
prints the file’s contents, and tells you where it is. In this example, the sever created an `F2F` account
form named `f2f_1612381824625.json`.
3. Manually edit the json file, and use its path in the `createpaymentacct` command.
```
$ ./bisq-cli --password=xyz --port=9998 createpaymentacct \
--payment-account-form=f2f_1612381824625.json
```
_Note: You can rename the file before passing it to the `createpaymentacct` command._
3. Manually edit the json file, and use its path in the `createpaymentacct` command.
```
$ ./bisq-cli --password=xyz --port=9998 createpaymentacct \
--payment-account-form=f2f_1612381824625.json
```
_Note: You can rename the file before passing it to the `createpaymentacct` command._
The server will create and save the new payment account from details defined in the json file then
return the new payment account to the CLI. The CLI will display the account ID with other details
in the console, but if you ever need to find a payment account ID, use the `getpaymentaccts` command:
```
$ ./bisq-cli --password=xyz --port=9998 getpaymentaccts
```
The server will create and save the new payment account from details defined in the json file then
return the new payment account to the CLI. The CLI will display the account ID with other details
in the console, but if you ever need to find a payment account ID, use the `getpaymentaccts` command:
```
$ ./bisq-cli --password=xyz --port=9998 getpaymentaccts
```
### Creating Test Altcoin Payment Accounts
@ -344,15 +385,18 @@ Unlike more complex fiat payment account setups, the `createcryptopaymentacct` c
#### BSQ Altcoin Payment Accounts
A default BSQ Swap Altcoin payment account was created for you when the BSQ Swap protocol was introduced, and you do
not need to create BSQ Altcoin payment accounts to execute BSQ Swaps. But if you do want to trade BSQ using the
not need to create BSQ Altcoin payment accounts to execute BSQ Swaps. But if you do want to trade BSQ using the
version 1 trade protocol, you will need to create a BSQ Altcoin payment accounts as show below.
```
$ ./bisq-cli --password=xyz --port=9998 createcryptopaymentacct --account-name="My BSQ Account" \
--currency-code=BSQ \
--address=Bn3PCQgRwhkrGnaMp1RYwt9tFwL51YELqne \
--trade-instant=false
```
To create a BSQ Altcoin _Instant_ payment account, use the `--trade-instant=true` parameter:
```
$ ./bisq-cli --password=xyz --port=9998 createcryptopaymentacct --account-name="My Instant BSQ Account" \
--currency-code=BSQ \
@ -367,17 +411,18 @@ example above._
To create an XMR Altcoin payment account associated with example XMR address
`44G4jWmSvTEfifSUZzTDnJVLPvYATmq9XhhtDqUof1BGCLceG82EQsVYG9Q9GN4bJcjbAJEc1JD1m5G7iK4UPZqACubV4Mq`:
```
$ ./bisq-cli --password=xyz --port=9999 createcryptopaymentacct --account-name=XMR-Account \
--currency-code=XMR
--address=44G4jWmSvTEfifSUZzTDnJVLPvYATmq9XhhtDqUof1BGCLceG82EQsVYG9Q9GN4bJcjbAJEc1JD1m5G7iK4UPZqACubV4Mq
```
### Creating Offers
The createoffer command is the API's most complex command (so far), but CLI posix-style options are self-explanatory,
and CLI `createoffer` command help gives you specific information about each option.
```
$ ./bisq-cli --password=xyz --port=9998 createoffer --help
```
@ -385,9 +430,10 @@ $ ./bisq-cli --password=xyz --port=9998 createoffer --help
#### Examples
The `trade-simulation.sh` script described above is an easy way to figure out how to use this command.
In a previous example, Alice created a BUY/ EUR offer to buy 0.125 BTC at a fixed price of 30,800 EUR,
and pay the Bisq maker fee in BSQ. Alice had already created an EUR face-to-face payment account with id
In a previous example, Alice created a BUY/ EUR offer to buy 0.125 BTC at a fixed price of 30,800 EUR,
and pay the Bisq maker fee in BSQ. Alice had already created an EUR face-to-face payment account with id
`f3c1ec8b-9761-458d-b13d-9039c6892413`, and used this `createoffer` command:
```
$ ./bisq-cli --password=xyz --port=9998 createoffer \
--payment-account-id=f3c1ec8b-9761-458d-b13d-9039c6892413 \
@ -401,6 +447,7 @@ $ ./bisq-cli --password=xyz --port=9998 createoffer \
If Alice was in Japan, and wanted to create an offer to sell 0.125 BTC at 0.5% above the current market JPY price,
putting up a 15% security deposit, the `createoffer` command to do that would be:
```
$ ./bisq-cli --password=xyz --port=9998 createoffer \
--payment-account-id=f3c1ec8b-9761-458d-b13d-9039c6892413 \
@ -413,12 +460,14 @@ $ ./bisq-cli --password=xyz --port=9998 createoffer \
```
The `trade-simulation.sh` script options that would generate the previous `createoffer` example is:
```
$ apitest/scripts/trade-simulation.sh -d sell -c jp -m 0.5 -a 0.125
```
The `createoffer` command can also be used to create BSQ swap offers, where trade execution is performed immediately
after a BSQ swap offer is taken. To swap 0.5 BTC for BSQ at a price of 0.00005 BTC for 1 BSQ:
after a BSQ swap offer is taken. To swap 0.5 BTC for BSQ at a price of 0.00005 BTC for 1 BSQ:
```
$ ./bisq-cli --password=xyz --port=9998 createoffer \
--swap=true \
@ -429,6 +478,7 @@ $ ./bisq-cli --password=xyz --port=9998 createoffer \
```
The `bsqswap-simulation.sh` script options that would generate the previous `createoffer` example is:
```
$ apitest/scripts/bsqswap-simulation.sh -d buy -a 0.5 -f 0.00005
```
@ -438,11 +488,13 @@ $ apitest/scripts/bsqswap-simulation.sh -d buy -a 0.5 -f 0.00005
There are different commands to browse available offers you can take, and offers you created.
To see all offers you created with a specific direction (BUY|SELL) and currency (CAD|EUR|USD|...):
```
$ ./bisq-cli --password=xyz --port=9998 getmyoffers --direction=<BUY|SELL> --currency-code=<currency-code>
```
To look at a specific offer you created:
```
$ ./bisq-cli --password=xyz --port=9998 getoffer --offer-id=<offer-id>
```
@ -450,11 +502,13 @@ $ ./bisq-cli --password=xyz --port=9998 getoffer --offer-id=<offer-id>
### Browsing Available Offers
To see all available offers you can take, with a specific direction (BUY|SELL) and currency (CAD|EUR|USD|...):
```
$ ./bisq-cli --password=xyz --port=9998 getoffers --direction=<BUY|SELL> --currency-code=<currency-code>
```
To look at a specific, available offer you could take:
```
$ ./bisq-cli --password=xyz --port=9998 getoffer --offer-id=<offer-id>
```
@ -462,9 +516,11 @@ $ ./bisq-cli --password=xyz --port=9998 getoffer --offer-id=<offer-id>
### Removing An Offer
To cancel one of your offers:
```
$ ./bisq-cli --password=xyz --port=9998 canceloffer --offer-id=<offer-id>
```
The offer will be removed from other Bisq users' offer views, and paid transaction fees will be forfeited.
### Editing an Existing Offer
@ -490,6 +546,7 @@ The subsections below contain examples related to specific use cases.
Existing offers you create can be disabled (removed from offer book) and re-enabled (re-published to offer book).
To disable an offer:
```
./bisq-cli --password=xyz --port=9998 editoffer \
--offer-id=83e8b2e2-51b6-4f39-a748-3ebd29c22aea \
@ -497,6 +554,7 @@ To disable an offer:
```
To enable an offer:
```
./bisq-cli --password=xyz --port=9998 editoffer \
--offer-id=83e8b2e2-51b6-4f39-a748-3ebd29c22aea \
@ -504,11 +562,14 @@ To enable an offer:
```
#### Change Offer Pricing Model
The `editoffer` command can be used to change an existing market price margin based offer to a fixed price offer,
and vice-versa.
##### Change Market Price Margin Based to Fixed Price Offer
Suppose you used `createoffer` to create a market price margin based offer as follows:
```
$ ./bisq-cli --password=xyz --port=9998 createoffer \
--payment-account-id=f3c1ec8b-9761-458d-b13d-9039c6892413 \
@ -519,7 +580,9 @@ $ ./bisq-cli --password=xyz --port=9998 createoffer \
--security-deposit=15.0 \
--fee-currency=BSQ
```
To change the market price margin based offer to a fixed price offer:
```
./bisq-cli --password=xyz --port=9998 editoffer \
--offer-id=83e8b2e2-51b6-4f39-a748-3ebd29c22aea \
@ -527,7 +590,9 @@ To change the market price margin based offer to a fixed price offer:
```
##### Change Fixed Price Offer to Market Price Margin Based Offer
Suppose you used `createoffer` to create a fixed price offer as follows:
```
$ ./bisq-cli --password=xyz --port=9998 createoffer \
--payment-account-id=f3c1ec8b-9761-458d-b13d-9039c6892413 \
@ -538,15 +603,18 @@ $ ./bisq-cli --password=xyz --port=9998 createoffer \
--security-deposit=15.0 \
--fee-currency=BSQ
```
To change the fixed price offer to a market price margin based offer:
```
./bisq-cli --password=xyz --port=9998 editoffer \
--offer-id=83e8b2e2-51b6-4f39-a748-3ebd29c22aea \
--market-price-margin=0.5
```
Alternatively, you can also set a trigger price on the re-published, market price margin based offer.
A trigger price on a SELL offer causes the offer to be automatically disabled when the market price
falls below the trigger price. In the `editoffer` example below, the SELL offer will be disabled when
falls below the trigger price. In the `editoffer` example below, the SELL offer will be disabled when
the JPY market price falls below 3960000.0000.
```
@ -555,6 +623,7 @@ the JPY market price falls below 3960000.0000.
--market-price-margin=0.5 \
--trigger-price=3960000.0000
```
On a BUY offer, a trigger price causes the BUY offer to be automatically disabled when the market price
rises above the trigger price.
@ -562,7 +631,9 @@ _Note: Disabled offers never automatically re-enable; they can only be manually
`editoffer --offer-id=<id> --enable=true`._
#### Remove Trigger Price
To remove a trigger price on a market price margin based offer, set the trigger price to 0:
```
./bisq-cli --password=xyz --port=9998 editoffer \
--offer-id=83e8b2e2-51b6-4f39-a748-3ebd29c22aea \
@ -570,10 +641,12 @@ To remove a trigger price on a market price margin based offer, set the trigger
```
#### Change Disabled Offer's Pricing Model and Enable It
You can use `editoffer` to simultaneously change an offer's price details and disable or re-enable it.
Suppose you have a disabled, fixed price offer, and want to change it to a market price margin based offer, set
a trigger price, and re-enable it:
```
./bisq-cli --password=xyz --port=9998 editoffer \
--offer-id=83e8b2e2-51b6-4f39-a748-3ebd29c22aea \
@ -586,13 +659,15 @@ a trigger price, and re-enable it:
Taking an available offer involves two CLI commands: `getoffers` and `takeoffer`.
A CLI user browses available offers with the getoffers command. For example, the user browses SELL / EUR offers:
A CLI user browses available offers with the getoffers command. For example, the user browses SELL / EUR offers:
```
$ ./bisq-cli --password=xyz --port=9998 getoffers --direction=SELL --currency-code=EUR
```
Then takes one of the available offers with an EUR payment account ( id `fe20cdbd-22be-4b8a-a4b6-d2608ff09d6e`)
with the `takeoffer` command:
```
$ ./bisq-cli --password=xyz --port=9998 takeoffer \
--offer-id=83e8b2e2-51b6-4f39-a748-3ebd29c22aea \
@ -600,34 +675,38 @@ $ ./bisq-cli --password=xyz --port=9998 takeoffer \
--amount=0.125
--fee-currency=btc
```
Depending on the offer type, the taken offer will be used to (1) create a trade contract, or (2) execute a BSQ swap.
The value passed with the optional `--amount` parameter must be between the offer's min-amount and amount values.
If the `--amount` parameter is omitted, the intended trade amount will equal the taken offer's amount.
The next section describes how to use the API to execute a trade. The following <b>Completing a BSQ Swap Trade</b>
The next section describes how to use the API to execute a trade. The following <b>Completing a BSQ Swap Trade</b>
section explains how to use the `takeoffer` command to complete a BSQ swap.
### Completing Trade Protocol
The first step in the Bisq trade protocol is completed when a `takeoffer` command successfully creates a new trade from
the taken offer. After the Bisq nodes prepare the trade, its status can be viewed with the `gettrade` command:
the taken offer. After the Bisq nodes prepare the trade, its status can be viewed with the `gettrade` command:
```
$ ./bisq-cli --password=xyz --port=9998 gettrade --trade-id=<trade-id>
```
The `trade-id` is the same as the taken `offer-id`, but when viewing and interacting with trades, it is referred to as
the `trade-id`. Note that the `trade-id` argument is a full `offer-id`, not a truncated `short-id` as displayed in the
the `trade-id`. Note that the `trade-id` argument is a full `offer-id`, not a truncated `short-id` as displayed in the
Bisq UI.
You can also view the entire trade contract in `json` format by using the `gettrade` command's `--show-contract=true`
option:
```
$ ./bisq-cli --password=xyz --port=9998 gettrade --trade-id=<trade-id> --show-contract=true
```
The `gettrade` command’s output shows the state of the trade from initial preparation through completion and closure.
Output columns include:
```
Deposit Published YES if the taker fee tx deposit has been broadcast to the network.
Deposit Confirmed YES if the taker fee tx deposit has been confirmed by the network.
@ -636,16 +715,18 @@ Fiat Received YES if the seller has sent a “payment received”
Payout Published YES if the seller’s BTC payout tx has been broadcast to the network.
Withdrawn YES if the buyer’s BTC proceeds have been sent to an external wallet.
```
Trade status information informs both sides of a trade which steps have been completed, and which step to perform next.
It should be frequently checked by both sides before proceeding to the next step of the protocol.
_Note: There is some delay after a new trade is created due to the time it takes for a taker’s trade deposit fee
transaction to be published and confirmed on the bitcoin network. Both sides of the trade can check the `gettrade`
transaction to be published and confirmed on the bitcoin network. Both sides of the trade can check the `gettrade`
output's `Deposit Published` and `Deposit Confirmed` columns to find out when this early phase of the trade protocol is
complete._
Once the taker fee transaction has been confirmed, payment can be sent, payment receipt confirmed, and the trade
protocol completed. There are three CLI commands that must be performed in coordinated order by each side of the trade:
protocol completed. There are three CLI commands that must be performed in coordinated order by each side of the trade:
```
confirmpaymentstarted Buyer sends seller a message confirming payment has been sent.
confirmpaymentreceived Seller sends buyer a message confirming payment has been received.
@ -653,11 +734,13 @@ closetrade Set trade state to CLOSED, and keep trade proceeds i
OR
withdrawfunds Set trade state to CLOSED, and send trade proceeds to an external wallet.
```
The last two mutually exclusive commands (`closetrade` or `withdrawfunds`) may seem unnecessary, but they are critical
because they tell the Bisq node to set a completed trade’s state `CLOSED`. Please close out your trades with one
because they tell the Bisq node to set a completed trade’s state `CLOSED`. Please close out your trades with one
or the other command.
Each of the CLI commands above takes one argument: `--trade-id=<trade-id>`:
```
$ ./bisq-cli --password=xyz --port=9998 confirmpaymentstarted --trade-id=<trade-id>
$ ./bisq-cli --password=xyz --port=9999 confirmpaymentreceived --trade-id=<trade-id>
@ -668,7 +751,8 @@ $ ./bisq-cli --password=xyz --port=9999 withdrawfunds --trade-id=<trade-id> --ad
### Completing a BSQ Swap Trade
The `takeoffer` command will immediately perform the BSQ swap, assuming both sides' wallets have sufficient BTC and
BSQ to cover the trade amount, and maker or taker fee. It takes one argument: `--offer-id=<offer-id>`:
BSQ to cover the trade amount, and maker or taker fee. It takes one argument: `--offer-id=<offer-id>`:
```
$ ./bisq-cli --password=xyz --port=9998 takeoffer --offer-id=Xge8b2e2-51b6-3TOOB-z748-3ebd29c2kj99
```
@ -678,7 +762,7 @@ $ ./bisq-cli --password=xyz --port=9998 takeoffer --offer-id=Xge8b2e2-51b6-3TOOB
The test harness should cleanly shut down all the background apps in proper order after entering ^C.
Once shutdown, all Bisq and bitcoin-core data files are left in the state they were in at shutdown time,
so they and logs can be examined after a test run. All datafiles will be refreshed the next time the test harness
so they and logs can be examined after a test run. All datafiles will be refreshed the next time the test harness
is started, so if you want to save datafiles and logs from a test run, copy them to a safe place first.
They can be found in `apitest/build/resources/main`.