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

GET /api/market/gold/current

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

Response:

{
  "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

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

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

cd backend
./start.sh

Method 2: Manual start

cd backend
source ../.venv/bin/activate
PYTHONPATH=$(pwd) python -m uvicorn app.main:app --reload --port 8000

Method 3: Docker (if configured)

docker-compose up backend

Configuration

Adjusting Base Price

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

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

Adjusting Volatility

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

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:

# 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!