QuantPilot

English | 中文

QuantPilot is a local-first quantitative research and execution console. It keeps the product focused on strategy review, market context, backtesting, simulated/paper/live execution, and basic risk controls.

---

Safety Boundaries

• Supported runtime modes are simulated, paper, and live. simulated is the default.
• Live trading is off by default and multi-gated: it requires QUANTPILOT_TRADING_MODE=live, ALPACA_USE_PAPER=false, valid Alpaca credentials, and the explicit acknowledgement QUANTPILOT_LIVE_TRADING_ACK=I_UNDERSTAND_LIVE_TRADING_RISK. If any gate is missing, live execution remains disabled.
• Browser code must not hold broker secrets; credentials live only in the API gateway environment.
• Risk checks and the kill switch must be enforced before execution actions.
• QuantPilot is a research and execution console, not an unattended trading bot.

---

Quick Start

Prerequisites: Node.js >=20.19.0, npm >=10

npm install

npm run gateway    # API gateway -> http://localhost:8787
npm run dev        # Web console -> http://localhost:8080

Copy .env.example to .env when you need local overrides.

Variable	Purpose
VITE_REFRESH_MS	Frontend refresh interval, default 5000
VITE_TRADING_MODE	Browser runtime mode: simulated, paper, or live
VITE_API_BASE_URL	Absolute API gateway origin for hosted SPA builds; empty uses the local proxy
VITE_MARKET_DATA_PROVIDER	simulated, custom-http, or alpaca
VITE_MARKET_DATA_HTTP_URL	Required HTTP market data URL when using custom-http
VITE_BROKER_PROVIDER	simulated, custom-http, or alpaca
GATEWAY_PORT	API gateway port, default 8787
CORS_ORIGINS	Allowed frontend origins for the API gateway
RATE_LIMIT_WINDOW_MS	API gateway rate-limit window
RATE_LIMIT_MAX	API gateway request limit per window
QUANTPILOT_TRADING_MODE	API runtime mode: simulated, paper, or live
ALPACA_KEY_ID	Alpaca API key id (gateway only)
ALPACA_SECRET_KEY	Alpaca API secret (gateway only)
ALPACA_USE_PAPER	true (default) targets the paper endpoint; false targets live
QUANTPILOT_LIVE_TRADING_ACK	Must equal I_UNDERSTAND_LIVE_TRADING_RISK to enable live trading
BROKER_ADAPTER	Server broker adapter: simulated, custom-http, or alpaca
BROKER_UPSTREAM_URL	Server-only upstream URL required by the custom-http adapter
BROKER_UPSTREAM_API_KEY	Optional server-only API key for the custom broker
BROKER_UPSTREAM_AUTH_SCHEME	Custom broker auth scheme, default Bearer

Both remote browser providers call the unified /api/v1/broker gateway path. Local development reaches it through the same-origin proxy; hosted builds prepend VITE_API_BASE_URL. With VITE_BROKER_PROVIDER=custom-http, configure the upstream only on the server using BROKER_ADAPTER=custom-http and BROKER_UPSTREAM_*.

For production, Vercel hosts the SPA from apps/web/dist while the Node.js API gateway runs as a separate service. Set VITE_API_BASE_URL for the hosted build; local development leaves it empty and proxies /api/v1 to port 8787.

---

Core Capabilities

Domain	Scope
Dashboard	Runtime status, account summary, key warnings
Market	Simulated, custom-http, or Alpaca market data overview
Trading	Unified desk for market monitoring, charting, and order entry
Strategies	Small strategy catalog and detail view
Backtest	Backtest specs, runs, result panels, costs and slippage
Execution	Simulated, paper, or live plans, orders, positions and event log
Risk	Basic limits, risk state and kill switch
Settings	Runtime/provider status, risk parameters, language and theme

Architecture

quantpilot/
├── apps/
│   ├── web/      React 18 SPA (Vite, vanilla-extract)
│   └── api/      Node.js API gateway (Alpaca + custom-http brokers)
├── packages/
│   ├── trading-engine/        Backtest, risk, execution and strategy core
│   ├── shared-types/          Core cross-package contracts
│   └── ui/                    Shared vanilla-extract UI components
├── docs/
│   ├── architecture/
│   ├── archive/
│   ├── superpowers/
│   ├── deployment.md
│   ├── integrations.md
│   └── operations-handbook.md
├── e2e/                       Playwright end-to-end specs
└── scripts/

Further reading: Project Structure | Integrations | Operations Handbook | Deployment Guide | Contributing

---

Development

npm run dev                 # Vite dev server (npm start is an alias)
npm run gateway             # API gateway
npm run preview             # Preview the production build

npm run test:web            # Vitest frontend tests
npm run test:api            # API tests
npm run test:engine         # Trading engine tests
npm run test:e2e            # Playwright end-to-end tests (installs Chromium on first run)

End-to-end tests run against the live dev server and gateway; install the browser once with npx playwright install chromium. See Contributing for details.

npm run typecheck
npm run build
npm run verify

verify runs all checks, tests, typecheck, build, and the e2e suite. The pre-push hook runs verify automatically.

---

License

MIT