PanWatch

PanWatch — Self-hosted AI stock monitoring

English | 简体中文

Monitor A-shares, Hong Kong, and U.S. stocks, manage your portfolios, and research ideas with TradingAgents. Self-host PanWatch with your preferred OpenAI-compatible provider or local models through Ollama.

Feature overview · Core features · Quick start · Reference · Support · Contributing

🧠 Start from a portfolio holding → let a nine-agent TradingAgents research team analyze it → follow the bull/bear debate and risk review → receive a PM decision memo and the complete reasoning trail in your messaging app within 3–5 minutes.

📸 Feature Overview

The screenshots below use the English interface; Simplified Chinese is available throughout the same product surfaces.

Portfolio · Multi-account overview	Opportunities · AI-scored ideas
Paper trading · Equity curve and performance	Deep stock analysis
Technical confluence · MACD/RSI/KDJ at a glance	Price alerts · Combined conditions

Mobile screenshots

📱 PanWatch is an installable PWA and can be added to your mobile home screen like a native app.

💡 If PanWatch is useful to you, please consider giving the project a ⭐ Star. It is the best way to support the project and help more people discover it.

Core Features

Stock and listed ETF search, watchlists, holdings, price alerts, quotes and candlesticks share the same workflow across mainland China, Hong Kong and US markets. Search by code or name (for example, 510300, 159915, 02800 or SPY). The asset type is saved with each instrument; select ETF for funds whose provider name does not identify them as ETFs.

ETF deep analysis uses fund-specific context and does not substitute company financial statements. Fund holdings, NAV, fees and tracking error are not yet supplied as structured data. Paper trading continues to use its existing market rules and cost model; ETF-specific T+0 exceptions and fee schedules are not modeled.

Quick Start

docker run -d \
  --name panwatch \
  --restart unless-stopped \
  -e TZ=Asia/Shanghai \
  -p 8000:8000 \
  -v panwatch_data:/app/data \
  sunxiao0721/panwatch:latest

Open http://localhost:8000 and create your login credentials.

Set TZ explicitly for background schedules and notification quiet hours, for example -e TZ=UTC or -e TZ=America/New_York. The image defaults to Asia/Shanghai and does not detect the host timezone. Interface timestamps and alert expiry inputs use the browser timezone. Timezone policy

Initial setup

1. Open the web interface and create your login credentials.
2. The main tour opens on first sign-in and follows stocks, quotes, AI setup and a first analysis. Required steps cannot be skipped; you can pause and resume. Reopen it from the Guide center, which also offers opportunities, paper trading, assistant, daily tasks and data sources, each with saved progress and replay. Click highlighted controls directly. The main tour verifies saved actions or successful checks; exploration routes record instructions you acknowledge.
3. In the main tour, configure a service in Settings → AI Services, set the default model, and test the connection before explicitly generating your first analysis. This action uses your model quota; its result stays on the page.
4. Optionally create a price alert and test a notification channel. You can defer or resume the guide; progress survives browser changes and service restarts. A changed model or channel configuration needs a new successful test.
5. Enable scheduled agents or explore TradingAgents after the basics work. These are configured separately from the first analysis.

Docker Compose

services:
  panwatch:
    image: sunxiao0721/panwatch:latest
    container_name: panwatch
    environment:
      TZ: "Asia/Shanghai"
    ports:
      - "8000:8000"
    volumes:
      - panwatch_data:/app/data
    restart: unless-stopped

volumes:
  panwatch_data:

docker compose up -d

Change environment.TZ to your IANA timezone and run docker compose up -d to recreate the container. Review existing cron and quiet-hour wall times before changing it; the same 09:00 schedule will run at a different instant. Keep the data volume.

First startup and browser installation

The image includes Playwright's system dependencies. Chromium's headless shell for screenshots is downloaded on first startup into the mounted volume (default /app/data/playwright), which requires network access and can take a few minutes.

If you do not need browser features such as screenshots, set PLAYWRIGHT_SKIP_BROWSER_INSTALL=1 to skip this installation.

Reference

Scheduled agents and deep analysis

Schedules are configurable. Automatic runs filter exchange holidays before collection and analysis; intraday workflows also require an open trading session.

Select the brain icon beside a holding to start TradingAgents deep analysis. Four analyst roles feed a bull/bear debate, risk review, and portfolio-manager decision, with the reasoning trail available in the app and through configured notification channels. Runtime and cost depend on the selected models and configuration.

Deep-analysis flowchart · Backend architecture

Market calendars and scheduling

