Trading Buddy

An open-source autonomous trading platform with multi-agent architecture, intelligent data aggregation, and comprehensive risk management.

Built for developers who want to create their own algorithmic trading systems.

5-Minute Quick Start

# Clone the repo
git clone https://github.com/heyhaigh/trading-buddy.git
cd trading-buddy
Run automated setup (creates venv, installs deps, generates secret key)
make setup
Add your API keys to .env (at minimum: Alpaca + one data provider)
nano .env
Start the application
make run
Open http://localhost:8000 in your browser

Need help? See Troubleshooting or run make check-env.

What is Trading Buddy?

Trading Buddy is a production-ready framework for building autonomous stock trading systems. It combines:

• Multi-Agent Architecture: Specialized agents for different trading tasks
• Intelligent Data Aggregation: 10+ market data providers with automatic failover
• Risk Management: Circuit breakers, position limits, and exposure controls
• Paper Trading: Full Alpaca integration for risk-free testing
• Real-Time Monitoring: WebSocket streaming, watchlists, and alerts

Architecture Overview

┌─────────────────────────────────────────────────────────────────────────────┐
│                              TRADING BUDDY                                   │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐        │
│  │    Chat     │  │  Analysis   │  │    Risk     │  │   Trade     │        │
│  │   Agent     │  │   Engine    │  │  Manager    │  │  Executor   │        │
│  │             │  │             │  │             │  │             │        │
│  │ • NL Query  │  │ • Technical │  │ • Position  │  │ • Order     │        │
│  │ • Intent    │  │ • Fundmtl   │  │   Sizing    │  │   Routing   │        │
│  │ • Response  │  │ • Sentiment │  │ • Circuit   │  │ • TWAP/VWAP │        │
│  └──────┬──────┘  └──────┬──────┘  │   Breakers  │  │ • Slippage  │        │
│         │                │         └──────┬──────┘  └──────┬──────┘        │
│         │                │                │                │               │
│  ┌──────┴────────────────┴────────────────┴────────────────┴──────┐        │
│  │                     PROVIDER ROUTER                             │        │
│  │            (Domain-Specific Data Routing + Validation)          │        │
│  └─────┬──────────┬──────────┬──────────┬──────────┬─────────────┘        │
│        │          │          │          │          │                       │
│   ┌────┴────┐┌────┴────┐┌────┴────┐┌────┴────┐┌────┴────┐                 │
│   │ Polygon ││ Finnhub ││ YCharts ││ Tiingo  ││  Yahoo  │                 │
│   │ (Price) ││ (Quote) ││ (Fund.) ││ (News)  ││(Fallbck)│                 │
│   └─────────┘└─────────┘└─────────┘└─────────┘└─────────┘                 │
│                                                                            │
└────────────────────────────────┬───────────────────────────────────────────┘
                                 │
                                 ▼
                    ┌────────────────────────┐
                    │    ALPACA BROKER API   │
                    │    (Paper / Live)      │
                    └────────────────────────┘

Quick Start

1. Clone the Repository

git clone https://github.com/heyhaigh/trading-buddy.git
cd trading-buddy

2. Install Dependencies

# Python dependencies
pip install -r requirements.txt
TypeScript agent (optional)
cd trading-agent && pnpm install && cd ..

3. Configure Environment

cp .env.example .env

Generate a secure secret key:

python -c 'import secrets; print(secrets.token_hex(32))'

Edit .env with your API keys (see API Integrations).

4. Run the Application

python run_web.py

Visit http://localhost:8000 in your browser.

Documentation

| Document | Description | |----------|-------------| | Welcome Guide | The full story—architecture, decisions, and lessons learned | | Getting Started | Step-by-step setup guide | | Architecture | System design, data flow, component interactions | | Agents Guide | All specialized agents, their roles, and how they coordinate | | API Integrations | Data providers, configuration, and rate limits | | Risk Management | Safety features, circuit breakers, position controls | | Troubleshooting | Common issues and solutions |

