initial commit

v1.0.0 release

gitignore

v1.0.0 Release

Author: jonte-z

.gitignore

@@ -0,0 +1,7 @@
+.python-version
+.env
+.venv
+__pycache__
+output
+market_data
+*.yaml

CHANGELOG.md

@@ -0,0 +1,5 @@
+# Change log
+
+## v1.0.0 - 2023-08-30
+
+- Initial release

LICENSE.md

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) [2023]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

README.md

@@ -0,0 +1,78 @@
+# AI Trading Prototype Backtester
+
+This project is a backtester for the sentiment-analysis cryptocurrency trading strategy that pairs with the live trading bot, [ai-trading-prototype](https://github.com/binance/ai-trading-prototype/). This backtester is designed to run accurate simulations for a given date range on a chosen trading symbol.
+
+![Diagram](../assets/diagram.png?raw=true)
+
+## Disclaimer
+
+This trading bot backtester does not provide financial advice or endorse trading strategies. Users assume all risks, as past results from historical data do not guarantee future returns; the creators bear no responsibility for losses. Please seek guidance from financial experts before trading or investing. By using this project you accept these conditions.
+
+## Features
+
+* A flexible trading strategy builder.
+* Customisable Backtesting strategy.
+* Automated data downloader using `data.binance.vision`.
+* Detailed backtest results and performance assessment, including HTML visualisations of all trades.
+
+## Installation
+
+1. Clone the repository
+```
+git clone https://github.com/binance/ai-trading-prototype-backtester
+```
+2. Move into the cloned directory
+```
+cd ai-trading-prototype-backtester
+```
+3. Install dependencies
+```
+pip install -r requirements.txt
+```
+
+## Usage
+### Configuration
+
+All configurations are stored in `config.yaml.example`. You can specify:
+* `symbol`: The trading symbol/ pair. Example: `ETHUSDT`.
+* `kline_interval`: The interval of the candlesticks. Valid intervals are: `1m, 3m, 5m, 15m, 30m, 1h, 2h, 4h, 6h, 8h, 12h` or `1d`
+* `start_date` and `end_date`: The range of dates to backtest on. Format: `YYYY-MM-DD`.
+* `sentiment_data`: The path to the sentiment data file. Default: `./sentiment_data/sentiment_data.csv`.
+* `start_balance`: The starting balance in quote currency (eg. USDT). Default: `100000`.
+* `order_size`: The order size in base currency (eg. BTC). Default: `0.01`.
+* `total_quantity_limit`: The maximum quantity of base currency (eg. BTC) that can be held at any given time. Default: `1`.
+* `commission`: The trading fee/commission ratio. Default: `0.002`.
+* `logging_level`: The logging detail level. Default: `INFO`.
+
+Please also ensure that the sentiment data file `sentiment_data.csv` is present and formatted as `"headline source","headline collected timestamp (ms)","headline published timestamp (ms)","headline","sentiment"`.
+
+#### Strategy Configuration Profiles
+
+Within the `strategy_configuration` directory, there are 3 extra configuration files. Each file corresponds to a different strategy/risk level (Aggressive, Conservative and Standard). These can be used to quickly test different parameters with varying degrees of risk.
+
+### Run the backtester as module
+
+```
+python -m aitradingprototypebacktester
+```
+
+#### How it works
+
+* During the backtesting process, the backtester checks `/sentiment_data/sentiment_data.csv` for a published headline at each kline/candlestick interval.
+* If a headline was published during the current time-period, it reads the sentiment of the headline.
+* By default, the backtester uses the `successive_strategy` which is defined in `aitradingprototypebacktester/strategy/successive_strategy.py`. The details of how this strategy works is as follows:
+  * If the sentiment was "bullish" (meaning it is expected that the price would increase) it will attempt a BUY order of size = `order_size` of base currency, so long as the `total_quantity_limit` (max. quantity that can be held at any given time) has not yet been reached.
+  * If the sentiment was "bearish" (meaning that a fall in price is expected), it will attempt to SELL `order_size` quantity of the base currency, so long as the current base currency balance is > 0.
+* Once the backtest is complete, it will return a detailed table of results along with an HTML visualisation of all the buys and sells plotted against the trading symbol's price throughout the period.
+  * An image, `backtest_result.png`, will also be generated. This is a static view of the HTML visualisation.
+* If there is a position still open at the end of the backtest, it will be closed at the open price of the last kline in the backtesting period.
+
+## Backtest Results
+
+* As outlined in the `How it works` section above, the backtester will output several files as a result of each backtest:
+  * `output/raw/backtest_result.txt` - A summary of the backtest.
+  * `output/raw/backtest_trades.txt` - A detailed list of each individual trade executed during the backtest.
+  * `output/visualisation/dynamic_report.html` - HTML visualisation of all the buys and sells plotted against the trading symbol's price throughout the period.
+  * `output/visualisation/backtest_result.png` - A static view of the HTML visualisation (image below).
+
+![Backtest Result](../assets/backtest_result.png?raw=true)

aitradingprototypebacktester/__main__.py

@@ -0,0 +1,128 @@
+import logging
+import os
+
+import bokeh
+from backtesting import Backtest
+
+from aitradingprototypebacktester.config_loader import load_config
+from aitradingprototypebacktester.data_downloader import download_binance_data
+from aitradingprototypebacktester.strategy_manager import StrategyManager
+
+
+def initialise_config(config):
+    """
+    Loads configuration values from config.yaml and returns neccessary variables
+    """
+    symbol = config["symbol"]
+    kline_interval = config["kline_interval"]
+    start_date = config["start_date"]
+    end_date = config["end_date"]
+    start_balance = int(config["start_balance"])
+    commission = float(config["commission"])
+    logging_level = config["logging_level"]
+    return (
+        symbol,
+        kline_interval,
+        start_date,
+        end_date,
+        start_balance,
+        commission,
+        logging_level,
+    )
+
+
+def create_directories():
+    """
+    Check if "output/visualisation" and "output/raw" directories exist, if not create them
+    """
+    if not os.path.exists("output/visualisation"):
+        os.makedirs("output/visualisation")
+    if not os.path.exists("output/raw"):
+        os.makedirs("output/raw")
+
+
+def write_results(results):
+    """
+    Write the backtest results and individual trades to output/raw directory separate text files.
+    """
+    create_directories()
+    with open("output/raw/backtest_result.txt", "w") as file:
+        file.write(str(results))
+    with open("output/raw/backtest_trades.txt", "w") as file:
+        file.write(str(results._trades))
+
+
+def convert_from_satoshi(results, bt):
+    """
+    Convert the columns `Size`, `EntryPrice`, `ExitPrice`, `Open`, `High`, `Low`, `Close`, and `Volume` from satoshis back to their original values.
+
+    Args:
+        results (object): The `results` object that contains the trades data.
+        bt (object): The `bt` object that contains the data for the strategy.
+
+    Returns:
+        tuple: A tuple containing the modified `results` object and the modified `bt` object.
+    """
+    # Convert columns: Size, EntryPrice, ExitPrice,  back from satoshis:
+    results._trades = results._trades.assign(
+        Size=results._trades.Size / 1e6,
+        EntryPrice=results._trades.EntryPrice * 1e6,
+        ExitPrice=results._trades.ExitPrice * 1e6,
+    )
+    bt._data = bt._data.assign(
+        Open=results._strategy._data._Data__df.Open * 1e6,
+        High=results._strategy._data._Data__df.High * 1e6,
+        Low=results._strategy._data._Data__df.Low * 1e6,
+        Close=results._strategy._data._Data__df.Close * 1e6,
+        Volume=results._strategy._data._Data__df.Volume / 1e6,
+    )
+    return results, bt
+
+
+if __name__ == "__main__":
+    """
+    - Loads configuration values from config.yaml
+    - Downloads binance kline/candlestick data from data.binance.vision
+    - Creates a Backtest instance with the trading data and trading strategy
+    - Runs backtest, outputs results and creates html + png visualisation of results
+    - Saves raw backtest results and individual trades
+    """
+    config = load_config("config.yaml")
+    (
+        symbol,
+        kline_interval,
+        start_date,
+        end_date,
+        start_balance,
+        commission,
+        logging_level,
+    ) = initialise_config(config)
+    logging.basicConfig(level=logging_level, format="%(message)s")  # Initialise Logging
+
+    kline_data = download_binance_data(
+        symbol, kline_interval, start_date, end_date, logging_level
+    )
+    kline_data = (kline_data / 1e6).assign(
+        Volume=kline_data.Volume * 1e6  # Convert relevant columns to satoshis
+    )
+
+    bt = Backtest(
+        kline_data,
+        StrategyManager,
+        cash=start_balance,
+        commission=commission,
+        exclusive_orders=False,
+    )
+    logging.info("Running Backtest...")
+
+    results = bt.run()
+    results, bt = convert_from_satoshi(
+        results, bt
+    )  # Convert relevant columns back from satoshis
+    logging.info(results)
+
+    write_results(results)
+    plot = bt.plot(resample=False, filename="output/visualisation/dynamic_report.html")
+    bokeh.io.export.export_png(
+        plot, filename="output/visualisation/backtest_result.png"
+    )

aitradingprototypebacktester/config_loader.py

@@ -0,0 +1,10 @@
+import yaml
+
+
+def load_config(file_path: str) -> dict:
+    """
+    Load configuration file and return the content as a dictionary.
+    """
+    with open(file_path, "r") as file:
+        config = yaml.safe_load(file)
+    return config

aitradingprototypebacktester/data_downloader.py

@@ -0,0 +1,105 @@
+import datetime
+import logging
+import os
+from io import BytesIO
+from zipfile import ZipFile
+
+import pandas as pd
+import requests
+
+
+def get_kline_data(symbol, kline_interval, date_str):
+    """
+    Fetches the binance data for given symbol and kline-interval for a particular day
+    """
+    url = f"https://data.binance.vision/data/spot/daily/klines/{symbol.upper()}/{kline_interval}/{symbol.upper()}-{kline_interval}-{date_str}.zip"
+    response = requests.get(url)
+    return response
+
+
+def parse_data(response):
+    """
+    Parses the fetched data and appends it into the list 'data'
+    """
+    data = []
+    with ZipFile(BytesIO(response.content)) as zip_file:
+        for file in zip_file.namelist():
+            with zip_file.open(file) as f:
+                df = pd.read_csv(f, usecols=range(6))
+                df.columns = ["Timestamp", "Open", "High", "Low", "Close", "Volume"]
+                data.append(df)
+    return data
+
+
+def process_data(data):
+    """
+    Processes the list into a DataFrame
+    """
+    df = pd.concat(data)
+    df.columns = ["Timestamp", "Open", "High", "Low", "Close", "Volume"]
+    df["Timestamp"] = pd.to_datetime(df["Timestamp"], unit="ms")
+    df.set_index("Timestamp", inplace=True)
+    df.sort_index(ascending=True, inplace=True)
+    return df
+
+
+def load_csv_data(file_path):
+    """
+    Loads the DataFrame from the specified csv file.
+    """
+    return pd.read_csv(file_path, index_col=[0])
+
+
+def download_binance_data(symbol, kline_interval, start_date, end_date, logging_level):
+    """
+    Downloads Binance data for a given symbol and date range.
+
+    Args:
+        symbol (str): The symbol to download data for.
+        kline_interval (str): The interval of the kline data.
+        start_date (datetime.date): The start date of the data to download.
+        end_date (datetime.date): The end date of the data to download.
+    """
+    logging.basicConfig(level=logging_level, format="%(message)s")  # Initialise Logging
+    market_data_path = f"market_data/{symbol.upper()}/{kline_interval}"
+
+    # Check if the downloads directory exists, create it if it doesn't
+    if not os.path.exists(market_data_path):
+        os.makedirs(market_data_path)
+
+    data = []
+    total_days = (end_date - start_date).days + 1
+    downloaded_days = 0
+
+    while start_date <= end_date:
+        date_str = start_date.strftime("%Y-%m-%d")
+        file_path = f"{market_data_path}/{date_str}.csv"
+
+        # Check if data is already downloaded
+        if os.path.isfile(file_path):
+            df = load_csv_data(file_path)
+            data.append(df)
+            logging.info(f"Loaded data for {date_str} from disk.")
+            downloaded_days += 1
+        else:
+            response = get_kline_data(symbol, kline_interval, date_str)
+
+            if response.status_code == 200:
+                data += parse_data(response)
+
+                # Save processed data to csv file
+                data[-1].to_csv(file_path)
+
+                downloaded_days += 1
+                logging.info(
+                    f"Downloaded and saved kline data for {date_str}\nProgress: {downloaded_days}/{total_days} days ({(downloaded_days/total_days)*100:.2f}%) downloaded.\n"
+                )
+            else:
+                logging.error(
+                    f"Failed to download kline data for date {date_str}. Status code: {response.status_code}"
+                )
+                downloaded_days += 1
+                pass
+
+        start_date += datetime.timedelta(days=1)
+    return process_data(data)

aitradingprototypebacktester/strategy/common_enums.py

@@ -0,0 +1,7 @@
+from enum import Enum
+
+
+class Sentiment(Enum):
+    BULLISH = "bullish"
+    BEARISH = "bearish"
+    UNKNOWN = "unknown"