https://github.com/pablomg-dev/stock-mind
Autonomous trading agent for xStocks (Kraken CLI + Gemini 2.5 Flash) with real-time React dashboard
https://github.com/pablomg-dev/stock-mind
agentic-ai hackaton-project kraken-exchange-api stock-market trading-strategy-simulation
Last synced: 11 days ago
JSON representation
Autonomous trading agent for xStocks (Kraken CLI + Gemini 2.5 Flash) with real-time React dashboard
- Host: GitHub
- URL: https://github.com/pablomg-dev/stock-mind
- Owner: pablomg-dev
- Created: 2026-05-15T00:48:37.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-06-22T01:40:53.000Z (29 days ago)
- Last Synced: 2026-06-22T03:15:46.561Z (29 days ago)
- Topics: agentic-ai, hackaton-project, kraken-exchange-api, stock-market, trading-strategy-simulation
- Language: Python
- Homepage:
- Size: 118 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# 🧠 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](https://github.com/krakenfx/kraken-cli) installed and in `PATH`
- **Node.js 18+** (for the frontend)
- Google AI Studio [API Key](https://aistudio.google.com/app/apikey) (Gemini)
- NewsAPI [API Key](https://newsapi.org/) (optional, for sentiment analysis)
---
## 🛠️ Installation
### 1. Clone the repository
```bash
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:**
```powershell
Copy-Item .env.example .env
```
**Linux/macOS:**
```bash
cp .env.example .env
```
Edit `.env` with your credentials:
```env
GEMINI_API_KEY=your_gemini_key
KRAKEN_API_KEY=your_kraken_key
KRAKEN_API_SECRET=your_kraken_secret
NEWS_API_KEY=your_news_api_key
TICKER=PF_NVDAXUSD
INTERVAL_MINUTES=15
MODE=paper
```
### 3. Python Dependencies (Virtual Environment Recommended)
**Windows PowerShell:**
```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
```
**Linux/macOS:**
```bash
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:**
```powershell
cd frontend
npm install
cd ..
```
**Linux/macOS:**
```bash
cd frontend
npm install
cd ..
```
---
## 🎮 Running the Application
### Quick Start (WSL/Linux)
Use the provided startup script to run all components at once:
```bash
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**
```bash
# Activate virtual environment first
source .venv/bin/activate # Linux/macOS
# or
.\.venv\Scripts\Activate.ps1 # Windows
# Run the agent
python -m agent.main
```
**Terminal 2: FastAPI Backend**
```bash
# Activate virtual environment first
source .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**
```bash
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.