353 lines
9.2 KiB
Markdown
353 lines
9.2 KiB
Markdown
# News Analysis & Alert System Guide
|
|
|
|
## Overview
|
|
|
|
The enhanced Gold Trading Simulator now includes a comprehensive news analysis and alerting system that provides real-time market intelligence and automated notifications for significant events.
|
|
|
|
## Key Features
|
|
|
|
### 1. **Real-Time News Feed**
|
|
- Aggregates news from multiple sources (Alpha Vantage, Finnhub)
|
|
- Automatic sentiment analysis using TextBlob
|
|
- Relevance scoring for gold-specific news
|
|
- Impact assessment (HIGH, MEDIUM, LOW)
|
|
- Category classification (MONETARY_POLICY, GEOPOLITICS, ECONOMIC_DATA, etc.)
|
|
|
|
### 2. **Intelligent Alerts**
|
|
- Price movement alerts (spikes, drops)
|
|
- Support/resistance breach detection
|
|
- High volatility warnings
|
|
- Breaking news notifications
|
|
- Economic event reminders
|
|
|
|
### 3. **News-Price Correlation**
|
|
- Tracks how news events affect gold prices
|
|
- Measures correlation strength
|
|
- Identifies significant market-moving events
|
|
|
|
## News Feed Features
|
|
|
|
### Sentiment Analysis
|
|
|
|
The system analyzes every article and assigns:
|
|
- **Sentiment**: POSITIVE, NEGATIVE, or NEUTRAL
|
|
- **Sentiment Score**: -1.0 to +1.0 scale
|
|
- **Overall Market Sentiment**: Aggregated across all articles
|
|
|
|
### Impact Classification
|
|
|
|
News articles are scored for gold market impact:
|
|
- **HIGH**: Federal Reserve decisions, major geopolitical events, significant inflation data
|
|
- **MEDIUM**: Economic indicators, central bank commentary, moderate policy changes
|
|
- **LOW**: General market news with indirect gold correlation
|
|
|
|
### Content Categories
|
|
|
|
- **MONETARY_POLICY**: Fed meetings, interest rate decisions, QE announcements
|
|
- **GEOPOLITICS**: Wars, conflicts, sanctions, international tensions
|
|
- **ECONOMIC_DATA**: CPI, GDP, employment reports, PMI data
|
|
- **MARKET_SENTIMENT**: Risk appetite, safe-haven flows, VIX movements
|
|
- **COMMODITY**: Gold-specific news, mining sector, ETF flows
|
|
|
|
### Filtering Options
|
|
|
|
Filter news by:
|
|
- All articles
|
|
- Bullish (positive sentiment)
|
|
- Bearish (negative sentiment)
|
|
- Neutral articles
|
|
|
|
### Auto-Refresh
|
|
|
|
Enable automatic refresh every 5 minutes to stay current with breaking news.
|
|
|
|
## Alert System
|
|
|
|
### Alert Types
|
|
|
|
**PRICE_SPIKE**
|
|
- Triggered when price increases ≥ 1% (default threshold)
|
|
- Severity: HIGH if ≥ 2%, MEDIUM if ≥ 1%
|
|
|
|
**PRICE_DROP**
|
|
- Triggered when price decreases ≥ 1%
|
|
- Severity: HIGH if ≤ -2%, MEDIUM if ≥ -1%
|
|
|
|
**NEWS_BREAKING**
|
|
- High-impact news articles (impact_on_gold = HIGH)
|
|
- Severity: CRITICAL
|
|
- Includes link to original article
|
|
|
|
**SUPPORT_BREACH**
|
|
- Price breaks below identified support level
|
|
- Severity: HIGH
|
|
- Action required: Consider position adjustment
|
|
|
|
**RESISTANCE_BREACH**
|
|
- Price breaks above identified resistance level
|
|
- Severity: HIGH
|
|
- Action required: Potential breakout trade
|
|
|
|
**HIGH_VOLATILITY**
|
|
- Current price range exceeds 2x average range
|
|
- Severity: MEDIUM
|
|
- Indicates increased market uncertainty
|
|
|
|
**ECONOMIC_EVENT**
|
|
- Upcoming scheduled events (Fed meetings, CPI releases, etc.)
|
|
- Severity varies by importance
|
|
|
|
### Severity Levels
|
|
|
|
- **CRITICAL**: Immediate attention required, major market event
|
|
- **HIGH**: Significant event requiring awareness
|
|
- **MEDIUM**: Notable event worth monitoring
|
|
- **LOW**: Informational alert
|
|
|
|
## API Keys & Configuration
|
|
|
|
### Required API Keys
|
|
|
|
**Alpha Vantage** (Required)
|
|
- Provides: Market data + News Sentiment API
|
|
- Free tier: 500 calls/day
|
|
- Get key: https://www.alphavantage.co/support/#api-key
|
|
- Includes gold price data AND news/sentiment
|
|
|
|
**OpenRouter** (Required)
|
|
- Provides: Claude 3.5 Sonnet AI analysis
|
|
- Pay-per-use pricing
|
|
- Get key: https://openrouter.ai/
|
|
|
|
### Optional API Keys
|
|
|
|
**Finnhub** (Optional - Enhanced News)
|
|
- Provides: Additional financial news coverage
|
|
- Free tier: 60 calls/minute
|
|
- Get key: https://finnhub.io/register
|
|
- Adds more news sources and broader coverage
|
|
|
|
**NewsAPI** (Reserved for future)
|
|
- Currently not implemented
|
|
- Placeholder for additional news source
|
|
|
|
### Environment Configuration
|
|
|
|
Add to `backend/.env`:
|
|
|
|
```bash
|
|
# Required
|
|
ALPHA_VANTAGE_API_KEY=your_key_here
|
|
OPENROUTER_API_KEY=your_key_here
|
|
|
|
# Optional (for more news coverage)
|
|
FINNHUB_API_KEY=your_key_here
|
|
NEWS_API_KEY=
|
|
```
|
|
|
|
## API Endpoints
|
|
|
|
### News Feed
|
|
```
|
|
GET /api/news/feed?limit=50
|
|
```
|
|
|
|
Returns:
|
|
- Array of news articles
|
|
- Bullish/bearish/neutral counts
|
|
- Overall market sentiment
|
|
- Average sentiment score
|
|
|
|
### Alerts
|
|
```
|
|
GET /api/news/alerts?limit=50
|
|
```
|
|
|
|
Returns:
|
|
- Recent alerts
|
|
- Critical alert count
|
|
- Unread alert count
|
|
|
|
### Economic Calendar
|
|
```
|
|
GET /api/news/economic-calendar
|
|
```
|
|
|
|
Returns:
|
|
- Upcoming economic events
|
|
- High-impact event count
|
|
|
|
### Clear Alerts
|
|
```
|
|
POST /api/news/alerts/clear
|
|
```
|
|
|
|
Removes alerts older than 24 hours.
|
|
|
|
## News Relevance Scoring
|
|
|
|
The system uses a sophisticated algorithm to score news relevance:
|
|
|
|
### High Relevance Keywords (0.4 points each)
|
|
- gold, xau, precious metals, bullion, gold price
|
|
- gold market, gold trading, gold miners, gold etf
|
|
|
|
### Medium Relevance Keywords (0.2 points each)
|
|
- federal reserve, fed, inflation, interest rates
|
|
- dollar, usd, monetary policy, central bank
|
|
- jerome powell, treasury, bonds
|
|
|
|
### Context Relevance Keywords (0.1 points each)
|
|
- geopolitics, war, sanctions, recession
|
|
- crisis, safe haven, risk off, uncertainty
|
|
|
|
**Minimum Threshold**: Articles with relevance score < 0.3 are filtered out
|
|
|
|
## Sentiment Analysis Details
|
|
|
|
Uses TextBlob for natural language processing:
|
|
|
|
**Polarity Score Calculation:**
|
|
- Range: -1.0 (most negative) to +1.0 (most positive)
|
|
- Analyzes: Title + Description + Summary
|
|
|
|
**Classification:**
|
|
- **POSITIVE**: polarity > 0.1 → Bullish for gold
|
|
- **NEGATIVE**: polarity < -0.1 → Bearish for gold
|
|
- **NEUTRAL**: -0.1 ≤ polarity ≤ 0.1
|
|
|
|
**Note**: For gold as a safe-haven asset, negative news (recession, crisis) often = positive for gold prices.
|
|
|
|
## Alert Configuration
|
|
|
|
### Customizable Thresholds
|
|
|
|
In `backend/app/config.py`:
|
|
|
|
```python
|
|
# Price change threshold for alerts (percentage)
|
|
PRICE_ALERT_THRESHOLD: float = 1.0
|
|
|
|
# News refresh interval (seconds)
|
|
NEWS_REFRESH_INTERVAL: int = 300 # 5 minutes
|
|
```
|
|
|
|
### Support/Resistance Levels
|
|
|
|
Set via AI analysis or manually:
|
|
|
|
```python
|
|
from app.services.alert_service import alert_service
|
|
|
|
alert_service.set_support_resistance(
|
|
support=[4000, 3950, 3900],
|
|
resistance=[4100, 4150, 4200]
|
|
)
|
|
```
|
|
|
|
## News-Price Correlation
|
|
|
|
The correlation analyzer:
|
|
|
|
1. **Captures news timestamp**
|
|
2. **Finds price before news** (within 1 hour)
|
|
3. **Finds price after news** (within 1 hour)
|
|
4. **Calculates price change**
|
|
5. **Determines correlation strength**:
|
|
- STRONG: |change| > 1.0%
|
|
- MODERATE: |change| > 0.5%
|
|
- WEAK: |change| ≤ 0.5%
|
|
|
|
## Best Practices
|
|
|
|
### For Scalpers (M1-M15 timeframes)
|
|
- Enable auto-refresh on news feed
|
|
- Filter for HIGH impact news only
|
|
- Watch for PRICE_SPIKE/DROP alerts
|
|
- Monitor volatility alerts during news releases
|
|
|
|
### For Swing Traders (H4-D1 timeframes)
|
|
- Review news feed 2-3x daily
|
|
- Focus on MONETARY_POLICY and GEOPOLITICS categories
|
|
- Monitor support/resistance breach alerts
|
|
- Track upcoming economic events
|
|
|
|
### Risk Management
|
|
- Reduce position size before high-impact events
|
|
- Set wider stops during high volatility periods
|
|
- Avoid trading during major news releases unless experienced
|
|
- Use correlation analysis to understand typical price reactions
|
|
|
|
## Troubleshooting
|
|
|
|
### "No news articles found"
|
|
- Check Alpha Vantage API key is valid
|
|
- Verify API hasn't hit daily limit (500 calls)
|
|
- Check internet connection
|
|
- Review backend logs for errors
|
|
|
|
### "Alerts not appearing"
|
|
- Ensure backend is running
|
|
- Check price data is updating
|
|
- Verify support/resistance levels are set (via AI analysis)
|
|
- Check browser console for errors
|
|
|
|
### "News sentiment seems incorrect"
|
|
- TextBlob uses general sentiment (not gold-specific)
|
|
- Negative news can be positive for gold (safe haven)
|
|
- Use category + impact rating for better context
|
|
- Review article manually if sentiment seems wrong
|
|
|
|
## API Rate Limits
|
|
|
|
### Alpha Vantage
|
|
- **Free tier**: 500 calls/day, 5 calls/minute
|
|
- **News endpoint**: Counts as 1 call
|
|
- **Tip**: Cache news for 5 minutes to reduce calls
|
|
|
|
### Finnhub (if configured)
|
|
- **Free tier**: 60 calls/minute
|
|
- **News endpoint**: 1 call
|
|
- **Generous limits** for development
|
|
|
|
### OpenRouter
|
|
- **No rate limits** (reasonable use)
|
|
- **Pay-per-use**: ~$0.01-0.05 per AI analysis
|
|
- **Very affordable** for news analysis
|
|
|
|
## Future Enhancements
|
|
|
|
- [ ] Real-time WebSocket news stream
|
|
- [ ] Custom alert rules builder
|
|
- [ ] Email/SMS alert notifications
|
|
- [ ] Historical news backtesting
|
|
- [ ] Machine learning sentiment models
|
|
- [ ] Economic calendar integration (Forex Factory, Investing.com)
|
|
- [ ] News event impact prediction
|
|
- [ ] Social media sentiment (Twitter/X gold mentions)
|
|
|
|
## Example Workflow
|
|
|
|
### Morning Routine
|
|
1. Open simulator
|
|
2. Review overnight news (filter: ALL)
|
|
3. Check critical alerts
|
|
4. Review economic calendar for today
|
|
5. Note high-impact events scheduled
|
|
|
|
### During Trading Session
|
|
1. Monitor alerts panel for price movements
|
|
2. Check news feed every 30-60 minutes
|
|
3. Watch for breaking news notifications
|
|
4. Adjust positions before scheduled events
|
|
|
|
### End of Day
|
|
1. Review news-price correlations
|
|
2. Analyze which news moved the market
|
|
3. Clear old alerts
|
|
4. Note patterns for future trading
|
|
|
|
---
|
|
|
|
**Remember**: News and alerts are decision support tools. Always verify information and maintain your own trading discipline. The simulator is for educational purposes only.
|