YAML Metadata Warning:empty or missing yaml metadata in repo card
Check out the documentation for more information.
Automated Trading System
Production-grade automated stock trading bot with FinBERT sentiment analysis, technical indicators, risk management, and a live Rich terminal dashboard.
Overview
This project is a fully automated, algorithmic trading bot designed to trade U.S. equities via the Alpaca API. It utilizes a hybrid approach, combining technical analysis (RSI, MACD, Bollinger Bands, VWAP) with AI-driven sentiment analysis (FinBERT + VADER) to generate trading signals. The system features a strict, 8-layer risk management pipeline to ensure capital preservation.
🚀 Quick Start Guide
Follow these steps to download, configure, and run the project locally.
1. Download the Project
If you are downloading this from Hugging Face or GitHub, you can clone the repository or download the ZIP file and extract it.
ash git clone <your-repository-url> cd trading_system
2. Set Up a Virtual Environment (Recommended)
It is highly recommended to run this bot inside a Python virtual environment to avoid dependency conflicts.
On Windows:
ash python -m venv .venv .venv\Scriptsctivate
On macOS/Linux:
ash python3 -m venv .venv source .venv/bin/activate
3. Install Requirements
Install all required Python packages using the provided equirements.txt file.
ash pip install -r requirements.txt
(Optional) For CUDA GPU support (highly recommended for faster FinBERT sentiment analysis):
ash pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu128
4. Configure Your Environment
The bot requires an Alpaca account (Paper or Live) and a NewsAPI key to function.
Copy the example configuration file to create your active .env file: `ash
On Windows (Command Prompt/PowerShell)
copy .env.example .env
On macOS/Linux
cp .env.example .env `
Open the .env file in a text editor and fill in your API keys:
- ALPACA_API_KEY & ALPACA_SECRET_KEY: Get these from your Alpaca Dashboard. (Live keys start with AK, Paper keys start with PK).
- ALPACA_BASE_URL: Use https://paper-api.alpaca.markets for paper trading, or https://api.alpaca.markets for live trading.
- TRADING_MODE: Set to paper or live.
- NEWS_API_KEY: Get this from NewsAPI.
- (Optional) TELEGRAM_BOT_TOKEN & TELEGRAM_CHAT_ID: For mobile alerts.
5. Run the Bot
Once your .env file is configured, you can start the bot!
ash python main.py
Note: The bot will automatically check if the market is open. If the market is closed, it will sleep until the next trading session.
📊 Backtesting
Before running the bot with real money, you should backtest the strategy against historical data.
`ash
Run a backtest on specific symbols over a date range
python -m backtester.engine --symbol AAPL --start 2023-01-01 --end 2024-12-31 ` The backtester includes a realistic cost model (slippage, commissions) and utilizes a vectorized engine for fast execution.
🛡️ Risk Management Pipeline
The bot will never place a trade without passing the strict 8-check risk pipeline:
- Safe Mode — Auto-triggered on 3 consecutive broker API errors.
- Daily Loss — Blocks all trades if the daily loss limit (e.g., ) is hit.
- Equity Drop — Blocks trading if the account equity drops >5% from the start of the day.
- Consecutive Losses — Halts trading for 30 minutes and halves position size after 3 consecutive losses.
- Profit Lock — (Optional) Stops trading for the day after a specific profit target is hit to protect gains.
- Max Positions — Hard cap on simultaneous open positions.
- PDT Compliance — Prevents Pattern Day Trader flags on accounts under ,000.
- Overnight Protection — Refuses new entries after 15:45 ET and force-closes positions before the bell.
📁 Architecture Overview
ext trading_system/ ├── .env # Secret API keys and configuration ├── main.py # Main orchestrator / Entry point ├── config.py # Environment variable loader & validator ├── contracts.py # Cross-module typed interfaces (Pydantic) ├── data/ # SQLite storage & Alpaca market data fetchers ├── signals/ # Technical indicators (RSI, MACD, VWAP) & Sentiment (FinBERT) ├── strategy/ # Trend-following, Mean Reversion, & Regime detection ├── execution/ # Alpaca API wrapper, Risk limits, Order routing, Portfolio state ├── monitoring/ # Rich terminal dashboard, Telegram alerts, & JSON logging ├── backtester/ # Vectorized backtest engine & CSV reporting └── tests/ # pytest test suite
🧪 Running Tests
To ensure everything is working correctly, you can run the test suite:
ash pytest tests/ -v
Disclaimer
This software is for educational and research purposes only. Do not risk money which you are afraid to lose. USE THE SOFTWARE AT YOUR OWN RISK. The authors and all affiliates assume no responsibility for your trading results.