Skip to main content

​
Prerequisites

Before running the bot, ensure you have:
The bot requires MetaTrader 5 to be running and logged in to fetch real-time market data.

​
Installation

1

Clone the Repository

Clone the project to your local machine:
git clone <repository-url>
cd <repo-folder-name>
2

Install Dependencies

Install all required Python packages:
pip install -r requirements.txt
Required packages include:
  • MetaTrader5 - MT5 Python API
  • pandas - Data manipulation
  • numpy - Numerical computations
  • langchain-groq - Groq LLM integration
  • streamlit - Web dashboard framework
3

Verify Configuration

Ensure your configuration is correct:
# Check secrets file exists
ls .streamlit/secrets.toml

# Verify MetaTrader 5 is running
# Check MT5 system tray icon or task manager

​
Starting the Dashboard

​
Basic Launch

Run the Streamlit application: 
streamlit run app.py
The dashboard will automatically open in your default browser at http://localhost:8501.
On first launch, the bot initializes the connection to MetaTrader 5 and loads the Groq API key from secrets.

​
Custom Port

To run on a different port: 
streamlit run app.py --server.port 8502

​
Network Access

To allow access from other devices on your network: 
streamlit run app.py --server.address 0.0.0.0
Only enable network access on trusted networks. The dashboard may contain sensitive trading information.

​
Dashboard Initialization

When the bot starts, it performs these initialization steps: 
# Set page configuration
st.set_page_config(
    page_title="XAUUSD Trading Bot", 
    page_icon="📈", 
    layout="wide"
)

# Initialize trading bot with API key
bot = XAUUSDTradingBot(api_key=st.secrets["GROQ_API_KEY"])
The bot is now ready to analyze XAUUSD market data.

​
First Analysis

1

Access the Dashboard

Open your browser to http://localhost:8501. You’ll see the main dashboard interface with:
  • Header: ”🤖 XAUUSD Trading Bot Dashboard”
  • Sidebar: Control panel with analysis button
  • Main area: Empty (no analysis yet)
2

Run Your First Analysis

Click the 📈 Run New Analysis button in the sidebar.The bot will:
  1. Connect to MetaTrader 5
  2. Fetch XAUUSD data across 6 timeframes (D1, H4, H1, M30, M15, M5)
  3. Calculate technical indicators (RSI, EMA, ATR)
  4. Send data to Groq LLM for AI analysis
  5. Generate trading signals
First analysis may take 10-30 seconds as the bot processes multi-timeframe data.
3

View Results

Once complete, the dashboard displays:
  • Analysis Tab: Technical analysis and market data by timeframe
  • Trading Signal Tab: AI-generated trading recommendations
  • Sidebar Metrics: Current spread, last update time

​
Command-Line Options

​
Development Mode

Run with auto-reload on file changes: 
streamlit run app.py --server.runOnSave true

​
Headless Mode

Run without opening browser: 
streamlit run app.py --server.headless true

​
Full Options Example

streamlit run app.py \
  --server.port 8501 \
  --server.address localhost \
  --server.headless false \
  --theme.base dark

​
Background Execution

​
Linux/macOS

Run in background using nohup: 
nohup streamlit run app.py > bot.log 2>&1 &
Stop the background process: 
# Find process ID
ps aux | grep streamlit

# Kill process
kill <PID>

​
Windows

Run in background using start: 
start /B streamlit run app.py

​
Using Screen (Linux)

For persistent sessions: 
# Create screen session
screen -S trading-bot

# Run bot
streamlit run app.py

# Detach: Ctrl+A, then D
# Reattach: screen -r trading-bot

​
Troubleshooting

If you see missing module errors:
# Reinstall dependencies
pip install -r requirements.txt

# Verify installation
pip list | grep -E "streamlit|MetaTrader5|langchain-groq"
Ensure:
  1. MT5 is running and logged in
  2. Algorithmic trading is enabled in MT5 settings
  3. You’re using 64-bit Python (matches MT5 architecture)
  4. Try restarting both MT5 and the bot
# Test MT5 connection
python -c "import MetaTrader5 as mt5; print(mt5.initialize())"
If you see GROQ_API_KEY not found:
  1. Verify .streamlit/secrets.toml exists
  2. Check the API key is correctly formatted
  3. Restart Streamlit to reload secrets
# Verify secrets file
cat .streamlit/secrets.toml
If port 8501 is busy:
# Use different port
streamlit run app.py --server.port 8502

# Or kill existing process
lsof -ti:8501 | xargs kill -9  # macOS/Linux

​
Stopping the Bot

  • Browser: Close the browser tab (bot keeps running)
  • Terminal: Press Ctrl+C to stop the server
  • Background: Use kill command with process ID
Always stop the bot gracefully with Ctrl+C to ensure proper cleanup of MT5 connections.

​
Next Steps

Now that the bot is running:
  1. Learn the dashboard features
  2. Understand trading signals
  3. Explore auto-refresh and advanced features

​
Performance Tips

Tested Performance: The bot achieves 65% accuracy for profitable trades on real accounts.
  • Run on a stable internet connection
  • Keep MetaTrader 5 running continuously
  • Use auto-refresh for hands-free monitoring
  • Monitor spread values for optimal entry timing
  • Review signals across multiple timeframes for confluence

Build docs developers (and LLMs) love

Get started for freeTalk to us