Skip to content

bisq-network/bisq

Repository files navigation

Build Status

Bisq API

Based on proposal: Bisq-IP 1

This repository is an add-on to the bisq-exchange.

The goal is to add Trading API functionality to Bisq, see this video to see it in action (pretty outdated).

Prerequisites

  • Java 8

Bisq configuration

Starting this api is like starting a normal Bisq client: configurations are read and written to the same location on your disk.

This implies that if you already have a fully configured Bisq application, the api will use those pre-existing configurations

Note: running 2 Bisq instances on one computer (e.g one with API, one without) is not advisable. By default they both write to the same configuration location. Changing the appname can fix this issue.

Compiling the API

Getting started: headless

The following command will start a headless Bisq instance on Bitcoin mainnet (meaning you can lose real BTC):

./gradlew run

Developing

When testing it is advisable to run Bisq in REGTEST mode. See below on how to pass Bisq arguments to enable REGTEST mode. All regular Bisq arguments can be used.

./gradlew run --args ' --baseCurrencyNetwork=BTC_REGTEST --bitcoinRegtestHost localhost --nodePort 2003 --seedNodes=localhost:2225 --useLocalhost true --appName Bisq-Regtest-Bob'

Exploring the HTTP API

locally generated swagger docs are at: http://localhost:8080/swagger

publically generated swagger docs are at: https://mrosseel.github.io/bisq-api-examples/

Locally generated swagger.json can be found at: http://localhost:8080/swagger.json

the admin interface can be found at: http://localhost:8080/admin

Overriding http port and host

Set the environment variable BISQ_API_PORT to your desired port. Set the environment variable BISQ_API_HOST to your desired host. You might also pass program args: apiPort and apiHost.

#TODO this is invalid instruction. We want to restore it once those params get to BisqEnvironment in core mvn compile exec:java
-Dexec.mainClass="network.bisq.api.app.BisqApiWithUIMain"
-Dexec.args="--apiPort=8000 --apiHost=localhost"

Docker for production

Since there is no security implemented yet, please be cautious. We do not consider this API to be production ready yet. But if you want to give it a try using docker, here is the image with headless version:

docker run -it -p 8080:8080 -p 9999:9999 bisq/api

or if you want to keep Bisq data outside of docker:

docker run -it -v ~/.local/share/Bisq:/root/.local/share/Bisq -p 8080:8080 -p 9999:9999 bisq/api

If you want to build your own production image instead of pulling it from docker hub:

docker build . -f docker/prod/Dockerfile -t bisq/api

Docker for developers

Since maven and gradle dependencies are being fetched after container is started you can seed 'm2' and 'gradle' volumes used for caching local maven repo:

sh create-docker-volumes.sh

Build bisq-api image:

docker-compose build

Now depending on what scenario you want to run execute one of following commands:

docker-compose up alice
docker-compose up alice bob
docker-compose up alice bob arbitrator

Api ports:

  • localhost:8080 Alice
  • localhost:8081 Bob
  • localhost:8082 Arbitrator

Integration tests

Integration tests are being run using Arquillian Cube. Arquillian will create and start containers for alice, bob, arbitrator, seednode and bitcoind on the fly during tests. You have to build bisq-api image before running integration tests.

Run integration tests:

docker-compose build #just make sure our images are up to date
./gradlew test

Api naming guidelines:

  • resource names should be in plural
  • use hyphen-case for multi word resource names (camelCase for everything else: payload properties or query params)
  • if you need to return array, use {results,total} pattern in case pagination is required in future
  • use GET / to search
  • use POST / to create
  • use PUT /{id} to update by id
  • use DELETE /{id} to remove by id
  • use POST /{id}/{action} to perform some action on specific resource

TODO

  • produce jar with all dependencies for easier deployment