🧠 StockMind

Autonomous AI trading agent for xStocks. Powered by Kraken CLI + Gemini 2.5 Flash with a real-time React dashboard.

---

🚀 Features

• AI-Powered Decisions: Uses Google Gemini 2.5 Flash for intelligent trading decisions
• Technical Analysis: RSI, MACD, SMA indicators for market signals
• Real-Time Dashboard: React frontend with live WebSocket updates
• Paper & Live Trading: Switch between simulation and real trading modes
• News Sentiment: Integrates NewsAPI for market sentiment analysis
• Kraken Integration: Executes trades via Kraken CLI
• SQLite Database: Persistent decision history and tracking
• Dynamic Configuration: Real-time leverage and position size adjustment via dashboard
• Risk Management: Automatic take profit (+5%) and stop loss (-3%) on every trade

---

📋 Requirements

• Python 3.11+
• Kraken CLI installed and in PATH
• Node.js 18+ (for the frontend)
• Google AI Studio API Key (Gemini)
• NewsAPI API Key (optional, for sentiment analysis)

---

🛠️ Installation

1. Clone the repository

git clone https://github.com/pablomg-dev/stock-mind.git
cd stock-mind

2. Environment Configuration

Copy the example environment file and fill in your API keys:

Windows PowerShell:

Copy-Item .env.example .env

Linux/macOS:

cp .env.example .env

Edit .env with your credentials:

GEMINI_API_KEY=your_gemini_keyKRAKEN_API_KEY=your_kraken_keyKRAKEN_API_SECRET=your_kraken_secretNEWS_API_KEY=your_news_api_keyTICKER=PF_NVDAXUSDINTERVAL_MINUTES=15MODE=paper

3. Python Dependencies (Virtual Environment Recommended)

Windows PowerShell:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

Linux/macOS:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Note: If activation fails on Windows due to execution policy, run: Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

4. Frontend Dependencies

Windows PowerShell:

cd frontend
npm install
cd ..

Linux/macOS:

cd frontend
npm install
cd ..

---

🎮 Running the Application

Quick Start (WSL/Linux)

Use the provided startup script to run all components at once:

chmod +x start.sh
./start.sh

This will start:

• Trading Agent
• FastAPI Backend (http://localhost:8000)
• React Frontend (http://localhost:5173)

Press Ctrl+C to stop all services.

Manual Startup (3 terminals)

If you prefer to run components separately:

Terminal 1: Trading Agent

# Activate virtual environment firstsource .venv/bin/activate # Linux/macOS# or
.\.venv\Scripts\Activate.ps1 # Windows# Run the agent
python -m agent.main

Terminal 2: FastAPI Backend

# Activate virtual environment firstsource .venv/bin/activate # Linux/macOS# or
.\.venv\Scripts\Activate.ps1 # Windows# Start the API server
uvicorn api.server:app --reload --host 0.0.0.0 --port 8000

Terminal 3: React Frontend

cd frontend
npm run dev

The frontend will be available at http://localhost:5173

---

📊 Architecture

StockMind/
├── agent/ # Trading agent logic
│ ├── brain.py # Gemini AI decision engine
│ ├── signals.py # Technical indicators (RSI, MACD, SMA)
│ ├── executor.py # Kraken CLI trade execution + dynamic config
│ ├── db.py # SQLite database operations
│ └── main.py # Main trading loop + take profit/stop loss
├── api/ # FastAPI backend
│ └── server.py # REST API + WebSocket server + config endpoints
├── frontend/ # React dashboard
│ ├── src/
│ │ ├── components/
│ │ │ ├── ConfigPanel.jsx # Dynamic configuration panel
│ │ │ ├── ReasoningFeed.jsx # Live decision feed
│ │ │ ├── Portfolio.jsx # Portfolio display
│ │ │ └── PnLChart.jsx # P&L chart
│ │ ├── App.jsx
│ │ └── api.js
│ └── public/
│ └── favicon.svg
├── start.sh # Quick startup script (WSL/Linux)
├── .env.example # Environment template
├── requirements.txt # Python dependencies
└── package.json # Node.js dependencies

---

🔧 Configuration

Trading Mode

Set MODE in .env:

• paper - Simulation mode (no real trades)
• live - Real trading with Kraken

The dashboard displays a Paper or Live badge based on this setting.

API Endpoints

• GET /decisions - Get recent trading decisions
• GET /config - Get current trading mode, leverage, and max position percentage
• POST /config - Update leverage (1-10) and max position percentage (1-25%)
• GET /balance - Get current portfolio balance
• WS /ws - WebSocket for real-time updates

Environment Variables

Variable	Description	Default
GEMINI_API_KEY	Google Gemini API key	Required
KRAKEN_API_KEY	Kraken API key	Required
KRAKEN_API_SECRET	Kraken API secret	Required
NEWS_API_KEY	NewsAPI key for sentiment	Optional
TICKER	Trading pair ticker	PF_NVDAXUSD
INTERVAL_MINUTES	Trading loop interval	15
MODE	Trading mode (paper/live)	paper
FUTURES_LEVERAGE	Default leverage (1-10)	5
MAX_POSITION_PCT	Default max position % (1-25)	10
API_BASE_URL	FastAPI backend URL for agent	http://localhost:8000
STOCKMIND_DB_PATH	SQLite database path	stockmind.db

---

🎨 Tech Stack

Backend

• FastAPI - Modern Python web framework
• Uvicorn - ASGI server
• SQLite - Database
• Google Gemini 2.5 Flash - AI decision engine
• Kraken CLI - Trade execution
• pandas & pandas-ta - Technical analysis

Frontend

• React 18 - UI library
• Vite - Build tool
• TailwindCSS - Styling
• Recharts - Data visualization
• WebSocket API - Real-time updates

---

📝 License

This project is open source and available under the MIT License.

---

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

---

📧 Contact

For questions or support, please open an issue on GitHub.