A full-stack paper trading platform with Python Flask backend and Next.js frontend. Practice stock trading with virtual money and real market data from Yahoo Finance!

• 🎯 Real-time Stock Quotes: Live market data using Yahoo Finance API
• 🔄 Auto-refresh Market Data: Prices update automatically every second (toggleable)
• 💼 Portfolio Management: Track your holdings with live P&L updates
• 📊 Modern UI: Beautiful dark-themed interface built with Next.js 14 and TailwindCSS
• 💰 Virtual Trading: Start with $100,000 virtual cash
• 📜 Transaction History: Complete audit trail of all trades
• 📈 Live Profit/Loss: Real-time tracking of gains and losses
• ⚡ Fast & Responsive: Optimized with React Context for efficient data fetching
• 🎨 Beautiful Components: Lucide icons and modern card-based design

• Backend: Flask (REST API)
• Frontend: Next.js 14, React, TypeScript, TailwindCSS
• Database: SQLite
• Market Data: Yahoo Finance API
• Icons: Lucide React

• Python 3.8+ with pip
• Node.js 18+ with npm
• Git (optional, for cloning)

1. Navigate to project directory:

cd paper-trade

2. Create and activate virtual environment:

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install Python dependencies:

pip install -r requirements.txt

4. Initialize database:

cd backend
python init_db.py
cd ..

1. Install Node dependencies:

cd web
npm install
cd ..

You need to run both servers simultaneously in separate terminals.

# Activate virtual environment (if not already active)
source venv/bin/activate

# Navigate to backend directory
cd backend

# Run Flask server
python app.py

✅ Backend runs on http://localhost:5000

# Navigate to frontend directory
cd web

# Run Next.js development server
npm run dev

✅ Frontend runs on http://localhost:3000

# Terminal 1
cd backend && source ../venv/bin/activate && python app.py

# Terminal 2 (new terminal)
cd web && npm run dev

Then open http://localhost:3000 in your browser! 🎉

The application displays everything on a single dashboard:

• Portfolio Summary at the top (cash balance, portfolio value, total P&L)
• Trading Panel on the left to execute trades
• Portfolio Holdings on the right showing your positions
• Transaction History at the bottom

1. In the Trading Panel, enter a stock symbol (e.g., AAPL, GOOGL, TSLA)
2. Click Search to load real-time price data
3. Choose Buy or Sell
4. Enter the number of shares
5. Review the total cost/proceeds
6. Click Execute Trade

• Stock prices in your portfolio update automatically every second
• Click the ⏸️ Pause button in the trading panel to stop live updates
• Click ▶️ Resume to restart live price updates
• This helps you track real-time profit/loss on your positions

Your holdings are displayed with:

• Current stock price (live updating)
• Number of shares owned
• Average purchase price
• Current value
• Profit/Loss ($ and %)
• Color-coded gains (green) and losses (red)

Scroll to the bottom to see:

• All past buy and sell transactions
• Transaction date and time
• Stock symbol and company name
• Number of shares traded
• Price per share
• Total transaction value
• Transaction type (BUY/SELL)

• Click the Reset Account button in the header
• Confirm the reset
• Your account will be restored to $100,000 cash
• All holdings and transaction history will be cleared

The Flask backend provides the following REST API endpoints:

• GET /api/portfolio - Get all holdings and cash balance
• GET /api/portfolio/balance - Get cash balance only
• GET /api/portfolio/<symbol> - Get specific holding

• POST /api/trades - Execute a trade (buy/sell)
  • Body: { "symbol": "AAPL", "type": "buy", "shares": 10, "price": 150.00 }
• GET /api/trades/history - Get transaction history (optional ?limit=50)

• GET /api/market/quote/<symbol> - Get real-time stock quote
• GET /api/market/chart/<symbol>?range=1mo - Get historical chart data
  • Range options: 1d, 5d, 1mo, 3mo, 6mo, 1y, 5y

• POST /api/reset - Reset account to initial state ($100,000)
• GET /api/health - Health check endpoint

paper-trade/
├── backend/
│   ├── app.py              # Flask API server with market data endpoints
│   ├── init_db.py          # Database initialization script
│   └── trading.db          # SQLite database (auto-created)
├── web/                    # Next.js frontend
│   ├── src/
│   │   ├── app/
│   │   │   └── page.tsx    # Main dashboard page
│   │   ├── components/     # React components
│   │   │   ├── PortfolioSummary.tsx
│   │   │   ├── PortfolioHoldings.tsx
│   │   │   ├── TradingPanel.tsx
│   │   │   └── TransactionHistory.tsx
│   │   ├── contexts/
│   │   │   └── MarketDataContext.tsx  # Centralized market data state
│   │   └── lib/
│   │       ├── api.ts      # API client functions
│   │       └── market.ts   # Market data functions
│   ├── package.json        # Node dependencies
│   └── tailwind.config.ts  # TailwindCSS config
├── requirements.txt        # Python dependencies
└── README.md              # This file

• id: Primary key
• symbol: Stock symbol
• shares: Number of shares owned
• avg_price: Average purchase price
• created_at: Creation timestamp
• updated_at: Last update timestamp

• id: Primary key
• symbol: Stock symbol
• type: 'buy' or 'sell'
• shares: Number of shares
• price: Price per share
• total: Total transaction value
• created_at: Transaction timestamp

• id: Primary key (always 1)
• cash_balance: Available cash
• updated_at: Last update timestamp

• Free Market Data: Uses Yahoo Finance API (yfinance) which is free and doesn't require an API key
• Educational Purpose: This is for learning and practice only - no real money involved
• Data Delays: Market data may have slight delays (typically 15-20 minutes for US markets)
• No Authentication: Single-user application (no login required)
• CORS Enabled: Frontend and backend communicate across different ports
• Live Updates: MarketDataContext uses React Context + useRef pattern for efficient real-time updates

• React Context Pattern: Centralized market data management with MarketDataContext
• useRef Hook: Solves closure issues in setInterval for always-fresh symbol lists
• Optimistic Updates: Immediate UI feedback before API confirmation
• CORS Configuration: Proper cross-origin setup for local development
• TypeScript: Full type safety in the frontend
• Responsive Design: TailwindCSS with mobile-first approach
• Error Handling: Graceful fallbacks for API failures

MIT License - Feel free to use and modify for your own projects!

Contributions are welcome! Feel free to:

• Open issues for bugs or feature requests
• Submit pull requests with improvements
• Share feedback and suggestions

Built with ❤️ using Flask, Next.js, and React