{"id":51549133,"url":"https://github.com/pablomg-dev/stock-mind","last_synced_at":"2026-07-09T22:00:57.472Z","repository":{"id":363137761,"uuid":"1239299191","full_name":"pablomg-dev/stock-mind","owner":"pablomg-dev","description":"Autonomous trading agent for xStocks (Kraken CLI + Gemini 2.5 Flash) with real-time React dashboard","archived":false,"fork":false,"pushed_at":"2026-06-22T01:40:53.000Z","size":121,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-22T03:15:46.561Z","etag":null,"topics":["agentic-ai","hackaton-project","kraken-exchange-api","stock-market","trading-strategy-simulation"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pablomg-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-15T00:48:37.000Z","updated_at":"2026-06-22T01:40:57.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/pablomg-dev/stock-mind","commit_stats":null,"previous_names":["pablomg-dev/stock-mind"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/pablomg-dev/stock-mind","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pablomg-dev%2Fstock-mind","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pablomg-dev%2Fstock-mind/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pablomg-dev%2Fstock-mind/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pablomg-dev%2Fstock-mind/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pablomg-dev","download_url":"https://codeload.github.com/pablomg-dev/stock-mind/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pablomg-dev%2Fstock-mind/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35313756,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-09T02:00:07.329Z","response_time":57,"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":["agentic-ai","hackaton-project","kraken-exchange-api","stock-market","trading-strategy-simulation"],"created_at":"2026-07-09T22:00:56.783Z","updated_at":"2026-07-09T22:00:57.462Z","avatar_url":"https://github.com/pablomg-dev.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🧠 StockMind\r\n\r\n\u003e **Autonomous AI trading agent for xStocks.** Powered by Kraken CLI + Gemini 2.5 Flash with a real-time React dashboard.\r\n\r\n![Python](https://img.shields.io/badge/Python-3.11+-3776AB) ![React](https://img.shields.io/badge/React-18+-61DAFB) ![FastAPI](https://img.shields.io/badge/FastAPI-0.115+-009688) ![Gemini](https://img.shields.io/badge/Gemini-2.5%20Flash-8E75B2) ![SQLite](https://img.shields.io/badge/SQLite-Database-003B57) ![Mode](https://img.shields.io/badge/Mode-Paper%20%2F%20Live-22c55e)\r\n\r\n---\r\n\r\n## 🚀 Features\r\n\r\n- **AI-Powered Decisions**: Uses Google Gemini 2.5 Flash for intelligent trading decisions\r\n- **Technical Analysis**: RSI, MACD, SMA indicators for market signals\r\n- **Real-Time Dashboard**: React frontend with live WebSocket updates\r\n- **Paper \u0026 Live Trading**: Switch between simulation and real trading modes\r\n- **News Sentiment**: Integrates NewsAPI for market sentiment analysis\r\n- **Kraken Integration**: Executes trades via Kraken CLI\r\n- **SQLite Database**: Persistent decision history and tracking\r\n- **Dynamic Configuration**: Real-time leverage and position size adjustment via dashboard\r\n- **Risk Management**: Automatic take profit (+5%) and stop loss (-3%) on every trade\r\n\r\n---\r\n\r\n## 📋 Requirements\r\n\r\n- **Python 3.11+**\r\n- [Kraken CLI](https://github.com/krakenfx/kraken-cli) installed and in `PATH`\r\n- **Node.js 18+** (for the frontend)\r\n- Google AI Studio [API Key](https://aistudio.google.com/app/apikey) (Gemini)\r\n- NewsAPI [API Key](https://newsapi.org/) (optional, for sentiment analysis)\r\n\r\n---\r\n\r\n## 🛠️ Installation\r\n\r\n### 1. Clone the repository\r\n\r\n```bash\r\ngit clone https://github.com/pablomg-dev/stock-mind.git\r\ncd stock-mind\r\n```\r\n\r\n### 2. Environment Configuration\r\n\r\nCopy the example environment file and fill in your API keys:\r\n\r\n**Windows PowerShell:**\r\n\r\n```powershell\r\nCopy-Item .env.example .env\r\n```\r\n\r\n**Linux/macOS:**\r\n\r\n```bash\r\ncp .env.example .env\r\n```\r\n\r\nEdit `.env` with your credentials:\r\n\r\n```env\r\nGEMINI_API_KEY=your_gemini_key\r\nKRAKEN_API_KEY=your_kraken_key\r\nKRAKEN_API_SECRET=your_kraken_secret\r\nNEWS_API_KEY=your_news_api_key\r\nTICKER=PF_NVDAXUSD\r\nINTERVAL_MINUTES=15\r\nMODE=paper\r\n```\r\n\r\n### 3. Python Dependencies (Virtual Environment Recommended)\r\n\r\n**Windows PowerShell:**\r\n\r\n```powershell\r\npython -m venv .venv\r\n.\\.venv\\Scripts\\Activate.ps1\r\npip install -r requirements.txt\r\n```\r\n\r\n**Linux/macOS:**\r\n\r\n```bash\r\npython3 -m venv .venv\r\nsource .venv/bin/activate\r\npip install -r requirements.txt\r\n```\r\n\r\n\u003e **Note:** If activation fails on Windows due to execution policy, run: `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned`\r\n\r\n### 4. Frontend Dependencies\r\n\r\n**Windows PowerShell:**\r\n\r\n```powershell\r\ncd frontend\r\nnpm install\r\ncd ..\r\n```\r\n\r\n**Linux/macOS:**\r\n\r\n```bash\r\ncd frontend\r\nnpm install\r\ncd ..\r\n```\r\n\r\n---\r\n\r\n## 🎮 Running the Application\r\n\r\n### Quick Start (WSL/Linux)\r\n\r\nUse the provided startup script to run all components at once:\r\n\r\n```bash\r\nchmod +x start.sh\r\n./start.sh\r\n```\r\n\r\nThis will start:\r\n\r\n- Trading Agent\r\n- FastAPI Backend (http://localhost:8000)\r\n- React Frontend (http://localhost:5173)\r\n\r\nPress `Ctrl+C` to stop all services.\r\n\r\n### Manual Startup (3 terminals)\r\n\r\nIf you prefer to run components separately:\r\n\r\n**Terminal 1: Trading Agent**\r\n\r\n```bash\r\n# Activate virtual environment first\r\nsource .venv/bin/activate  # Linux/macOS\r\n# or\r\n.\\.venv\\Scripts\\Activate.ps1  # Windows\r\n\r\n# Run the agent\r\npython -m agent.main\r\n```\r\n\r\n**Terminal 2: FastAPI Backend**\r\n\r\n```bash\r\n# Activate virtual environment first\r\nsource .venv/bin/activate  # Linux/macOS\r\n# or\r\n.\\.venv\\Scripts\\Activate.ps1  # Windows\r\n\r\n# Start the API server\r\nuvicorn api.server:app --reload --host 0.0.0.0 --port 8000\r\n```\r\n\r\n**Terminal 3: React Frontend**\r\n\r\n```bash\r\ncd frontend\r\nnpm run dev\r\n```\r\n\r\nThe frontend will be available at `http://localhost:5173`\r\n\r\n---\r\n\r\n## 📊 Architecture\r\n\r\n```\r\nStockMind/\r\n├── agent/              # Trading agent logic\r\n│   ├── brain.py       # Gemini AI decision engine\r\n│   ├── signals.py     # Technical indicators (RSI, MACD, SMA)\r\n│   ├── executor.py    # Kraken CLI trade execution + dynamic config\r\n│   ├── db.py          # SQLite database operations\r\n│   └── main.py        # Main trading loop + take profit/stop loss\r\n├── api/               # FastAPI backend\r\n│   └── server.py      # REST API + WebSocket server + config endpoints\r\n├── frontend/          # React dashboard\r\n│   ├── src/\r\n│   │   ├── components/\r\n│   │   │   ├── ConfigPanel.jsx      # Dynamic configuration panel\r\n│   │   │   ├── ReasoningFeed.jsx   # Live decision feed\r\n│   │   │   ├── Portfolio.jsx        # Portfolio display\r\n│   │   │   └── PnLChart.jsx        # P\u0026L chart\r\n│   │   ├── App.jsx\r\n│   │   └── api.js\r\n│   └── public/\r\n│       └── favicon.svg\r\n├── start.sh           # Quick startup script (WSL/Linux)\r\n├── .env.example       # Environment template\r\n├── requirements.txt   # Python dependencies\r\n└── package.json       # Node.js dependencies\r\n```\r\n\r\n---\r\n\r\n## 🔧 Configuration\r\n\r\n### Trading Mode\r\n\r\nSet `MODE` in `.env`:\r\n\r\n- `paper` - Simulation mode (no real trades)\r\n- `live` - Real trading with Kraken\r\n\r\nThe dashboard displays a **Paper** or **Live** badge based on this setting.\r\n\r\n### API Endpoints\r\n\r\n- `GET /decisions` - Get recent trading decisions\r\n- `GET /config` - Get current trading mode, leverage, and max position percentage\r\n- `POST /config` - Update leverage (1-10) and max position percentage (1-25%)\r\n- `GET /balance` - Get current portfolio balance\r\n- `WS /ws` - WebSocket for real-time updates\r\n\r\n### Environment Variables\r\n\r\n| Variable            | Description                   | Default                 |\r\n| ------------------- | ----------------------------- | ----------------------- |\r\n| `GEMINI_API_KEY`    | Google Gemini API key         | Required                |\r\n| `KRAKEN_API_KEY`    | Kraken API key                | Required                |\r\n| `KRAKEN_API_SECRET` | Kraken API secret             | Required                |\r\n| `NEWS_API_KEY`      | NewsAPI key for sentiment     | Optional                |\r\n| `TICKER`            | Trading pair ticker           | `PF_NVDAXUSD`           |\r\n| `INTERVAL_MINUTES`  | Trading loop interval         | `15`                    |\r\n| `MODE`              | Trading mode (paper/live)     | `paper`                 |\r\n| `FUTURES_LEVERAGE`  | Default leverage (1-10)       | `5`                     |\r\n| `MAX_POSITION_PCT`  | Default max position % (1-25) | `10`                    |\r\n| `API_BASE_URL`      | FastAPI backend URL for agent | `http://localhost:8000` |\r\n| `STOCKMIND_DB_PATH` | SQLite database path          | `stockmind.db`          |\r\n\r\n---\r\n\r\n## 🎨 Tech Stack\r\n\r\n### Backend\r\n\r\n- **FastAPI** - Modern Python web framework\r\n- **Uvicorn** - ASGI server\r\n- **SQLite** - Database\r\n- **Google Gemini 2.5 Flash** - AI decision engine\r\n- **Kraken CLI** - Trade execution\r\n- **pandas \u0026 pandas-ta** - Technical analysis\r\n\r\n### Frontend\r\n\r\n- **React 18** - UI library\r\n- **Vite** - Build tool\r\n- **TailwindCSS** - Styling\r\n- **Recharts** - Data visualization\r\n- **WebSocket API** - Real-time updates\r\n\r\n---\r\n\r\n## 📝 License\r\n\r\nThis project is open source and available under the MIT License.\r\n\r\n---\r\n\r\n## 🤝 Contributing\r\n\r\nContributions are welcome! Please feel free to submit a Pull Request.\r\n\r\n---\r\n\r\n## 📧 Contact\r\n\r\nFor questions or support, please open an issue on GitHub.\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpablomg-dev%2Fstock-mind","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpablomg-dev%2Fstock-mind","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpablomg-dev%2Fstock-mind/lists"}