Paper Trading Platform

Self-hosted paper trading workspace with a Next.js dashboard, simulated order fills, portfolio tracking, watchlists, alerts, live-brokerage integration hooks, and an MCP server for agent access.

Current project progress

Workspace

• apps/web — Next.js app, REST API routes, Prisma schema, trading services, and Vitest coverage.
• packages/mcp-server — MCP stdio/Streamable HTTP server backed by the platform API.
• docker-compose.yml — local PostgreSQL for development.
• docker-compose.prod.yml — production-oriented app + PostgreSQL compose file.

Prerequisites

• Node.js >=20
• pnpm >=9
• Docker Desktop or another Compose-compatible runtime
• Polygon API key for live market data
• SnapTrade credentials only when live brokerage mode is enabled

Local Setup

pnpm install
Copy-Item .env.example .env.local
docker compose up -d postgres
pnpm --filter web db:push
pnpm --filter web dev

Open http://localhost:3000.

Demo Account

• Email: demo@app.com
• Password: letmein@123

Environment

Required for local development:

• DATABASE_URL — PostgreSQL connection string.
• AUTH_SECRET — generated with openssl rand -base64 32.
• AUTH_URL — local app URL, usually http://localhost:3000.
• POLYGON_API_KEY — market data provider key.

Required for MCP:

• TRADING_API_URL — API base URL, usually http://localhost:3000/api/v1.
• TRADING_API_KEY — API key issued from the dashboard.
• MCP_HTTP_PORT — HTTP transport port when running --transport http.

Common Commands

pnpm --filter web test
pnpm --filter web type-check
pnpm --filter @paper-trading/mcp-server test
pnpm --filter @paper-trading/mcp-server build
pnpm build

See docs/testing.md for lifecycle coverage and the manual E2E smoke test.

Docker Compose Deployment

Copy-Item .env.production.example .env.production
# Edit .env.production with production secrets and URLs.
docker compose -f docker-compose.prod.yml --env-file .env.production up -d --build

The production Compose stack runs PostgreSQL, applies Prisma migrations, starts the standalone Next.js app, and exposes a health check at /api/health. See docs/deployment.md for deployment commands and required environment variables.

MCP Server

pnpm --filter @paper-trading/mcp-server dev
pnpm --filter @paper-trading/mcp-server dev -- --transport http --port 3001

The server requires TRADING_API_KEY and calls the platform API using bearer authentication.