BX-bot

What is BX-bot?

<img src="./docs/bxbot-cropped.png" align="right" width="25%" />

BX-bot (Bex) is a simple Bitcoin trading bot written in Java for trading on cryptocurrency exchanges.

The project contains the basic infrastructure to trade on a cryptocurrency exchange... except for the trading strategies - you'll need to write those yourself! A simple ExampleScalpingStrategy is included to get you started with the Trading API - see Ta4j for more ideas.

Exchange Adapters for using Bitstamp, Bitfinex, Kraken, and Gemini are included. Feel free to improve these or contribute new adapters to the project; that would be shiny!

A TryModeExchangeAdapter is configured by default to delegate public API calls to Bitstamp, but it simulates the private API (order management) calls; it's good for testing your initial setup and paper trading without actually sending orders to the exchange.

The Trading API provides support for limit orders traded at the spot price. If you're looking for something more sophisticated with a much richer Trading API, take a look at XChange.

Warning: Trading cryptocurrency carries significant financial risk; you could lose money. This software is provided 'as is' and released under the MIT license.

Architecture

• Trading Engine - the execution unit. It provides a framework for integrating Exchange Adapters and executing Trading Strategies.
• Exchange Adapters - the data stream unit. They provide access to a given exchange.
• Trading Strategies - the decision or strategy unit. This is where the trading decisions happen.
• Trading API - Trading Strategies use this API to make trades. Exchange Adapters implement this to provide access to a given exchange.
• Strategy API - Trading Strategies implement this so the Trading Engine can execute them.

Trading Strategies and Exchange Adapters are injected by the Trading Engine on startup. The bot uses a simple YAML backed dependency injection framework to achieve this; the long term goal is to convert it into a fully configurable Spring Boot app.

The bot was designed to fail hard and fast if any unexpected errors occur in the Exchange Adapters or Trading Strategies: it will log the error, send an email alert (if configured), and then shut down.

Installation Guide

The bot runs on Linux, macOS, and Windows.

BX-bot is supported on the current JDK 21 LTS. You'll need the JDK (e.g. OpenJDK 21 or Oracle JDK 21) installed on the machine you are going to use to build and run the bot. Be mindful of Oracle's recent licensing changes and how you intend to use the bot.

You can use Gradle or Maven to build the bot. The instructions below are for Linux/macOS, but equivalent Windows scripts are included.

Download the latest Release and unzip the bot.

Maven

1. If you plan on using your own Trading Strategies/Exchange Adapters packaged in separate jar files, you'll need to add the dependency in the bxbot-app/pom.xml - see the commented out dependency examples inside it.
2. From the project root, run ./mvnw clean package to produce the distribution artifacts bxbot-app-<version>-dist.tar.gz and bxbot-app-<version>-dist.zip in the ./bxbot-app/target folder.
3. Copy either the bxbot-app-<version>-dist.tar.gz or the bxbot-app-<version>-dist.zip onto the machine you want to run the bot and unzip it someplace.
4. Configure the bot as required - see the main Configuration section. The bot's default configuration uses the ExampleScalpingStrategy, but you'll probably want to code your own! The TryModeExchangeAdapter is configured out of the box to simulate trading with Bitstamp.
5. Usage: ./bxbot.sh [start|stop|status]

Gradle

1. If you plan on using your own Trading Strategies/Exchange Adapters packaged in separate jar files, you'll need to add the dependency in the bxbot-app/build.gradle - see the commented out dependency examples inside it.
2. From the project root, run ./gradlew clean build to build the bot.
3. Then run ./gradlew buildTarGzipDist or ./gradlew buildZipDist to build the distribution artifact: either bxbot-app-<version>.tar.gz or bxbot-app-<version>.zip respectively. It will be placed in the ./build/distributions folder.
4. Copy the artifact onto the machine you want to run the bot and unzip it someplace.
5. Configure the bot as described in step 4 of the previous Maven section.
6. Usage: ./bxbot.sh [start|stop|status]

Docker

If you want to just play around with the ExampleScalpingStrategy and evaluate the bot, Docker is the way to go.

1. Install Docker on the machine you want to run the bot.
2. Fetch the BX-bot image from Docker Hub: docker pull gazbert/bxbot:2.2.1
3. Run the Docker container: docker container run --publish=8080:8080 --name bxbot-2.2.1 -it gazbert/bxbot:2.2.1 bash
4. Change into the bot's directory: cd bxbot*
5. Configure the bot as described in step 4 of the previous Maven section.
6. Usage: ./bxbot.sh [start|stop|status]
7. You can detach from the container and leave the bot running using the CTRL-p CTRL-q key sequence.
8. To re-attach to the Docker container, run docker container ls to get the CONTAINER ID. Then run: docker container attach <CONTAINER ID>

You could modify the Dockerfile to containerise the bot and deploy to Kubernetes. The config can be externalised using a Docker volume mount.

Build Guide

If you plan on developing the bot, you'll need JDK 21 installed on your dev box.

You can use Gradle or Maven to build the bot and pull down the dependencies.

The instructions below are for Linux/macOS, but equivalent Windows scripts are included.

Clone the repo locally (main branch).

Maven

1. From the project root, run ./mvnw clean install. If you want to run the exchange integration tests, use ./mvnw clean install -Pint. To execute both unit and integration tests, use ./mvnw clean install -Pall.
2. Take a look at the Javadoc in the ./target/apidocs folders of the bxbot-trading-api, bxbot-strategy-api, and bxbot-exchange-api modules after the build completes.

Gradle

1. From the project root, run ./gradlew build. If you want to run the exchange integration tests, use ./gradlew integrationTests. To execute both unit and integration tests, use ./gradlew build integrationTests.
2. To generate the Javadoc, run ./gradlew javadoc and look in the ./build/docs/javadoc folders of the bxbot-trading-api, bxbot-strategy-api, and bxbot-exchange-api modules.

Issue & Change Management

Issues and new features are managed using the project Issue Tracker - submit bugs here.

You are welcome to take on new features or fix bugs! See here for how to get involved.

For help and general questions about BX-bot, check out the Gitter channel.

Testing

The bot has undergone basic unit testing on a best-effort basis.

There is a CI build running on GitHub Actions.

The latest stable build can always be found on the Releases page. The SNAPSHOT builds on main are active development builds, but the tests should always pass and the bot should always be deployable.

User Guide

_"Change your opinions, keep to your princip