{"repo": "aristidesai/ibkr-aihedge", "files": {"README.md": {"c30f17e00d777b33ac0fcbd5dc7f9265d13f31a2": {"t": 1786068578.1980627, "n": 10959, "h": "b2316d3b8d998017", "c": "# IBKR AI Hedge Fund Integration\n

\"IBKR\" \"Plus\" \"GPT\"

\n\n\n[![Python](https://img.shields.io/badge/Python-3.8%2B-blue)](https://www.python.org/)\n[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n[![Code Style](https://img.shields.io/badge/Code%20Style-Black-black)](https://black.readthedocs.io/)\n[![Twitter](https://img.shields.io/badge/Twitter-@aristidesai-1DA1F2)](https://x.com/aristidesai)\n\nAn automated trading integration that connects Interactive Brokers with AI-powered financial analysis for intelligent trading decisions.\n\n> **Created by**: [@aristides lintzeris](https://x.com/aristidesai) | **Follow for updates and trading insights**\n\n## Features\n\n- **Real-time Data Processing**: Connect to Interactive Brokers API for live market data\n- **AI-Powered Analysis**: Leverage multiple AI models for comprehensive market analysis\n- **Automated Trading**: Execute trades based on AI recommendations with built-in risk management\n- **Multi-Market Support**: Configure for any stock exchange or market worldwide\n- **Risk Management**: Position sizing, stop-losses, and daily trade limits\n- **Paper Trading Support**: Test strategies safely before live trading\n- **Comprehensive Logging**: Track all activities and performance metrics\n\n## Table of Contents\n\n- [Quick Start](#quick-start)\n- [Prerequisites](#prerequisites)\n- [Installation](#installation)\n- [Configuration](#configuration)\n- [Usage](#usage)\n- [Risk Management](#risk-management)\n- [Monitoring](#monitoring)\n- [Documentation](#documentation)\n- [Troubleshooting](#troubleshooting)\n- [Contributing](#contributing)\n- [Contact](#contact)\n- [Disclaimer](#disclaimer)\n\n## Quick Start\n\nGet up and running in 5 minutes:\n\n```bash\n# 1. Clone the repository\ngit clone https://github.com/aristideslintzeris/ibkr-ai-hedge-fund.git\ncd ibkr-ai-hedge-fund\n\n# 2. Install dependencies\npip install -r requirements.txt\n\n# 3. Configure environment\ncp env.template .env\n# Edit .env with your API keys and settings\n\n# 4. Start paper trading\npython ibkr_integration.py\n```\n\n## Prerequisites\n\n### Interactive Brokers Account\n- Sign up at [Interactive Brokers](https://www.interactivebrokers.com/)\n- Download and install **Trader Workstation (TWS)** or **IB Gateway**\n- **Recommended**: Start with paper trading for testing\n\n### Python Environment\n- Python 3.8 or higher\n- pip package manager\n\n### API Keys (Required)\n- **OpenAI API Key**: For GPT models\n- **Financial Datasets API Key**: For market data\n- **Optional**: Additional model providers (Anthropic, Groq, DeepSeek, Google)\n\n## Installation\n\n### 1. Clone the Repository\n```bash\ngit clone https://github.com/aristideslintzeris/ibkr-ai-hedge-fund.git\ncd ibkr-ai-hedge-fund\n```\n\n### 2. Install Dependencies\n```bash\npip install -r requirements.txt\n```\n\n### 3. Clone AI-Hedge-Fund Repository\n```bash\ngit clone https://github.com/virattt/ai-hedge-fund.git\n```\n\n### 4. Configure Environment\n```bash\ncp env.template .env\n```\n\n## Configuration\n\n### Environment Variables\n\nEdit your `.env` file with the following configurations:\n\n```env\n# IBKR Connection Settings\nIBKR_HOST=127.0.0.1\nIBKR_PORT=7497 # 7497 for paper trading, 7496 for live\nIBKR_CLIENT_ID=123\n\n# Trading Settings\nINITIAL_CASH=10000.0 # Starting capital (adjust to your preference)\nCURRENCY=USD # USD, EUR, GBP, AUD, CAD, etc.\nMAX_POSITION_SIZE=0.2 # Maximum 20% per position\nMAX_DAILY_TRADES=10 # Maximum trades per day\nSTOP_LOSS_PERCENTAGE=0.05 # 5% stop loss\nTAKE_PROFIT_PERCENTAGE=0.10 # 10% take profit\n\n# Market Settings\nMARKET_TIMEZONE=US/Eastern # Your market timezone\nTRADING_SCHEDULE=09:30 # Daily analysis time (24-hour format)\n\n# Watchlist (comma-separated stock symbols)\nWATCHLIST=AAPL,GOOGL,MSFT,AMZN,TSLA,NVDA,META,NFLX,BABA,V\n\n# AI Model Configuration\nPRIMARY_MODEL=gpt-4o-mini\nBACKUP_MODELS=gpt-3.5-turbo,claude-3-haiku\n\n# API Keys (REQUIRED)\nOPENAI_API_KEY=your-openai-api-key\nFINANCIAL_DATASETS_API_KEY=your-financial-datasets-api-key\n\n# Optional AI Model Providers\nANTHROPIC_API_KEY=your-anthropic-api-key\nGROQ_API_KEY=your-groq-api-key\nDEEPSEEK_API_KEY=your-deepseek-api-key\nGOOGLE_API_KEY=your-google-api-key\n\n# Logging\nLOG_LEVEL=INFO # DEBUG, INFO, WARNING, ERROR\nLOG_FILE=ibkr_hedge_fund.log\n```\n\n### Market-Specific Examples\n\n
\nπŸ‡ΊπŸ‡Έ US Market Configuration\n\n```env\nCURRENCY=USD\nMARKET_TIMEZONE=US/Eastern\nTRADING_SCHEDULE=09:30\nWATCHLIST=AAPL,GOOGL,MSFT,AMZN,TSLA,NVDA,META,NFLX,JPM,JNJ\n```\n
\n\n
\nπŸ‡ͺπŸ‡Ί European Market Configuration\n\n```env\nCURRENCY=EUR\nMARKET_TIMEZONE=Europe/London\nTRADING_SCHEDULE=09:00\nWATCHLIST=ASML,SAP,LVMH,NESN,NOVN,ROG,OR,SAN,INGA,PHIA\n```\n
\n\n
\nπŸ‡¦πŸ‡Ί Australian Market Configuration\n\n```env\nCURRENCY=AUD\nMARKET_TIMEZONE=Australia/Sydney\nTRADING_SCHEDULE=09:00\nWATCHLIST=CBA,BHP,CSL,WBC,ANZ,NAB,WOW,TLS,RIO,MQG\n```\n
\n\n
\nπŸ‡―πŸ‡΅ Japanese Market Configuration\n\n```env\nCURRENCY=JPY\nMARKET_TIMEZONE=Asia/Tokyo\nTRADING_SCHEDULE=09:00\nWATCHLIST=7203,6758,6861,8411,9984,4661,6098,9432,8001,8031\n```\n
\n\n### IBKR Configuration\n\n1. **Open TWS/IB Gateway**\n2. **Navigate to API Settings**:\n - File β†’ Global Configuration β†’ API β†’ Settings\n3. **Enable API**:\n - βœ… Enable ActiveX and Socket Clients\n - βœ… Read-Only API (uncheck for trading)\n4. **Set Port**:\n - Paper Trading: `7497`\n - Live Trading: `7496`\n5. **Add Trusted IPs**: `127.0.0.1`\n\n## Usage\n\n### Quick Start\n\n1. **Validate Configuration**:\n```bash\npython config.py\n```\n\n2. **Start Paper Trading**:\n```bash\npython ibkr_integration.py\n```\n\n3. **Monitor Logs**:\n```bash\ntail -f ibkr_hedge_fund.log\n```\n\n### Advanced Usage\n\n#### Custom Watchlist\n```python\n# In your .env file\nWATCHLIST=AAPL,GOOGL,MSFT,AMZN,TSLA\n\n# Or modify in config.py\nWATCHLIST = [\"AAPL\", \"GOOGL\", \"MSFT\", \"AMZN\", \"TSLA\"]\n```\n\n#### Scheduling Options\n```python\n# Daily at 9:30 AM\nTRADING_SCHEDULE=09:30\n\n# Multiple times per day (comma-separated)\nTRADING_SCHEDULE=09:30,14:00,16:00\n\n# Weekly on specific days\nTRADING_SCHEDULE=Monday:09:30,Wednesday:09:30,Friday:09:30\n```\n\n#### Risk Management Profiles\n\n
\nConservative Profile\n\n```env\nMAX_POSITION_SIZE=0.1 # 10% max per position\nMAX_DAILY_TRADES=5\nSTOP_LOSS_PERCENTAGE=0.03 # 3% stop loss\nTAKE_PROFIT_PERCENTAGE=0.06 # 6% take profit\n```\n
\n\n
\nModerate Profile\n\n```env\nMAX_POSITION_SIZE=0.15 # 15% max per position\nMAX_DAILY_TRADES=8\nSTOP_LOSS_PERCENTAGE=0.05 # 5% stop loss\nTAKE_PROFIT_PERCENTAGE=0.10 # 10% take profit\n```\n
\n\n
\nAggressive Profile\n\n```env\nMAX_POSITION_SIZE=0.25 # 25% max per position\nMAX_DAILY_TRADES=15\nSTOP_LOSS_PERCENTAGE=0.08 # 8% stop loss\nTAKE_PROFIT_PERCENTAGE=0.15 # 15% take profit\n```\n
\n\n## Risk Management\n\n### Built-in Safety Features\n\n- **Position Sizing**: Automatic position size calculation based on portfolio percentage\n- **Stop Losses**: Configurable stop-loss orders for all positions\n- **Daily Limits**: Maximum number of trades per day\n- **Portfolio Limits**: Maximum allocation per security\n- **Paper Trading**: Safe testing environment\n\n### Risk Monitoring\n\n```python\n# Check current risk metrics\npython -c \"from ibkr_integration import get_portfolio_metrics; print(get_portfolio_metrics())\"\n```\n\n## πŸ“Š Monitoring\n\n### Real-time Monitoring\n\nThe integration provides comprehensive monitoring through:\n\n- **Log Files**: Detailed activity logging\n- **Portfolio Tracking**: Real-time position updates\n- **Performance Metrics**: P&L tracking and analytics\n- **Error Handling**: Automatic error recovery and logging\n\n### Dashboard (Optional)\n\nCreate a simple monitoring dashboard:\n\n```bash\npython dashboard.py\n```\n\n## Documentation\n\nComprehensive documentation is available in the `/docs` folder:\n\n- **[Installation Guide](docs/installation.md)**: Detailed setup instructions\n- **[Configuration Guide](docs/configuration.md)**: Complete configuration reference\n- **[API Reference](docs/api.md)**: Code documentation and examples\n- **[Trading Guide](docs/trading.md)**: Trading strategies and best practices\n- **[Troubleshooting](docs/troubleshooting.md)**: Common issues and solutions\n\n## Troubleshooting\n\n### Common Issues\n\n
\nConnection Errors\n\n**Issue**: Cannot connect to IBKR\n```\nError: Connection failed to 127.0.0.1:7497\n```\n\n**Solution**:\n1. Ensure TWS/IB Gateway is running\n2. Check API settings are enabled\n3. Verify correct port (7497 for paper, 7496 for live)\n4. Confirm 127.0.0.1 is in trusted IPs\n
\n\n
\nAPI Key Errors\n\n**Issue**: Invalid API key\n```\nError: OpenAI API key is invalid\n```\n\n**Solution**:\n1. Verify API key in `.env` file\n2. Check API key permissions\n3. Confirm sufficient quota/credits\n4. Test API key independently\n
\n\n
\nTrading Errors\n\n**Issue**: Order rejected\n```\nError: Order rejected - insufficient funds\n```\n\n**Solution**:\n1. Check account balance\n2. Verify market hours\n3. Confirm security permissions\n4. Review position limits\n
\n\n### Debug Mode\n\nEnable detailed logging:\n```env\nLOG_LEVEL=DEBUG\n```\n\n### Test Configuration\n\nRun diagnostic tests:\n```bash\npython -m pytest tests/\n```\n\n## Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests\n5. Submit a pull request\n\n## Contact\n\n- **Creator**: [@aristidesai](https://x.com/aristidesai)\n\nFor project updates, trading insights, and AI developments, follow [@aristidesai](https://x.com/aristidesai) on Twitter.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Disclaimer\n\n**Important**: This software is for educational purposes only. Trading involves substantial risk of loss. Always test thoroughly with paper trading before using real money. The authors and contributors are not responsible for any financial losses.\n\n**Key Points**:\n- Start with paper trading\n- Test thoroughly before live trading\n- Never risk more than you can afford to lose\n- Understand the risks involved\n- Consult with financial professionals\n\n## Support\nContact me on twitter for support - [@aristidesai](https://x.com/aristidesai) \n- **IBKR API**: [Official Documentation](https://interactivebrokers.github.io/tws-api/)\n\n## πŸ™ Acknowledgments\n\n- [AI-Hedge-Fund](https://github.com/virattt/ai-hedge-fund) for the original AI analysis system\n- [Interactive Brokers](https://www.interactivebrokers.com/) for the trading platform\n- Contributors and the open-source community\n\n---\n\nMade by [@aristides lintzeris](https://x.com/aristidesai) \n"}}}}