Examples

Ready-to-run code examples in the examples/ folder:

| Example | Description | |---------|-------------| | basic_trade.py | Place a paper trade via the API | | fetch_quotes.py | Fetch quotes from multiple providers | | custom_indicator.py | Add a custom technical indicator | | custom_agent.py | Create a new specialized agent | | webhook_alerts.py | Set up price alerts with webhooks |

Key Features

Multi-Source Data Aggregation

Trading Buddy intelligently routes data requests to the best available provider with automatic failover:

| Data Domain | Primary | Secondary | Tertiary | Fallback | |-------------|---------|-----------|----------|----------| | Prices | Polygon WS | Tiingo IEX | Finnhub | Yahoo Finance | | Fundamentals | YCharts | FMP | Alpha Vantage | Yahoo Finance | | News | Benzinga | Tiingo News | NewsAPI | - | | Sentiment | Tiingo NLP | StockTwits | - | - | | Corporate Actions | Polygon | FMP | Tiingo | - | | Macro Data | YCharts | FRED | - | - |

Specialized Agents

| Agent | File | Purpose | |-------|------|---------| | Chat Agent | chat_agent.py | Natural language interface for queries and commands | | Analysis Engine | analysis_engine.py | Technical indicators, fundamental analysis | | Risk Manager | risk_manager.py | Position sizing, exposure limits, circuit breakers | | Trade Executor | trade_executor.py | Order routing, execution algorithms (TWAP/VWAP) | | Agent Watchdog | agent_watchdog.py | Process monitoring, auto-restart on failure | | YCharts Agent | ychartsmarketagent.py | Professional financial analytics | | Portfolio Manager | portfolio_manager.py | Portfolio tracking, rebalancing |

Risk Management

Built-in safety features protect your capital:

| Feature | Default | Description | |---------|---------|-------------| | Daily Loss Limit | 3% | Halt trading if daily P&L drops below threshold | | Portfolio Loss Limit | 10% | Emergency stop if total drawdown exceeds limit | | Max Position Size | 5% | Maximum allocation per security | | Max Sector Exposure | 20% | Maximum allocation per sector | | Conviction Threshold | 60% | Minimum confidence score for trade execution |

Paper Trading

Full integration with Alpaca's paper trading API for risk-free testing:

# Environment variables
APCAAPIKEYID=yourpaper_key
APCAAPISECRETKEY=yourpaper_secret
APCAAPIBASE_URL=https://paper-api.alpaca.markets
TRADING_MODE=paper

Project Structure

trading-buddy/
├── docs/                          # Comprehensive documentation
│   ├── ARCHITECTURE.md            # System design
│   ├── AGENTS.md                  # Agent documentation
│   ├── API_INTEGRATIONS.md        # Data provider setup
│   ├── RISK_MANAGEMENT.md         # Safety features
│   └── GETTING_STARTED.md         # Setup guide
│
├── trading-agent/                 # TypeScript trading agent
│   ├── src/
│   │   ├── adapters/             # Broker adapters (Alpaca)
│   │   ├── analytics/            # Factor attribution
│   │   ├── api/                  # REST API server
│   │   ├── audit/                # Compliance logging
│   │   ├── cli/                  # CLI agents
│   │   ├── core/                 # Orchestration
│   │   └── data/                 # Market data providers
│   └── package.json
│
├── templates/                     # Web UI (Flask templates)
├── tests/                         # Test suite
│
├── # Core Python Components
├── web_app.py                    # Flask application (225KB, main entry)
├── multiapiaggregator.py       # Data source aggregation
├── provider_router.py            # Intelligent routing with failover
├── analysis_engine.py            # Technical/fundamental analysis
├── risk_manager.py               # Risk assessment and controls
├── trade_executor.py             # Order execution engine
├── portfolio_manager.py          # Portfolio tracking
├── compliance.py                 # Regulatory compliance
├── paper_trading.py              # Paper trading simulation
│
├── # Specialized Agents
├── agent_watchdog.py             # Process monitoring
├── chat_agent.py                 # Natural language interface
├── ychartsmarketagent.py       # Professional analytics
├── doughreportagent.py         # Market reports
│
├── # Configuration
├── config.json                   # Trading rules and parameters
├── data_providers.yaml           # Provider configuration
├── .env.example                  # Environment template
│
└── # Infrastructure
    ├── requirements.txt          # Python dependencies
    ├── docker-compose.yml        # Container orchestration
    └── pytest.ini               # Test configuration

