CW Research Terminal
CW Research Terminal is a research workstation for Vietnamese covered warrants and their
underlying equities, combining realtime market monitoring, quantitative analytics,
historical research, and AI-assisted analysis.
▶ Live demo: https://cw-research-terminal.vercel.app — no account needed; the dashboard,
research, market data, quant analytics, and history are all fully public.
It is a personal project. Runtime market data comes from public Vnstock Community
KBS/VCI adapters plus the SSI iBoard WebSocket protocol documented by vnstock-js. It is
not affiliated with, sponsored by, or operated on behalf of those projects or providers.
What is a covered warrant?
A covered warrant (CW) is an exchange-listed option-like security issued by a securities
firm. A HOSE call CW gives the holder the right to buy a fixed underlying stock (e.g. HPG)
at a fixed exercise price by a fixed maturity, converted at a fixed ratio (e.g. 5:1 —
five warrants per share). Its price is driven by the underlying's price, time to maturity,
and volatility — so it is priced and risk-managed with a Black-Scholes-Merton model. This
terminal pairs each CW with its underlying and computes the standard analytics (theoretical
price, implied volatility, Greeks, moneyness, spread, days-to-expiry).
What it does
- Realtime market monitoring — live bid/ask/trade for a watchlist of covered warrants
and their underlyings, with normalized state, session-freshness protection, and warm-cache
recovery.
- Covered-warrant ↔ underlying comparison — side-by-side price/return context.
- Historical market research — PostgreSQL-first historical bars with charting.
- Quantitative analytics — Black-Scholes-Merton theoretical price, implied volatility
(bid/ask/trade/mid), analytical Greeks, HV_22 historical volatility, moneyness, spread,
days-to-expiry.
- AI-assisted analysis — an assistant that summarizes, explains, and compares the
current market/quant/history context (OpenRouter; optional).
- Optional accounts — Supabase Auth for a per-user server-persisted watchlist. The
dashboard, research, market data, quant, and history are all fully public without an
account.
Architecture (implemented)
REALTIME
SSI iBoard WebSocket + KBS recovery poll ─► VnstockProvider
─► MarketState (normalized bid/ask/trade)
─► Redis warm cache (L2 recovery) ─► FastAPI WebSocket (/ws/market) ─► React
LiveQuantEngine ◄─ market ticks ─► BSM / IV / Greeks / theo price ─► analytics patches ─► WS
HISTORICAL
history_read_service (PostgreSQL-first)
complete DB hit → 0 provider calls
legitimate in-horizon gap → 1 controlled, single-flighted Vnstock fill → persist
PostgresHistoricalBarSource → HistoricalVolatilityService (HV_22) → in-memory estimate → LiveQuantEngine
QUANT
market quote + contract terms (effective strike/ratio) ─► BSM / IV / Greeks / theo / HV ─► analytics
RESEARCH
market + history + quant context ─► research views ─► AI-assisted explanation / comparison / summarization
AUTH (optional)
Supabase Auth ─► JWT verified locally ─► /api/me/* only (user-specific persistence)
MarketDataProvider is a vendor-neutral abstraction (connect, set_subscriptions,
get_historical_bars, set_event_callback). The runtime implementation is
VnstockProvider; source changes stay behind this boundary and do not alter the
subscription planner, market-state pipeline, or quant engine.- Quant math is an independent implementation of public Black-Scholes-Merton pricing,
implied-volatility inversion, analytical Greeks, and the HV_22 window. HOSE covered
warrants are dividend-protected (the issuer adjusts strike/ratio on the ex-date), so the
analytics engine pins the BSM dividend yield
q = 0 — see
backend/app/quant/dividend_convention.py.
Design decisions
| Decision | Why |
|---|
MarketDataProvider abstraction | Vendor-neutral seam; the subscription planner, market-state pipeline and quant engine never import a vendor SDK. |
| One backend replica / one Uvicorn worker | The provider owns one SSI socket, the bounded recovery poller, and shared in-memory state; a second worker would duplicate upstream traffic and split process-local WS state. |
| PostgreSQL-first history | A complete DB hit makes zero provider calls; only a legitimate in-horizon gap triggers one controlled, advisory-locked, single-flighted fill, which is then persisted. |
| Redis warm state | L2 recovery of the latest canonical market snapshot across restarts/sessions, plus the distributed rate limiter (separate key prefixes). |
q = 0 dividend convention | CWs are dividend-protected via strike/ratio adjustment; a BSM q > 0 would double-count and underprice. |
| Adjusted stock history vs RAW CW history | Underlying HV is computed from corporate-action-adjusted closes (removes ex-date jumps from the volatility estimate); CW bars are stored RAW because CW terms are re-based on the ex-date, so there is nothing to adjust. |
Testing
Backend 1,500+ pytest cases (quant verification, provider lifecycle, ingestion /
history, auth, rate-limit / security, repo-hygiene) + frontend ~190 vitest cases,
tsc --noEmit, and pyright. Normal CI tests use captured provider fixtures and make no
live market-data request.
cd backend && .venv/bin/python -m pytest -q
cd frontend && npm test && npx tsc --noEmit && npm run build
The persistence tests spin up a disposable local PostgreSQL cluster and skip cleanly when
initdb / pg_ctl are not on PATH.
Production hosting
This is the beginning of the README. Read the rest at the original. Read the full README ↗
