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	`ycharts_market_agent.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
APCA_API_KEY_ID=your_paper_key
APCA_API_SECRET_KEY=your_paper_secret
APCA_API_BASE_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)
├── multi_api_aggregator.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
├── ycharts_market_agent.py       # Professional analytics
├── dough_report_agent.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

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/test_risk_manager.py

# Run integration tests
pytest tests/test_api_integration.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

Name		Name	Last commit message	Last commit date
Latest commit History 6 Commits
docs		docs
examples		examples
observability		observability
python_risk_manager		python_risk_manager
schema		schema
scripts		scripts
src		src
templates		templates
tests		tests
trading-agent		trading-agent
.bandit		.bandit
.env.example		.env.example
.gitignore		.gitignore
.mutmut-config.py		.mutmut-config.py
.pre-commit-config.yaml		.pre-commit-config.yaml
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
WELCOME.md		WELCOME.md
agent_watchdog.py		agent_watchdog.py
analysis_engine.py		analysis_engine.py
analyze_coverage.py		analyze_coverage.py
api_response.py		api_response.py
autonomous_integration.py		autonomous_integration.py
autonomous_integration_fixed.py		autonomous_integration_fixed.py
autonomous_routes.py		autonomous_routes.py
backend_qa_agent.py		backend_qa_agent.py
background_preloader.py		background_preloader.py
calendar_execution_upgrade.json		calendar_execution_upgrade.json
chat_agent.py		chat_agent.py
check_javascript_syntax.py		check_javascript_syntax.py
circuit_breaker.py		circuit_breaker.py
compliance.py		compliance.py
comprehensive_qa.py		comprehensive_qa.py
comprehensive_qa_workflow.py		comprehensive_qa_workflow.py
config.json		config.json
config.py		config.py
data_feeds.py		data_feeds.py
data_providers.yaml		data_providers.yaml
debug_spacing.py		debug_spacing.py
design_system_agent.py		design_system_agent.py
docker-compose.yml		docker-compose.yml
dough_report_agent.py		dough_report_agent.py
enhanced_analysis_engine.py		enhanced_analysis_engine.py
enhanced_api_clients.py		enhanced_api_clients.py
enhanced_multi_api_aggregator.py		enhanced_multi_api_aggregator.py
enhanced_real_time_data.py		enhanced_real_time_data.py
enhanced_watchlist.py		enhanced_watchlist.py
execution_upgrade.json		execution_upgrade.json
fix_imports.py		fix_imports.py
frontend_detail_qa.py		frontend_detail_qa.py
frontend_qa_agent.py		frontend_qa_agent.py
generate_openapi.py		generate_openapi.py
governance.py		governance.py
health_check.py		health_check.py
http2_connection_manager.py		http2_connection_manager.py
institutional_data_bridge.py		institutional_data_bridge.py
institutional_data_integration.py		institutional_data_integration.py
investigate_html_structure.py		investigate_html_structure.py
javascript_syntax_qa.py		javascript_syntax_qa.py
light_qa_agent.py		light_qa_agent.py
live_signals_parser.py		live_signals_parser.py
logging_config.py		logging_config.py
main.py		main.py
multi_api_aggregator.py		multi_api_aggregator.py
package-lock.json		package-lock.json
package.json		package.json
paper_trading.py		paper_trading.py
performance_tracker.py		performance_tracker.py
phase2c_observability_runbook.json		phase2c_observability_runbook.json
phase2c_upgrade.json		phase2c_upgrade.json
portfolio_manager.py		portfolio_manager.py
price_alerts.py		price_alerts.py
provider_router.py		provider_router.py
provider_upgrade.json		provider_upgrade.json
pytest.ini		pytest.ini
qa_audit_agent.py		qa_audit_agent.py
real_time_data_feeds.py		real_time_data_feeds.py
redis_cache_manager.py		redis_cache_manager.py
requirements.txt		requirements.txt
risk_manager.py		risk_manager.py
run_dough_report_scheduler.py		run_dough_report_scheduler.py
run_web.py		run_web.py
setup.cfg		setup.cfg
simple_real_time_data.py		simple_real_time_data.py
start_dough_report.sh		start_dough_report.sh
stock_discovery.py		stock_discovery.py
test_api_integration.py		test_api_integration.py
test_api_response.py		test_api_response.py
test_api_structure_simple.py		test_api_structure_simple.py
test_bridge_integration.py		test_bridge_integration.py
test_e2e.py		test_e2e.py
test_e2e_api.py		test_e2e_api.py
test_enhanced_features.py		test_enhanced_features.py
test_enhanced_ui.py		test_enhanced_ui.py
test_frontend_alerts.py		test_frontend_alerts.py
test_health_check.py		test_health_check.py
test_institutional_integration.py		test_institutional_integration.py
test_multi_api.py		test_multi_api.py

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

Folders and files

Latest commit

History

Repository files navigation

Trading Buddy

5-Minute Quick Start

What is Trading Buddy?

Architecture Overview

Quick Start

1. Clone the Repository

2. Install Dependencies

3. Configure Environment

4. Run the Application

Documentation

Examples

Key Features

Multi-Source Data Aggregation

Specialized Agents

Risk Management

Paper Trading

Project Structure

API Keys Required

Required (Pick at least one data source)

Recommended

Professional (Optional)

Testing

Deployment

Development

Production with Docker

Environment Variables

Contributing

License

Disclaimer

Not Financial Advice

Risk Warning

No Warranties

Limitation of Liability

Your Responsibilities

By Using This Software, You Acknowledge:

Acknowledgments

About

Topics

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages