{"id":30396407,"url":"https://github.com/GuntharDeNiro/gunbot-quant","last_synced_at":"2025-08-21T13:03:26.806Z","repository":{"id":308714961,"uuid":"1029024309","full_name":"GuntharDeNiro/gunbot-quant","owner":"GuntharDeNiro","description":"An open-source toolkit for quantitative analysis of crypto \u0026 stock markets, featuring an advanced market screener, portfolio backtester, and companion tools for the Gunbot trading bot.","archived":false,"fork":false,"pushed_at":"2025-08-19T08:43:40.000Z","size":946,"stargazers_count":13,"open_issues_count":0,"forks_count":7,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-08-19T10:44:22.636Z","etag":null,"topics":["algorithmic-trading","backtesting","cryptocurrency","data-analysis","fastapi","fintech","gunbot","market-screener","pandas","python","quantitative-finance","react","stocks","trading","trading-bot","trading-strategies"],"latest_commit_sha":null,"homepage":"https://www.gunbot.com","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GuntharDeNiro.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-30T12:09:14.000Z","updated_at":"2025-08-19T08:43:44.000Z","dependencies_parsed_at":"2025-08-07T13:37:34.127Z","dependency_job_id":"754c92e0-f0e5-4f7a-8fce-f8e7e4accf89","html_url":"https://github.com/GuntharDeNiro/gunbot-quant","commit_stats":null,"previous_names":["gunthardeniro/gunbot-quant"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/GuntharDeNiro/gunbot-quant","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GuntharDeNiro%2Fgunbot-quant","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GuntharDeNiro%2Fgunbot-quant/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GuntharDeNiro%2Fgunbot-quant/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GuntharDeNiro%2Fgunbot-quant/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GuntharDeNiro","download_url":"https://codeload.github.com/GuntharDeNiro/gunbot-quant/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GuntharDeNiro%2Fgunbot-quant/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271485574,"owners_count":24767774,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-21T02:00:08.990Z","response_time":74,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["algorithmic-trading","backtesting","cryptocurrency","data-analysis","fastapi","fintech","gunbot","market-screener","pandas","python","quantitative-finance","react","stocks","trading","trading-bot","trading-strategies"],"created_at":"2025-08-21T13:01:06.665Z","updated_at":"2025-08-21T13:03:26.773Z","avatar_url":"https://github.com/GuntharDeNiro.png","language":"JavaScript","funding_links":[],"categories":["Miscellaneous tools","Python","Backtest + live trading"],"sub_categories":["Trading \u0026 Backtesting","General purpose"],"readme":"# Gunbot Quant (GQ)\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Python Version](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/) [![Framework](https://img.shields.io/badge/Framework-FastAPI-blueviolet)](https://fastapi.tiangolo.com/)\n\nGunbot 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](https://www.gunbot.com/) trading bot.\n\nThe 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.\n\nBlog post about this project: [https://www.gunbot.com/blog/gunbot-quant-market-screener-backtesting-tool/](https://www.gunbot.com/blog/gunbot-quant-market-screener-backtesting-tool/)\n\n![Gunbot Quant](screenshot.png)\n\n\n## Capabilities\n\nGunbot Quant is designed to provide a systematic, data-driven workflow for traders.\n\n#### 1. Screen Markets with Precision\nBuild 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.\n\n**Example Screener Setups:**\n-   **Find Prime Mean-Reversion Candidates:**\n    -   Filter for `avg_vol_30d_quote \u003e 10,000,000` to ensure liquidity.\n    -   Add conditions `rsi_14p \u003c 35` and `stochrsi_k_14_3_3 \u003c 20` to find oversold assets.\n    -   Add `adx_14p \u003c 25` to ensure the asset is in a non-trending, ranging state.\n-   **Identify High-Quality Trending Assets:**\n    -   Filter for `price_vs_sma200 \u003e 5` (price is 5% above the 200 SMA) to confirm a strong uptrend.\n    -   Add `volatility_consistency \u003c 3.0` to filter out assets with erratic price behavior.\n    -   Add `volume_concentration_pct \u003c 40` to avoid assets susceptible to pump-and-dump schemes.\n\n#### 2. Backtest Strategies at Scale\nValidate your ideas by running strategies against historical data. The engine is built for portfolio-level analysis, not just single-symbol tests.\n\n-   **Portfolio Simulation:** Run multiple strategies across your entire screened watchlist in a single batch.\n-   **Aggregated Analytics:** View the combined equity curve and performance metrics for your entire simulated portfolio.\n-   **Comprehensive Reports:** Analyze 15+ key metrics, including Sharpe/Sortino Ratios, Max Drawdown, Profit Factor, and a breakdown of trade exit reasons.\n-   **Strategy Library:** A suite of pre-built, configurable strategies covering Mean Reversion, Trend Following, Breakouts, and more.\n\n#### 3. Integrate with Gunbot (Optional)\nFor Gunbot users, GQ acts as a powerful analytical and operational dashboard.\n\n-   **Analyze Live Performance:** Connect to a running Gunbot instance to visualize the real-world equity curve of your active trading pairs.\n-   **Discover Better Pairs:** Run your live pair's strategy against a basket of quality-screened alternative symbols to find potentially more profitable markets.\n-   **Benchmark Live Strategies:** Compare the historical performance of your active Gunbot setup against the entire GQ strategy library.\n-   **1-Click Deployment:** Add any successfully backtested strategy to your Gunbot instance with the exact tested parameters.\n\n## Installation \u0026 Usage\n\n#### Prerequisites\n-   **Python** (3.10+)\n-   **Poetry** (Python dependency manager)\n\u003e If you don't have these, please follow the detailed **[First-Time Setup Guide](#appendix-first-time-setup)** at the bottom of this document. Node.js is **not** required for standard use.\n\n#### Running the Application\n1.  **Download the Project:**\n    -   Click the green `\u003c\u003e Code` button on the GitHub repository page and select **Download ZIP**.\n    -   Extract the ZIP file to a permanent location on your computer.\n\n2.  **Open a Terminal/PowerShell** and navigate into the extracted project folder (e.g., `cd C:\\Users\\YourUser\\Desktop\\gunbot-quant-main`).\n\n3.  **Install Dependencies:**\n    ```bash\n    poetry install --no-root\n    ```\n\n4.  **Start the Application:**\n    ```bash\n    poetry run start\n    ```\n\nAfter starting, open your web browser and navigate to **`http://localhost:8000`**.\n\n---\n\n## Command-Line Interface (CLI)\n\nFor automation and headless operation, you can use the built-in CLI.\n\n**List all pre-defined scenarios:**\n```bash\npoetry run gunbot-quant list-scenarios\n```\n\n**Run a specific scenario:**\n```bash\npoetry run gunbot-quant run \"Mean_Reversion_Screener_Last_6_Months\"\n```\n\n## For Developers\n\nIf you intend to modify the application frontend code, you will need **Node.js v20+** installed.\n\n1.  **Clone \u0026 Install:**\n    ```bash\n    git clone https://github.com/Gunbot/gunbot-quant.git\n    cd gunbot-quant\n    poetry install\n    npm install --prefix gunbot_quant/frontend\n    ```\n\n2.  **Run Dev Servers:**\n    This starts the FastAPI backend (with auto-reload) and the Vite frontend (with hot-reloading).\n    ```bash\n    npm run dev\n    ```\n    -   Backend API: `http://localhost:8000`\n    -   Frontend Dev Server: `http://localhost:5173`\n\n## Gunbot Integration\n\n-   **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](https://pypi.org/project/gunbot-sdk-python/).\n-   **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.\n\n## Supported Exchanges\n\nGunbot Quant leverages the CCXT library and Yahoo Finance to fetch historical data, providing support for a wide range of markets.\n\n#### Primary Crypto Exchanges (Gunbot Compatible)\nThese 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.\n\n| Exchange         | CCXT ID        |\n|------------------|----------------|\n| Binance          | `binance`      |\n| Binance US       | `binanceus`    |\n| BingX            | `bingx`        |\n| Bitget           | `bitget`       |\n| Bybit            | `bybit`        |\n| Coinbase         | `coinbase`     |\n| Gate.io          | `gate`         |\n| HTX (Huobi)      | `htx`          |\n| Kraken           | `kraken`       |\n| KuCoin           | `kucoin`       |\n| MEXC             | `mexc`         |\n| OKX              | `okx`          |\n| Poloniex         | `poloniex`     |\n\n#### Stocks \u0026 ETFs\nTraditional financial assets are supported via Yahoo Finance. This allows you to screen and backtest individual stocks, ETFs, and indices.\n\n-   **Yahoo Finance** (ID: `yfinance`)\n\n#### Other CCXT-Supported Exchanges\nThe following spot exchanges are also available. Data availability for older assets and less common timeframes may vary by exchange.\n\n| Exchange        | Exchange        | Exchange        |\n|-----------------|-----------------|-----------------|\n| Bequant         | Bitrue          | FMFW.io         |\n| Bithumb         | Bitstamp        | HashKey Global  |\n| BitMart         | Bitvavo         | LBank           |\n| BTC-Alpha       | CoinCatch       | MyOKX (EEA)     |\n| Coins.ph        | DigiFinex       | NovaDAX         |\n| ProBit          | TimeX           | Upbit           |\n| Vertex          | Waves.Exchange  | WhiteBit        |\n| XT              | EXMO            | p2b             |\n| OKX (US)        |                 |                 |\n\n\n#### Important Notes\n-   **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.\n-   **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.\n\n## License\n\nThis project is licensed under the MIT License. See the `LICENSE` file for details.\n\n---\n\n## Appendix: First-Time Setup\n\n**Windows**\n1.  **Install Python:**\n    -   Go to the [official Python website's download page](https://www.python.org/downloads/windows/).\n    -   Download the \"Windows installer (64-bit)\".\n    -   Run the installer. **Important:** On the first screen of the installer, check the box that says **\"Add Python to PATH\"**.\n    -   Click \"Install Now\" and complete the setup.\n    -   Open a new Command Prompt or PowerShell and type `python --version` to verify it's installed.\n\n2.  **Install Poetry:**\n    -   Open a new PowerShell terminal (not Command Prompt).\n    -   Run the following command to download and install Poetry:\n        ```powershell\n        (Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -\n        ```\n    -   Close and reopen PowerShell, then type `poetry --version` to verify it's installed.\n\n**macOS / Linux**\n1.  **Install Python:**\n    -   Python is usually pre-installed. Open your terminal and check with `python3 --version`.\n    -   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](https://brew.sh/) on macOS: `brew install python`).\n\n2.  **Install Poetry:**\n    -   Open your terminal and run the official installation script:\n        ```bash\n        curl -sSL https://install.python-poetry.org | python3 -\n        ```\n    -   Follow the on-screen instructions to add Poetry to your shell's PATH.\n    -   Close and reopen your terminal, then type `poetry --version` to verify it's installed.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FGuntharDeNiro%2Fgunbot-quant","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FGuntharDeNiro%2Fgunbot-quant","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FGuntharDeNiro%2Fgunbot-quant/lists"}