biggfish/QUICKSTART.md

🐟 BIGGFISH Quick Start

Get up and running in 5 minutes!

TL;DR

cd /workspace/extra/repos/biggfish

# 1. Verify installation
./verify.sh

# 2. Copy config
cp config/config.example.json config/config.json

# 3. Add your Alpaca API keys to config.json
# Get free paper trading keys at: https://alpaca.markets/

# 4. Install dependencies
pip install -r requirements.txt

# 5. Test it works
python src/cli.py market

# 6. Run your first scan
python src/cli.py scan

# 7. Start the system
python src/main.py

What Happens Next?

When You Run python src/main.py:

1. System Initializes 🚀

   • Connects to Alpaca (paper trading)
   • Loads your $100 starting balance
   • Begins monitoring

2. First Scan (immediate)

   • Scans 30+ small cap stocks
   • Scores each based on momentum, volume, volatility
   • Identifies top 5-10 opportunities

3. Strategy Generation 🧠

   • Creates 3-5 trading strategies
   • Calculates entry, target, and stop prices
   • Determines position sizes (max 20% per position)
   • Generates detailed rationale

4. Awaiting Your Approval ⏳

   • Strategies are logged and saved
   • System waits for you to approve/reject
   • No trades executed without approval

5. Ongoing Monitoring 👀

   • Scans market every 6 hours
   • Checks news every 2 hours
   • Daily report at 4:30 PM ET
   • Continuous learning and adaptation

Your First Trade

1. Review Strategies

   python src/cli.py strategies
   

2. You'll see something like:

   Strategy #1: Momentum Breakout - SOUN
   BUY 15 shares @ $5.50
   Target: $6.33 (+15.0%)
   Stop: $5.12 (-7.0%)
   Position Size: $82.50
   Score: 85/100
   
   Rationale:
   📊 Signals:
   • Score: 85/100
   • 1W Change: +8.2%
   • Volume Surge: 2.3x
   • Volatility: 3.4%
   • Sector: Technology
   
   🚀 Strong volume surge with positive momentum suggests breakout potential.
   

3. Approve It (in future version with Telegram bot)

   • For now, strategies are logged for your review
   • Manual execution via CLI coming soon

CLI Commands

# Check portfolio value and positions
python src/cli.py status

# Scan for opportunities (default: small caps)
python src/cli.py scan

# Scan with different focus
python src/cli.py scan --focus mid_cap_mixed

# Generate fresh strategies
python src/cli.py strategies

# Check if market is open
python src/cli.py market

Understanding the Output

Portfolio Status

💰 Portfolio Value: $100.00
💵 Cash: $100.00
📊 Positions Value: $0.00
📈 Day P/L: $0.00 (+0.00%)

🎯 Goal Progress: $100.00 / $1000.00 (10.0%)
[██░░░░░░░░░░░░░░░░░░] 10.0%

Opportunity Scan

1. SOUN - Score: 85/100
   Price: $5.50 | 1W: +8.2%
   Volume Surge: 2.3x | Volatility: 3.4%
   Sector: Technology

Score Meaning:

• 90-100: Exceptional setup
• 80-89: Strong opportunity
• 70-79: Good opportunity
• 60-69: Acceptable
• <60: Filtered out

Progression Path

Week 1: Learn the system, make first trades

• Goal: $100 → $150 (50% gain)
• Focus: Understanding signals
• Trades: 3-5 small positions

Week 2: Gain confidence

• Goal: $150 → $225 (50% gain)
• Focus: Pattern recognition
• Trades: Start increasing position sizes

Week 3-4: Scale up

• Goal: $225 → $400 (78% gain)
• Focus: Consistency
• Trades: Add mid caps to mix

Week 5-6: Diversify

• Goal: $400 → $700 (75% gain)
• Focus: Risk management
• Trades: Add blue chips

Week 7-8: Final push

• Goal: $700 → $1,000 (43% gain)
• Focus: Capital preservation
• Trades: Selective, high-confidence only

Key Files to Know

• config/config.json - All settings
• logs/biggfish_*.log - System logs
• data/reports/report_*.json - Daily reports
• src/cli.py - Command line interface
• src/main.py - Main system

Common Questions

Q: Is this safe? A: Yes! It's 100% paper trading. No real money involved.

Q: Do I need to approve every trade? A: Yes, require_approval: true in config. Change to false for full automation (not recommended at first).

Q: What if I lose money? A: System has safety limits:

• Max 5% loss per day (circuit breaker)
• Max 15% total loss (emergency stop)
• Stop losses on every position

Q: Can I run this 24/7? A: Stock market is only open Mon-Fri 9:30 AM - 4:00 PM ET. System will wait when market is closed.

Q: How do I stop it? A: Press Ctrl+C in the terminal

Q: Where are the reports? A: Check data/reports/ directory

Troubleshooting

"Invalid API credentials" → Check config.json has correct Alpaca keys

"Market is closed" → Normal! Wait for market hours

No opportunities found → Try different focus: --focus mid_cap_mixed

Module not found → Run pip install -r requirements.txt

Ready to Go?

# One command to verify everything
./verify.sh

# Then start trading
python src/main.py

Let's catch that BIGGFISH! 🐟🚀

---

Need help? Check the logs: tail -f logs/biggfish_*.log