PaperTradeX

A batteries-included, multi-market paper trading platform: sign up with email verification, trade A-shares / Hong Kong / US stocks, Chinese futures and crypto with realistic market rules, and manage everything from a full admin console. Single-process Node.js + SQLite — no external database, one server is all you need.

| Feature | Details | | --- | --- | | 5 markets, live quotes | CN A-shares, Hong Kong, US, Chinese futures, crypto; public quote feeds (Tencent/Sina with configurable primary/backup, crypto falls back OKX → Gate → CoinGecko), optional HTTP proxy | | 4 trading modes | Spot, margin trading (financing & short selling), futures, crypto perpetual contracts (isolated/leveraged) | | Realistic rules | Trading sessions / price limits / T+1 / fees / margin / liquidation modeled after real market rules, 5-second settlement loop | | Bilingual UI | English (default) and Chinese, switchable at runtime; all backend messages are error-coded and localized | | Dark mode | Light/dark theme toggle, persisted per browser, charts included | | Admin console | Separate /admin entry: user management, balance adjustments, SMTP / fees / leverage / market-source / proxy configuration, test email | | User side | 1,000,000 simulated cash on sign-up; quotes, orders, positions, statements, leaderboard, WebSocket push |

Market Realism

Rules are modeled as close to the real markets as free public data sources allow. Everything below is tunable in the admin console:

Orders & Execution

• Day orders: limit orders on stocks/futures expire at market close (frozen funds auto-refunded on daily rollover); crypto orders are GTC.
• Price improvement: limit orders fill at the better of current price vs. limit price.
• Tick size: CN 0.01, HKEX tiered spread table, US 0.01/0.0001, per-product ticks for futures, Gate precision for crypto.
• Tiered slippage: market orders slip by notional-value tier (defaults 5/10/20 bp).

Stocks

• CN price limits (main board ±10%, ChiNext/STAR ±20%, ST ±5%, new listings with the N prefix ±44% on debut), T+1, board-lot buying.
• Suspension detection: suspended/delisted symbols are blocked from trading, matching and liquidation.
• HK board lots pulled live from quotes (e.g. Xiaomi 200 shares/lot, HSBC 400).
• Dividends & splits: on ex-dividend dates cash dividends are credited, bonus/converted shares added, and cost basis diluted automatically (EastMoney corporate-action feed).
• Call auction: CN stocks 9:15–9:25 and futures 8:55–9:00 accept limit orders only.

Futures

• Per-product parameters for 69 Chinese futures products: margin rate, price limit, tick size, per-lot fee (index futures charged by notional), night session end, delivery rule (data as of 2026-07, approximations, admin-tunable).
• Mark-to-market: daily settlement moves floating P&L to cash and recomputes margin; margin calls are pushed when equity runs short.
• Night sessions per product (non-ferrous/precious metals to 01:00/02:30 next day, ferrous/energy to 23:00), intraday close fees (index futures penalty), expiry delivery (commodities mid-month, index futures 3rd Friday, treasury futures 2nd Friday).

Margin Trading (real margin model)

• Financing requires 80% own funds (1.25× leverage), short selling 50%; standard maintenance-ratio formula; open at 300% / margin call at 150% / liquidation at 130%; separate interest tracks for financing and short borrowing.

Crypto Perpetuals

• Funding fees settled at 00:00/08:00/16:00 Beijing time (live Gate funding rates, longs pay shorts).
• Mark price = median of the last 5 quotes (anti price-spike); liquidations and liq-price display both use mark price.
• Tiered maintenance margin by position notional (defaults ≤50k USDT 0.5% / ≤250k 1% / >250k 2%).

FX

• Non-CNY instruments convert at live FX rates with an optional conversion spread (default 0; buy side pays up, sell side receives less).

Quick Start (one command)

npx papertrade-x

This downloads the package, generates a .env with a random JWT secret and a random admin password (printed once to the console), creates the data/ directory in your current folder, and starts the server on port 8080 (--port 9000 to change).

Deploy from Source

Requirements: Node.js ≥ 18 (Windows/Linux). Quote sources are reachable directly from mainland China; crypto sources degrade automatically (an HTTP proxy can be configured in the admin console if needed).

# 1. Copy .env.example to .env and change JWT_SECRET and ADMIN_INITIAL_PASSWORD
cp .env.example .env

# 2. Install and build the frontend
npm install
npm run build

# 3. Start
node server.js
# or keep it alive with pm2:
npm i -g pm2
pm2 start ecosystem.config.js

.env variables:

| Variable | Description | Default | | --- | --- | --- | | PORT | HTTP port | 8080 | | JWT_SECRET | Token signing secret, must be changed | please-change-me | | ADMIN_INITIAL_PASSWORD | Initial admin password (seeded on first boot) | admin123456 | | DATA_DIR | SQLite data directory | ./data |

First-time Setup (admin console)

1. Open http://your-server:8080/admin
2. Log in with the initial password → you will be forced to change it
3. Configure SMTP under System Settings (required for sign-up verification emails)
4. Click Send test email to verify
5. (Optional) configure an HTTP proxy if crypto quotes cannot connect directly

User Flow

Sign up (email verification) → receive 1,000,000 simulated cash → browse quotes → place orders → track positions/statements → compete on the leaderboard.

Backup & Restore

All data lives in the data/ directory (single SQLite file + WAL):

• Backup: copy the whole data/ directory (safe while running)
• Restore: stop the server, replace data/, restart

FAQ

| Question | Answer | | --- | --- | | How do I change the port? | Edit PORT in .env and restart, or pass --port to npx papertrade-x | | What does "market data interrupted" mean? | A quote source failed repeatedly and tripped the circuit breaker; it recovers automatically. For crypto you can configure a proxy or wait for source fallback | | HK/US quotes look delayed? | Public feeds provide delayed quotes for HK/US — expected behavior | | better-sqlite3 fails to install | A local build toolchain is required: Visual Studio Build Tools (C++ workload) on Windows, python3 make g++ on Linux | | Forgot the admin password | Stop the server, run node -e "require('./src/db').open(); require('./src/db').get().prepare('DELETE FROM admin').run()", restart — the initial password from .env is re-seeded |

Disclaimer

This project is for paper-trading practice and education only. It is not investment advice. Quotes come from public feeds and may be delayed or inaccurate.

License

MIT