API Keys Required

Required (Pick at least one data source)

| Service | Purpose | Free Tier | Link | |---------|---------|-----------|------| | Alpaca | Paper/Live Trading | Yes | alpaca.markets | | Polygon | Real-time Prices | Limited | polygon.io | | Finnhub | Quotes & Fundamentals | Yes | finnhub.io |

Recommended

| Service | Purpose | Free Tier | Link | |---------|---------|-----------|------| | Alpha Vantage | Backup Data | Yes | alphavantage.co | | Tiingo | News & IEX Data | Yes | tiingo.com | | NewsAPI | News Articles | Yes | newsapi.org |

Professional (Optional)

| Service | Purpose | Link | |---------|---------|------| | YCharts | Professional Analytics | ycharts.com | | Benzinga | Pro News Feed | benzinga.com | | RapidAPI | Twelve Data, FMP, StockTwits | rapidapi.com |

Testing

# Run all tests
pytest
Run with coverage
pytest --cov=. --cov-report=html
Run specific test file
pytest tests/testriskmanager.py
Run integration tests
pytest tests/testapiintegration.py

Deployment

Development

python run_web.py

Production with Docker

docker-compose up -d

Environment Variables

See .env.example for all configuration options.

Contributing

We welcome contributions! Please see our Contributing Guide.

• Fork the repository
• Create a feature branch (git checkout -b feature/amazing-feature)
• Commit your changes (git commit -m 'Add amazing feature')
• Push to the branch (git push origin feature/amazing-feature)
• Open a Pull Request

License

MIT License - See LICENSE for details.

Disclaimer

This software is provided for educational and research purposes only.

Not Financial Advice

• This software does NOT provide financial, investment, tax, or legal advice
• No content, signals, alerts, or outputs from this software should be construed as a recommendation to buy, sell, or hold any security
• The developers are not registered investment advisors, broker-dealers, or financial planners

Risk Warning

• Trading in stocks, options, and other financial instruments involves substantial risk of loss
• You may lose some or all of your invested capital
• Past performance, including backtests and paper trading results, does NOT guarantee future results
• Hypothetical or simulated performance results have inherent limitations and biases

No Warranties

• This software is provided "as is" without warranty of any kind, express or implied
• The developers make no guarantees about the accuracy, reliability, completeness, or timeliness of data
• The developers are not responsible for any errors, bugs, or malfunctions in the software
• API integrations may fail, provide incorrect data, or experience outages

Limitation of Liability

• Under no circumstances shall the authors, contributors, or copyright holders be liable for any direct, indirect, incidental, special, exemplary, or consequential damages
• This includes, but is not limited to: loss of profits, data, business opportunities, or trading losses
• Use of this software is entirely at your own risk

Your Responsibilities

• Always do your own research (DYOR) before making any investment decisions
• Consult with a qualified financial advisor, tax professional, or attorney before investing real money
• Thoroughly test any strategies in paper trading before using real capital
• Understand that algorithmic trading can result in rapid and significant losses
• Ensure compliance with all applicable laws and regulations in your jurisdiction

By Using This Software, You Acknowledge:

• You have read and understood this disclaimer
• You accept full responsibility for any trading decisions made using this software
• You will not hold the developers liable for any financial losses

Acknowledgments

• Alpaca - Commission-free trading API
• Polygon.io - Real-time market data
• YCharts - Professional financial analytics

See more AI experiments at heyhaigh.ai

Built with care by @heyhaigh