• Select the market status strip to compare all three exchanges across the next 14 dates. Opening/session times use your browser timezone; trade dates and status use each exchange's local date.
• A non-trading day shows closed; a completed trading day shows market closed. Beijing Saturday morning may still be New York Friday after close.
• Published 2026 closures and half-days are bundled locally. Startup warms only the previous 30 and next 90 days, without downloading full history. Unpublished weekdays show a pending calendar and block automatic execution; the bundled annual data must be updated for the next year.
• Agent Cron/interval settings remain unchanged; execution and schedule previews share calendar filters. Price alerts in “all day” mode still require a trading day.
• Paper fills require an open session for that stock's market. Paper notifications follow each exchange's local clock, including half-days and U.S. daylight-saving changes.
• Mainland China paper positions follow T+1 using the Shanghai purchase date: automatic and manual sells are blocked on the purchase date and allowed from the next trading day, without waiting 24 hours. Prices and unrealized P&L continue updating while locked; stop-loss, take-profit and other exit conditions are checked again when selling becomes available, using the then-current quote.
• Paper cash settlement is separate from sell eligibility: A shares settle T+1 and allow sale proceeds to fund new purchases immediately; HK (T+2) and US (T+1) use a cash account that only buys with settled, unreserved funds. The page shows cash balance, buying power, settled available cash and outstanding sale proceeds. Purchases reserve cash immediately; settlement changes availability without crediting cash or P&L again.
• Settlement dates use each market's local calendar. HK half-days are non-settlement days; US Columbus Day and Veterans Day also defer settlement even when stocks trade. The simulation releases funds at the start of the due date, rather than modeling intraday clearing batches, withdrawal cutoffs, margin, FX or broker-specific facilities. Existing balances are treated as settled opening funds; historical trades are not retroactively locked. Unknown future calendars keep new outstanding proceeds pending until calendar data is updated.
• Rule references: HKEX settlement and half-days, SEC T+1, DTC 2026 holidays.

Professional technical analysis

• Trend indicators: moving-average alignment, MACD crosses, and Bollinger Band breakouts.
• Momentum indicators: RSI overbought/oversold conditions and KDJ saturation or divergence.
• Price and volume: volume-ratio anomalies, low-volume pullbacks, and high-volume breakouts.
• Pattern recognition: hammer, engulfing, doji, and other candlestick patterns.
• Support and resistance: automatic calculation of multiple support and resistance levels.

Price alerts

• Combine price, percentage change, turnover, volume ratio, and other conditions with AND/OR logic.
• Limit rules to market hours or keep them active all day on trading days; configure cooldowns, daily trigger limits, and repeat behavior.
• Set an expiration date and HH:mm time in the rule dialog, or leave it empty so the rule never expires.
• Choose notification channels per rule, or use the system default when none is selected.

Environment variables

Local development

Requirements: Python 3.10+ / Node.js 24.14.0 / pnpm 9.15.9

# One-command development setup (recommended)
make dev-api          # Backend with automatic venv/dependencies on :8000
make dev-web          # Frontend with automatic pnpm install on :5183

# Or start each service manually
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt
python server.py                              # Backend on :8000

cd frontend && pnpm install && pnpm dev       # Frontend on :5183

The frontend development server runs at http://localhost:5183 and proxies /api to 127.0.0.1:8000.

Frontend UI conventions and checks

Technology stack

Backend: FastAPI / SQLAlchemy / APScheduler / OpenAI SDK

Frontend: React 18 / TypeScript / Tailwind CSS / shadcn/ui

OpenTelemetry export (optional and disabled by default)

PanWatch includes a built-in observability stack with structured logs, end-to-end trace_id correlation, the agent_runs table, and node-level TradingAgents progress and cost reporting. It works without any external service.

You can optionally add standard OpenTelemetry export and send traces to Jaeger, Tempo, Langfuse, or another compatible APM. PanWatch maps three types of spans:

• One agent run → a root span correlated with the trace_id from agent_runs.
• One LLM call → a gen_ai child span following the OpenTelemetry GenAI semantic conventions, including gen_ai.system, gen_ai.request.model, input/output token usage, and gen_ai.operation.name.
• One TradingAgents node → a child span that reuses the node-level progress callback.

Export is a complete no-op when the optional dependencies are not installed and no endpoint is configured.

Enable it in three steps:

# 1. Install the optional dependencies
pip install -r requirements-otel.txt

# 2. Configure your collector or APM endpoint
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
export OTEL_SERVICE_NAME=panwatch   # Optional; defaults to panwatch

# 3. Start PanWatch normally. The startup log will confirm that OTel export is enabled.
python server.py

Run a local Jaeger instance to verify the integration:

docker run -d --name jaeger -p 16686:16686 -p 4318:4318 \
  jaegertracing/all-in-one:latest
# Trigger an agent, open http://localhost:16686, and select service=panwatch.

Langfuse and Tempo work the same way: point OTEL_EXPORTER_OTLP_ENDPOINT to their OTLP endpoint.

Publishing Docker images

The repository includes a GitHub Actions release workflow:

• Pushing a tag such as 0.2.3 automatically builds and publishes:
  • sunxiao0721/panwatch:0.2.3
  • sunxiao0721/panwatch:latest
• The workflow can also be started manually with workflow_dispatch and an explicit version.

Configure these repository secrets before publishing:

• DOCKERHUB_USERNAME
• DOCKERHUB_TOKEN

Support the Project

Sponsorship

For sponsorship or partnership inquiries, contact sunxiaoyes@outlook.com.

Donations

PanWatch is free and open source. If it saves you time or improves your workflow, you can support continued development:

Alipay / WeChat Pay

Alipay	WeChat Pay

USDT

Binance Pay — scan with the Binance app:

On-chain USDT (TRC20) — scan with any TRON wallet:

Address: TKBV69B2AoU67p3vDhnJUbMJtZ1DxuUF5C

Contributing

Issues and pull requests are welcome. See the contribution guide for setup, validation, internationalization, custom agents, and market-data sources.

Community chat (Telegram): t.me/panwatch

License

MIT