robinhood/docs/SIMULATED_FEED_GUIDE.md

# Simulated Live Price Feed - No API Keys Required! 🎉

## Overview

The gold trading simulator now uses a **fully simulated price feed** that requires **NO external API calls** and **NO API keys**! 

### ✅ What Changed

- **Before**: Required Alpha Vantage API key, hit rate limits, slow responses
- **After**: Self-contained simulator with instant responses, no limits, no costs

## Features

### 🎯 Realistic Price Simulation

The `GoldPriceSimulator` class provides:

- **Geometric Brownian Motion**: Realistic random walk price movements
- **Trend Simulation**: Periods of uptrends and downtrends
- **Mean Reversion**: Prices naturally gravitate toward base price
- **Volatility**: Configurable price volatility (default 0.08% per tick)
- **Smooth Continuity**: Prices evolve continuously, not randomly jumping

### 📊 Generated Data

1. **Historical Data**: Generate any amount of historical OHLC candles
   - Daily, hourly, or intraday intervals (1min, 5min, 15min, 30min, 60min)
   - 100 or 500 data points
   - Fully deterministic yet realistic

2. **Live Price Feed**: Real-time simulated price ticks
   - Updates continuously based on simulator state
   - Aligned to selected timeframe intervals
   - Always provides timestamps newer than historical data

3. **Current Price**: Instant spot price
   - Evolves using Brownian motion
   - Includes 24h high/low/change calculations

## How It Works

### Price Evolution

```
Current Price = Previous Price + (Drift + Random Shock + Trend + Mean Reversion)
```

- **Drift**: Slight upward bias (0.001%)
- **Random Shock**: Gaussian noise scaled by volatility
- **Trend**: Periodic directional movement (changes every 50-200 ticks)
- **Mean Reversion**: Pulls price back toward base (prevents runaway prices)

### Bounds

Prices stay within 80-120% of the base price (currently $2,650/oz):
- **Min**: $2,120
- **Max**: $3,180

This prevents unrealistic price explosions while allowing meaningful movements.

## API Endpoints

### 1. Current Price
```bash
GET /api/market/gold/current
```

Returns current spot price with 24h stats - **NO API KEY NEEDED**

Response:
```json
{
  "symbol": "XAU/USD",
  "price": 2658.42,
  "change": 12.50,
  "change_percent": 0.47,
  "high_24h": 2665.80,
  "low_24h": 2640.15,
  "volume": 0.0
}
```

### 2. Historical Data
```bash
GET /api/market/gold/history?interval=5min&output_size=compact
```

Parameters:
- `interval`: `daily`, `1min`, `5min`, `15min`, `30min`, `60min`
- `output_size`: `compact` (100 points) or `full` (500 points)

Returns array of OHLC candles - **INSTANT RESPONSE, NO RATE LIMITS**

### 3. Live Price Feed
```bash
GET /api/market/gold/live?interval=5min
```

Parameters:
- `interval`: Matches your chart timeframe (`1min`, `5min`, etc.)

Returns single live candle with timestamp aligned to interval - **UPDATES EVERY REQUEST**

## Starting the Backend

### Method 1: Using the startup script
```bash
cd backend
./start.sh
```

### Method 2: Manual start
```bash
cd backend
source ../.venv/bin/activate
PYTHONPATH=$(pwd) python -m uvicorn app.main:app --reload --port 8000
```

### Method 3: Docker (if configured)
```bash
docker-compose up backend
```

## Configuration

### Adjusting Base Price

Edit `/backend/app/services/price_simulator.py`:

```python
# Change initial price (default: $2650/oz)
gold_simulator = GoldPriceSimulator(initial_price=2800.0)
```

### Adjusting Volatility

```python
self.volatility = 0.0008  # Default: 0.08% per tick
# Increase for more volatile prices:
self.volatility = 0.0015  # 0.15% per tick
```

### Adjusting Trend Behavior

```python
self.max_trend_duration = 100  # Ticks before trend change
self.trend_strength = 0.0001   # Strength of trends
```

## Frontend Integration

The frontend automatically uses the simulated feed:

1. **Historical data loads** on chart mount
2. **Live updates poll** every 10 seconds (only for intraday timeframes)
3. **Timestamps are validated** to prevent conflicts
4. **No configuration needed** - it just works!

### Live Update Behavior

- **Daily/Weekly views**: Live updates **disabled** (historical data only)
- **Intraday views** (1min-60min): Live updates **enabled** with green badge
- **Timeframe switching**: Seamlessly transitions between modes

## Advantages

### ✅ No External Dependencies
- No API keys to configure
- No rate limits to worry about
- No network latency
- No third-party service downtime

### ✅ Perfect for Development
- Instant responses
- Predictable behavior
- Easy to test
- No costs

### ✅ Realistic Data
- Smooth price movements
- Trending behavior
- Mean reversion
- Proper OHLC candles

### ✅ Production Ready
- Stateful simulator (prices evolve continuously)
- Thread-safe implementation
- Configurable parameters
- Extensible architecture

## Future Enhancements

- [ ] Save/load simulator state for consistent sessions
- [ ] Add major economic events that impact price
- [ ] Implement weekend/holiday price gaps
- [ ] Add correlation with other assets (USD index, S&P 500)
- [ ] Configurable volatility regimes (calm vs volatile periods)
- [ ] News-driven price shocks
- [ ] User-adjustable parameters via API

## Testing

Test all endpoints:

```bash
# Current price
curl "http://localhost:8000/api/market/gold/current"

# Historical data (daily)
curl "http://localhost:8000/api/market/gold/history?interval=daily&output_size=compact"

# Historical data (5min intraday)
curl "http://localhost:8000/api/market/gold/history?interval=5min&output_size=compact"

# Live price feed (1min)
curl "http://localhost:8000/api/market/gold/live?interval=1min"

# Live price feed (5min)
curl "http://localhost:8000/api/market/gold/live?interval=5min"
```

All should return instant responses with realistic gold prices!

## Summary

🎉 **You now have a fully functional simulated live price feed!**

- ✅ No API keys required
- ✅ No rate limits
- ✅ Instant responses
- ✅ Realistic price behavior
- ✅ Works for all timeframes
- ✅ Live updates every 10 seconds
- ✅ Production ready

Just start the backend and frontend - everything works out of the box!