Gunbot Quant (GQ)

Gunbot Quant is an open-source, self-hosted toolkit for quantitative trading analysis. It integrates an advanced market screener, a multi-strategy backtesting engine, and serves as optional companion app for the Gunbot trading bot.

The application is a self-contained Python package serving its own React-based frontend, intended for local use. Gunbot is not required to use the core screening and backtesting features.

Blog post about this project: https://www.gunbot.com/blog/gunbot-quant-market-screener-backtesting-tool/

Capabilities

Gunbot Quant is designed to provide a systematic, data-driven workflow for traders.

1. Screen Markets with Precision

Build data-driven watchlists by filtering assets across crypto and stock markets. The screener goes beyond simple indicator values by incorporating market character heuristics, allowing you to find assets that are suitable for specific types of strategies.

Example Screener Setups:

• Find Prime Mean-Reversion Candidates:
  • Filter for avg_vol_30d_quote > 10,000,000 to ensure liquidity.
  • Add conditions rsi_14p < 35 and stochrsi_k_14_3_3 < 20 to find oversold assets.
  • Add adx_14p < 25 to ensure the asset is in a non-trending, ranging state.
• Identify High-Quality Trending Assets:
  • Filter for price_vs_sma200 > 5 (price is 5% above the 200 SMA) to confirm a strong uptrend.
  • Add volatility_consistency < 3.0 to filter out assets with erratic price behavior.
  • Add volume_concentration_pct < 40 to avoid assets susceptible to pump-and-dump schemes.

2. Backtest Strategies at Scale

Validate your ideas by running strategies against historical data. The engine is built for portfolio-level analysis, not just single-symbol tests.

• Portfolio Simulation: Run multiple strategies across your entire screened watchlist in a single batch.
• Aggregated Analytics: View the combined equity curve and performance metrics for your entire simulated portfolio.
• Comprehensive Reports: Analyze 15+ key metrics, including Sharpe/Sortino Ratios, Max Drawdown, Profit Factor, and a breakdown of trade exit reasons.
• Strategy Library: A suite of pre-built, configurable strategies covering Mean Reversion, Trend Following, Breakouts, and more.

3. Integrate with Gunbot (Optional)

For Gunbot users, GQ acts as a powerful analytical and operational dashboard.

• Analyze Live Performance: Connect to a running Gunbot instance to visualize the real-world equity curve of your active trading pairs.
• Discover Better Pairs: Run your live pair's strategy against a basket of quality-screened alternative symbols to find potentially more profitable markets.
• Benchmark Live Strategies: Compare the historical performance of your active Gunbot setup against the entire GQ strategy library.
• 1-Click Deployment: Add any successfully backtested strategy to your Gunbot instance with the exact tested parameters.

Installation & Usage

Prerequisites

• Python (3.10+)
• Poetry (Python dependency manager)

If you don't have these, please follow the detailed First-Time Setup Guide at the bottom of this document. Node.js is not required for standard use.

Running the Application

1. Download the Project:

   • Click the green <> Code button on the GitHub repository page and select Download ZIP.
   • Extract the ZIP file to a permanent location on your computer.

2. Open a Terminal/PowerShell and navigate into the extracted project folder (e.g., cd C:\Users\YourUser\Desktop\gunbot-quant-main).

3. Install Dependencies:

   poetry install --no-root

4. Start the Application:

   poetry run start

After starting, open your web browser and navigate to http://localhost:8000.

---

Command-Line Interface (CLI)

For automation and headless operation, you can use the built-in CLI.

List all pre-defined scenarios:

poetry run gunbot-quant list-scenarios

Run a specific scenario:

poetry run gunbot-quant run "Mean_Reversion_Screener_Last_6_Months"

For Developers

If you intend to modify the application frontend code, you will need Node.js v20+ installed.

1. Clone & Install:

   git clone https://github.com/Gunbot/gunbot-quant.git
   cd gunbot-quant
   poetry install
   npm install --prefix gunbot_quant/frontend

2. Run Dev Servers: This starts the FastAPI backend (with auto-reload) and the Vite frontend (with hot-reloading).

   npm run dev

   • Backend API: http://localhost:8000
   • Frontend Dev Server: http://localhost:5173

Gunbot Integration

• Reference SDK Implementation: The code in gunbot_quant/gunbot_api serves as a practical, real-world example of how to use the official Gunbot Python SDK.
• Strategy Compatibility: The included strategy .js files are compatible with any Gunbot Defi license or higher. They provide a robust suite of open-source strategies that can be directly deployed to your bot from the GQ interface.

Supported Exchanges

Gunbot Quant leverages the CCXT library and Yahoo Finance to fetch historical data, providing support for a wide range of markets.

Primary Crypto Exchanges (Gunbot Compatible)

These exchanges are recommended as they are also supported by Gunbot, enabling a seamless workflow from backtesting in GQ to live deployment. They generally offer reliable and deep historical data.

Exchange	CCXT ID
Binance	binance
Binance US	binanceus
BingX	bingx
Bitget	bitget
Bybit	bybit
Coinbase	coinbase
Gate.io	gate
HTX (Huobi)	htx
Kraken	kraken
KuCoin	kucoin
MEXC	mexc
OKX	okx
Poloniex	poloniex

Stocks & ETFs

Traditional financial assets are supported via Yahoo Finance. This allows you to screen and backtest individual stocks, ETFs, and indices.

• Yahoo Finance (ID: yfinance)

Other CCXT-Supported Exchanges

The following spot exchanges are also available. Data availability for older assets and less common timeframes may vary by exchange.

Exchange	Exchange	Exchange
Bequant	Bitrue	FMFW.io
Bithumb	Bitstamp	HashKey Global
BitMart	Bitvavo	LBank
BTC-Alpha	CoinCatch	MyOKX (EEA)
Coins.ph	DigiFinex	NovaDAX
ProBit	TimeX	Upbit
Vertex	Waves.Exchange	WhiteBit
XT	EXMO	p2b
OKX (US)

Important Notes

• Data Availability: Support for an exchange does not guarantee the availability of deep historical data for all pairs or timeframes. This is determined by the exchange's own API limitations.
• API Rate Limits: When fetching large amounts of data for the first time, you may encounter exchange-side API rate limits. The tool caches data locally to minimize future requests.

License

This project is licensed under the MIT License. See the LICENSE file for details.

---

Appendix: First-Time Setup

Windows

1. Install Python:

   • Go to the official Python website's download page.
   • Download the "Windows installer (64-bit)".
   • Run the installer. Important: On the first screen of the installer, check the box that says "Add Python to PATH".
   • Click "Install Now" and complete the setup.
   • Open a new Command Prompt or PowerShell and type python --version to verify it's installed.

2. Install Poetry:

   • Open a new PowerShell terminal (not Command Prompt).
   • Run the following command to download and install Poetry:

     (Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -

   • Close and reopen PowerShell, then type poetry --version to verify it's installed.

macOS / Linux

1. Install Python:

   • Python is usually pre-installed. Open your terminal and check with python3 --version.
   • If it's not installed or you need a newer version, it's best to use your system's package manager (e.g., sudo apt-get install python3.10 on Debian/Ubuntu, or Homebrew on macOS: brew install python).

2. Install Poetry:

   • Open your terminal and run the official installation script:

     curl -sSL https://install.python-poetry.org | python3 -

   • Follow the on-screen instructions to add Poetry to your shell's PATH.
   • Close and reopen your terminal, then type poetry --version to verify it's installed.