PaperTrade — Virtual Stock Trading Simulator

A full-stack virtual stock trading platform where users trade real US stocks with $100,000 virtual cash, watch live prices update in real time, and track their portfolio performance.

---

Features

• JWT Authentication — signup/login with bcrypt password hashing
• Live Price Streaming — Socket.io pushes real-time price updates to the Watchlist every 12 seconds without page refresh
• Trade Execution — buy/sell US stocks with average-cost-basis tracking and realized/unrealized P&L calculations
• Smart Caching — MongoDB TTL cache layer reduces redundant Finnhub API calls by ~95% within 30-second windows
• Scheduled Jobs — node-cron revalues all portfolios every 15 minutes and updates leaderboard rankings
• Markets Dashboard — browse Top Movers, Most Watched, and Technology sectors with live prices and sparkline charts
• Trade History — paginated log of all trades with realized P&L per transaction

---

Tech Stack

Layer	Technology
Frontend	AngularJS 1.x, Chart.js
Backend	Node.js, Express
Database	MongoDB (Mongoose)
Real-time	Socket.io
Market Data	Finnhub API
Scheduler	node-cron
Auth	JWT, bcrypt

---

Getting Started

Prerequisites

• Node.js 18+
• MongoDB (local) or MongoDB Atlas (free)
• Finnhub API key — free at finnhub.io (optional — mock data works without it)

Installation

git clone https://github.com/your-username/papertrade.git
cd papertrade/backend
npm install

Configuration

cp .env.example .env

Fill in .env:

PORT=3000
MONGODB_URI=mongodb://localhost:27017/papertrade
JWT_SECRET=your_random_secret_here
FINNHUB_API_KEY=your_key_here
STARTING_BALANCE=100000
PRICE_CACHE_TTL_SECONDS=30
CRON_INTERVAL_MINUTES=15

Run

# Start MongoDB
mongod --dbpath ~/mongodb-data

# Start the app (in a new terminal)
cd papertrade/backend
npm start

Open http://localhost:3000

---

Architecture

AngularJS SPA  <── REST API ──>  Node.js + Express
      |                                   |
Socket.io (live prices)          MongoDB (Mongoose)
                                          |
                                  Finnhub API (market data)
                                  node-cron (portfolio revaluation)

---

API Reference

Auth

Method	Endpoint	Description
POST	/api/auth/signup	Create account, returns JWT
POST	/api/auth/login	Login, returns JWT

Stocks

Method	Endpoint	Description
GET	/api/stocks/:symbol/quote	Live price with cache
GET	/api/stocks/:symbol/history	Historical OHLCV data
GET	/api/stocks/search?q=apple	Symbol/company search
GET	/api/stocks/multi?symbols=AAPL,MSFT	Batch quotes

Trading

Method	Endpoint	Description
POST	/api/trades/buy	Execute buy order
POST	/api/trades/sell	Execute sell order
GET	/api/trades/portfolio	Holdings with live P&L
GET	/api/trades/transactions	Paginated trade history

---

Deployment

MongoDB Atlas + Render (both free tier):

1. Create a free cluster at cloud.mongodb.com and copy the connection string
2. Push this repo to GitHub
3. Create a new Web Service on render.com pointing to your repo
4. Set root directory to backend/, build command npm install, start command npm start
5. Add all .env variables in the Render dashboard