# 🐟 BIGGFISH Quick Start

Get up and running in 5 minutes!

## TL;DR

```bash
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**
   ```bash
   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

```bash
# 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?

```bash
# 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`