foxhunt/PAPER_TRADING_QUICK_REFERENCE.md

Paper Trading - Quick Reference

The Bottom Line

Paper trading IS IMPLEMENTED and ACTIVELY RUNNING. Not planned. Not TODO. Production code.

Key Facts

Question	Answer
Is paper trading implemented?	YES - 719 lines of production code
Does it execute orders?	YES - Without real broker, simulated in DB
Can it track positions?	YES - HashMap-based real-time tracking
Does it calculate P&L?	PARTIALLY - Schema ready, execution tracking works
Is it integrated with ML?	YES - Consumes ensemble_predictions table
Can it run without broker?	YES - Entirely simulated, no API calls needed
Is it running right now?	YES - Spawned at service startup as background task
Test coverage?	YES - 1,075 lines of integration tests (10 scenarios)

What It Does

1. Polls database every 100ms - Checks ensemble_predictions table for new predictions
2. Filters predictions - Only processes high-confidence (≥60%) BUY/SELL signals
3. Creates simulated orders - Inserts into orders table with immediate fill
4. Links to predictions - Sets ensemble_predictions.order_id to track execution
5. Tracks positions - Maintains in-memory HashMap of open positions
6. Enforces risk limits - Validates symbols, position counts, confidence levels

Configuration

All configurable via environment variables (defaults work out of box):

PAPER_TRADING_ENABLED=true                          # Enable/disable
PAPER_TRADING_MIN_CONFIDENCE=0.60                   # 60% minimum
PAPER_TRADING_POLL_INTERVAL_MS=100                  # Check every 100ms
PAPER_TRADING_MAX_POSITION_SIZE=10000.0             # $10K max per position
PAPER_TRADING_ALLOWED_SYMBOLS="ES.FUT,NQ.FUT,ZN.FUT,6E.FUT"
PAPER_TRADING_ACCOUNT_ID="paper_trading_001"
PAPER_TRADING_INITIAL_CAPITAL=100000.0              # $100K starting capital
PAPER_TRADING_BATCH_SIZE=100                        # Process 100 per cycle

How to Run It

# 1. Start services
docker-compose up -d

# 2. Run migrations
cargo sqlx migrate run

# 3. Start trading service (paper trading runs automatically)
cargo run -p trading_service

# 4. Insert test predictions
psql postgresql://foxhunt:foxhunt_dev_password@localhost:5432/foxhunt << SQL
INSERT INTO ensemble_predictions (symbol, ensemble_action, ensemble_signal, ensemble_confidence, disagreement_rate)
VALUES ('ES.FUT', 'BUY', 0.75, 0.85, 0.10);
SQL

# 5. Check orders created within ~100ms
SELECT * FROM orders WHERE account_id = 'paper_trading_001';

Current Limitations (Phase 1)

• Position size is fixed (1 contract) - not confidence-scaled yet
• Prices are hardcoded per symbol - no real-time updates
• No P&L updates after trade - simulated fills only
• Positions don't close - no exit signals yet

What Works Perfectly

• Prediction consumption and filtering
• Order creation without broker
• Position tracking and risk limits
• Error handling (exponential backoff + circuit breaker)
• Concurrent execution (no race conditions)
• Integration with ML predictions

Files

Core Code:

• services/trading_service/src/paper_trading_executor.rs (719 lines)

Tests:

• services/trading_service/tests/paper_trading_executor_tests.rs (1,075 lines)
• services/trading_service/tests/paper_trading_ml_integration_test.rs (500 lines)

Database:

• migrations/022_create_ensemble_tables.sql

Test Coverage

10 comprehensive test scenarios:

1. ✅ Fetch pending predictions (filtering works)
2. ✅ Prediction to order conversion (BUY→buy enum)
3. ✅ Order creation SQL (INSERT works)
4. ✅ Position tracking (HashMap management)
5. ✅ Invalid symbol error handling
6. ✅ Low confidence rejection
7. ✅ Position limit enforcement
8. ✅ Polling interval timing
9. ✅ Concurrent execution (no duplicates)
10. ✅ End-to-end execute cycle

Next Phase (Future)

• Confidence-based position sizing
• Dynamic price updates from market data
• P&L calculation on trade close
• Volatility-adjusted position sizing (Kelly Criterion)
• Real broker integration (optional)

---

TL;DR: Paper trading works. ML predictions are converted to simulated orders. Positions are tracked. It's running right now in the background.