WIP Produce the simplest-possible getting started guide for the Bisq HTTP API

http-api-monitor-offers.adoc

@@ -0,0 +1,327 @@
+= Monitoring Bisq offers with Http API
+
+This guide walks you through the process of creating a bot that monitors available offers and sends email notifications.
+
+== What you'll build
+
+You'll build a NodeJS-based script that connects to Bisq over an HTTP API to get offers and market prices and sends email notification whenever "interesting" offers are detected.
+
+== What you’ll need
+
+* About 15 minutes
+* A favorite text editor or IDE
+* NodeJS 6+
+* Docker (to run from an image) or Git and Maven (to build from source)
+* A GMail account
+
+== Run the API
+
+There are two alternative ways you can run an instance of the Bisq HTTP API, either from a Docker image or from source.
+
+=== Run the API using Docker
+
+The easiest way to run the API in headless mode is by using a Docker image:
+
+    docker run -it --rm -p 8080:8080 -e BISQ_API_HOST=0.0.0.0 bisq/api
+
+=== Run the API from source
+
+For more hard-core developers that want to run from source:
+
+    git clone https://github.com/mrosseel/bisq-api
+    cd bisq-api
+    mvn compile exec:java \
+        -Dexec.mainClass="io.bisq.api.app.ApiMain" \
+        -Dexec.args="--appName=bisqmon"
+
+=== Verify the API is running
+
+In both cases the API should be running on port 8080. You can verify that by executing:
+
+    curl http://localhost:8080/api/v1/version
+
+You should receive a response like the following:
+
+[source,json]
+----
+{
+    "application": "0.6.7",
+    "network": 1,
+    "p2PMessage": 10,
+    "localDB": 1,
+    "tradeProtocol": 1
+}
+----
+
+[NOTE]
+Complete interactive API documentation is available at http://localhost:8080/swagger.
+
+== List available offers
+
+Open offers are available at http://localhost:8080/api/v1/offers.
+
+The response should look like this:
+
+[source,json]
+----
+{
+    "offers": [OfferDetail],
+    "total": integer
+}
+----
+
+Where `offers` is an array with individual offers and `total` is number of all offers. The model for each individual `OfferDetail` is defined as follows:
+
+[source,json]
+----
+{
+    acceptedBankIds	[string]
+    acceptedCountryCodes	[string]
+    amount	integer($int64)
+    arbitratorNodeAddresses	[string]
+    bankId	string
+    baseCurrencyCode	string
+    blockHeightAtOfferCreation	integer($int64)
+    buyerSecurityDeposit	integer($int64)
+    counterCurrencyCode	string
+    countryCode	string
+    currencyCode	string
+    date	string($date-time)
+    direction	string Enum: [ BUY, SELL ]
+    hashOfChallenge	string
+    id	string
+    isCurrencyForMakerFeeBtc	boolean
+    isPrivateOffer	boolean
+    lowerClosePrice	integer($int64)
+    makerFee	integer($int64)
+    makerPaymentAccountId	string
+    marketPriceMargin	number($double)
+    maxTradeLimit	integer($int64)
+    maxTradePeriod	integer($int64)
+    minAmount	integer($int64)
+    offerFeePaymentTxId	string
+    ownerNodeAddress	string
+    paymentMethodId	string
+    price	integer($int64)
+    protocolVersion	integer($int32)
+    sellerSecurityDeposit	integer($int64)
+    state	string Enum: [ UNKNOWN, OFFER_FEE_PAID, AVAILABLE, NOT_AVAILABLE, REMOVED, MAKER_OFFLINE ]
+    txFee	integer($int64)
+    upperClosePrice	integer($int64)
+    useAutoClose	boolean
+    useMarketBasedPrice	boolean
+    useReOpenAfterAutoClose	boolean
+    versionNr	string
+}
+----
+
+Now let's assume that we want to buy bitcoin, and let's define "interesting" offers as those that:
+
+ . sell bitcoin at a discount 1% or more under the current market price, and
+ . accept payment in Euros to a Polish SEPA account
+
+First we need to filter those offers using following static criteria:
+
+[source,json]
+----
+{
+    baseCurrencyCode: 'BTC',
+    counterCurrencyCode: 'EUR',
+    direction: 'SELL',
+    paymentMethodId: 'SEPA'
+}
+----
+
+Next we need to filter those offers by price. There are two types of offers: _market-based price offers_ and _fixed price offers_. They are distinguished by the `useMarketBasedPrice` attribute. In case of market-based price offers the filtering criteria is easy: the `marketPriceMargin` value must be above 0.1. In case of fixed price offers we have to fetch market price of BTC in EUR, then calculate whether the price is 1% or less, and finally we must filter offers which have a price _less_ than that calculated price.
+
+=== Get the market price
+
+In order to get the market price of BTC in EUR, execute the following query:
+
+    curl http://localhost:8080/api/v1/currencies/prices?currencyCodes=EUR
+
+You should receive a response like the following:
+
+[source,json]
+----
+{
+  "prices": {
+    "EUR": 7035.62
+  }
+}
+----
+
+== The JavaScript part
+
+Let's install some dependencies:
+
+    npm install lodash http-as-promised nodemailer
+
+In general our script will look like this:
+
+[source,javascript]
+----
+Promise.all([getOffers(), getMarketPrice()])
+        .then(filterOffers)
+        .then(notify)
+        .catch(e => console.error(e));
+----
+
+So first 2 things to do (concurrently and asynchronously) is to fetch offers and market price of BTC from our API. Then we need to filter those offers and finally send notification.
+
+Getting offers is a simple call that returns promise with array of offers:
+
+[source,javascript]
+----
+function getOffers() {
+    return $http.get('http://localhost:8080/api/v1/offers', {resolve: 'body', json: true})
+        .then(body => body.offers);
+}
+----
+
+Similarly with `getMarketPrice`:
+
+[source,javascript]
+----
+function getMarketPrice() {
+    return $http.get('http://localhost:8080/api/v1/currencies/prices?currencyCodes=EUR', {resolve: 'body', json: true})
+            .then(body => _.get(body, 'prices.EUR'))
+}
+----
+
+Now our `filterOffers` function is ready to receive an array of results from the two functions described above:
+
+[source,javascript]
+----
+function filterOffers([offers, marketPrice]) {
+    return _(offers)
+            .filter({
+                baseCurrencyCode: 'BTC',
+                counterCurrencyCode: 'EUR',
+                direction: 'SELL',
+                paymentMethodId: 'SEPA'
+            })
+            .filter(i => _.includes(i.acceptedCountryCodes, 'PL'))
+            .filter(getPriceFilter(marketPrice))
+            .map(i => ({amount: i.amount, margin: i.useMarketBasedPrice ? i.marketPriceMargin : marketPrice / i.price}))
+            .value();
+}
+----
+
+This function filters offers to match our criteria. It returns matching offers and maps them to a bit simpler structure that contains as little data as needed for `notify` function. We are using `lodash` library to simplify the filtering.
+
+The `getPriceFilter` function creates the actual filter function and looks like this:
+
+[source,javascript]
+----
+function getPriceFilter(marketPrice) {
+    const maxPrice = marketPrice * (1 - threshold) * 10000;
+    return offer => {
+        if (offer.useMarketBasedPrice)
+            return offer.marketPriceMargin >= threshold;
+        return offer.price < maxPrice;
+    }
+}
+----
+
+We are multiplying `marketPrice` by `10000` because that is the format in which the API returns the price.
+
+Here is a full script. You must substitute `EMAIL_ACCOUNT_USERNAME`, `EMAIL_ACCOUNT_PASSWORD`, `EMAIL_FROM_ADDRESS` and `EMAIL_TO_ADDRESS`
+with appropriate values.
+
+[source,javascript]
+----
+const _ = require('lodash');
+const $http = require('http-as-promised');
+const nodemailer = require('nodemailer');
+
+const threshold = 0.1;
+
+const EMAIL_ACCOUNT_USERNAME = 'email@gmail.com';
+const EMAIL_ACCOUNT_PASSWORD = 'secret';
+const EMAIL_FROM_ADDRESS = 'from@gmail.com';
+const EMAIL_TO_ADDRESS = 'to@gmail.com';
+
+function getPriceFilter(marketPrice) {
+    const maxPrice = marketPrice * (1 - threshold) * 10000;
+    return offer => {
+        if (offer.useMarketBasedPrice)
+            return offer.marketPriceMargin >= threshold;
+        return offer.price < maxPrice;
+    }
+}
+
+function getMarketPrice() {
+    return $http.get('http://localhost:8080/api/v1/currencies/prices?currencyCodes=EUR', {resolve: 'body', json: true})
+            .then(body => _.get(body, 'prices.EUR'))
+}
+
+function getOffers() {
+    return $http.get('http://localhost:8080/api/v1/offers', {resolve: 'body', json: true}).then(body => body.offers);
+}
+
+function notify(offers) {
+    if (!offers.length) {
+        console.log('No interesting offers found');
+        return;
+    }
+
+    const transporter = nodemailer.createTransport({
+        service: 'gmail',
+        auth: {
+            user: EMAIL_ACCOUNT_USERNAME,
+            pass: EMAIL_ACCOUNT_PASSWORD
+        }
+    });
+
+    const text = _.map(offers, offer => `${offer.amount / 100000000} BTC (-${_.round(offer.margin * 100, 2)}%)`).join('\n');
+
+    const mailOptions = {
+        from: EMAIL_FROM_ADDRESS,
+        to: EMAIL_TO_ADDRESS,
+        subject: `${offers.length} interesting BTC offers from Bisq`,
+        text: text
+    };
+
+    transporter.sendMail(mailOptions, function (error) {
+        if (error) {
+            console.log(error);
+        } else {
+            console.log(`Notification about ${offers.length} offers sent`);
+        }
+    });
+}
+
+function filterOffers([offers, marketPrice]) {
+    return _(offers)
+            .filter({
+                baseCurrencyCode: 'BTC',
+                counterCurrencyCode: 'EUR',
+                direction: 'SELL',
+                paymentMethodId: 'SEPA'
+            })
+            .filter(i => _.includes(i.acceptedCountryCodes, 'PL'))
+            .filter(getPriceFilter(marketPrice))
+            .map(i => _.pick(i, 'baseCurrencyCode', 'counterCurrencyCode', 'direction', 'paymentMethodId', 'id', 'useMarketBasedPrice', 'price', 'marketPriceMargin', 'amount', 'minAmont'))
+            .map(i => ({amount: i.amount, margin: i.useMarketBasedPrice ? i.marketPriceMargin : marketPrice / i.price}))
+            .value();
+}
+
+Promise.all([getOffers(), getMarketPrice()])
+        .then(filterOffers)
+        .then(notify)
+        .catch(e => console.error(e));
+----
+
+If there are any matching offers you should receive an mail like this:
+
+    5 interesting BTC offers from Bisq
+    0.0625 BTC (-2%)
+    0.01 BTC (-2%)
+    0.01 BTC (-5%)
+    0.033 BTC (-3%)
+    0.02 BTC (-1.5%)
+    0.25 BTC (-6%)
+
+[NOTE]
+If you would like to use something else that gmail then you will need a bit different mail transport configuration. For reference look at https://nodemailer.com/smtp/.

index.adoc

@@ -3,6 +3,7 @@
  * *_User Docs_*
  ** <<intro#, Introduction>> — What Bisq is, why it exists and how it works
  ** <<getting-started#, Getting Started>> — Go from zero to trading in 15 minutes
+ ** <<http-api#, Getting Started - HTTP API>> — How to access Bisq programatically
 
  * *_Contributor Docs_*
  ** <<contributor-checklist#, New contributor checklist>>