(P1) CW Market Overview

Để xem toàn cảnh thị trường chứng quyền, tôi thiết lập hệ thống với dữ liệu thị trường được tải từ dữ liệu chứng quyền (CW) của SSI và VNDIRECT. Với dữ liệu bán hàng thì dựa trên ước lượng giao dịch tự doanh, còn với nội bộ sẽ đọc thông tin tồn kho nội bộ, tính IV / HV / GARCH, ghi vào Excel và dựng một file dashboard HTML. Bài viết mô tả các file, luồng chạy, vai trò từng file, cách lấy dữ liệu qua API, quá trình xây dựng và cách vận hành.

1. Tổng quan: nguồn → xử lý → đầu ra

Mọi con số mô tả cùng một phiên đã đóng (ngày as-of). Chạy trước 15:00 thì lấy phiên hôm trước. Nguồn nào chưa có dữ liệu ngày đó thì lùi một ngày làm việc, tối đa 7 ngày. Trong giờ giao dịch, chế độ Realtime cập nhật phần giá mỗi 5 phút (mục 4).

2. Ba chế độ chạy

3. Luồng chạy khi bấm Run

Thứ tự thực tế từ lúc bấm đúp tới lúc dashboard mở ra.

1. Bấm đúp file .bat (Run CW Market Overview.bat): chuyển về thư mục chứa file, bật UTF-8, gọi bước kiểm tra Python, rồi chạy main.py.
2. Kiểm tra Python (src/ensure_python.bat): tìm Python; nếu chưa có thì tự cài Python 3.12 và các thư viện. Sau đó main.py tự cài gói còn thiếu (pandas, arch, xlwings…).
3. Kiểm tra workbook (main.py): thiếu CW Market Overview.xlsx thì dừng ngay, báo “MISSING FILE”.
4. Pipeline 9 bước (bảng dưới).
5. Dựng dashboard (src/dashboard/build.py): làm mới file tồn kho trong Excel, tính dữ liệu cho 2 tab, ghép vào template.
6. In DONE và mở dashboard: cửa sổ dừng lại để đọc log; CW Dashboard.html tự mở.

4. Chế độ Realtime trong phiên

Bảng giá của SSI trong giờ giao dịch trả về giá khớp gần nhất, giá mua/bán tốt nhất và khối lượng / giá trị từ đầu phiên. Chế độ Realtime dùng chính các dữ liệu này, kết hợp với kết quả của lần chạy chốt ngày gần nhất.

1. Đọc ngày Sync gần nhất (từ data/pdt_cache.csv) và nạp các kết quả đã lưu của ngày đó: HV, tự doanh, thanh khoản, GARCH. Chưa có thì báo cần chạy Run CW Market Overview.bat trước.
2. Tải bảng CW và bảng VNALL của SSI (2 lần gọi API).
3. Chọn giá cho từng CW: giá khớp gần nhất → nếu chưa khớp trong ngày thì trung bình giá mua/bán tốt nhất → nếu không có thì giá tham chiếu. Cổ phiếu cơ sở: giá khớp, không có thì giá tham chiếu.
4. Tính lại bảng master bằng chính cw_processor.py: IV, delta, moneyness, breakeven, leverage, trạng thái, DTE tính từ hôm nay; giá trị giao dịch lấy theo phiên đang chạy.
5. Ghi snapshot vào data/realtime/ (có cờ live và giờ chụp), dựng dashboard không làm mới file tồn kho để chạy nhanh.
6. Dashboard mở sẵn ở chế độ Real-time, góc trên ghi “LIVE hh:mm · proprietary data dd/mm · auto-refresh every 5 min” và tự tải lại khi tới lượt cập nhật.
7. Lặp lại mỗi 5 phút. Mở trước 09:00 thì chờ; 11:30–13:00 nghỉ trưa; 15:05 chụp lần cuối (giá sau ATC) rồi tự dừng. Dừng tay: Ctrl+C hoặc đóng cửa sổ.

Tần suất và giờ chạy chỉnh trong config/api_config.py (không bắt buộc): REALTIME_REFRESH_MINUTES là 5 phút, REALTIME_START là 09:00, REALTIME_END là 15:05. Không khai báo thì dùng các giá trị mặc định này.

5. Dựng dashboard

build.py gọi lần lượt từng bộ dựng; mỗi bộ thêm một phần dữ liệu vào data/cache/web_data.json, cuối cùng nhúng tất cả vào template.

1. market_data.py: đọc Horizon + tự doanh + giá đóng cửa, kiểm tra cùng ngày → dữ liệu Tab 1 (K, C, CL, CWS, RT).
2. client_data.py: dòng tiền nhà đầu tư theo ngày, bucket moneyness / DTE / leverage → Tab 2 (CL2, FIRST).
3. inventory_refresh.py: mở file tồn kho bằng Excel, Refresh All, lưu, đóng (tối đa 600 giây). Bỏ qua ở chế độ Realtime.
4. k_batches.py: lọc tiểu khoản CW, lọc nhiễu, bù ngày thiếu từ tự doanh, cảnh báo thiếu lịch sử → biểu đồ batch (KB).
5. template/: head.html (CSS) + body.html (bố cục) + app.js.html (vẽ biểu đồ) → CW Dashboard.html. Ở chế độ Realtime, trang nhận thêm cấu hình LIVE để mở sẵn Real-time và tự tải lại.

6. Cây thư mục và vai trò từng file

CW_Market Overview/
├─ Run CW Market Overview.bat      chạy chốt ngày (Sync)
├─ Run CW Realtime.bat             chế độ realtime trong phiên
├─ Rebuild Dashboard.bat           chỉ dựng lại dashboard
├─ main.py                         điều phối 9 bước
├─ run_realtime.py                 khởi động chế độ realtime
├─ build_dashboard.py              gọi bộ dựng dashboard cho Rebuild
├─ CW Market Overview.xlsx         workbook chính (Horizon + RawData)
├─ K_Prop.xlsx                     tồn kho nội bộ (Power Query)
├─ CW Dashboard.html               dashboard
├─ config/
│  └─ api_config.py                mọi thiết lập
├─ src/
│  ├─ ensure_python.bat            tìm / cài Python
│  ├─ api_client.py                gọi SSI
│  ├─ as_of.py                     chọn ngày as-of, DATA CHECK
│  ├─ step_cache.py                cache theo ngày
│  ├─ historical_loader.py         giá lịch sử, HV, Yang-Zhang
│  ├─ underlying_liquidity.py      giá trị khớp, ADV
│  ├─ proprietary_trading.py       tự doanh VNDIRECT
│  ├─ option_pricing.py            Black-Scholes, IV, delta
│  ├─ cw_processor.py              bảng master
│  ├─ volatility_models.py         GARCH / GJR-GARCH, backtest
│  ├─ garch_pipeline.py            GARCH theo kỳ hạn CW
│  ├─ realtime.py                  snapshot Real-time, CSV
│  ├─ raw_data.py                  sheet RawData
│  ├─ excel_exporter.py            ghi Horizon, workbook GARCH
│  ├─ workbook_io.py               popup, backup, lưu an toàn
│  ├─ inventory_refresh.py         tự làm mới file tồn kho
│  ├─ intraday.py                  chụp bảng giá trong phiên, vòng lặp 5 phút
│  └─ dashboard/
│     ├─ build.py                  điều phối dựng dashboard
│     ├─ market_data.py            dữ liệu Tab 1
│     ├─ client_data.py            dữ liệu Tab 2
│     ├─ k_batches.py              biểu đồ batch
│     └─ template/                 head.html · body.html · app.js.html · ảnh base64
├─ data/
│  ├─ pdt_cache.csv · pdt_daily.csv          tự doanh luỹ kế / theo ngày
│  ├─ cw_eod.csv · underlying_daily.csv      giá đóng cửa CW và cơ sở
│  ├─ realtime/                    snapshot cho nút Real-time / chế độ realtime
│  ├─ cache/  backup/  output/
│  └─ Inventory_dip_check.xlsx               phân tích tồn kho "hụt rồi hồi"
├─ GARCH Volatility Result/                  kết quả GARCH (7 sheet) + chi tiết backtest
├─ backup/                                   lịch sử code + template workbook
├─ Claude outputs/                           ảnh phân tích phụ
└─ logs/                                     (rỗng)

Vai trò chi tiết

7. Lấy dữ liệu qua API SSI và VNDIRECT

Hệ thống không dùng API có tài liệu chính thức. Nó gọi các địa chỉ mà bảng giá web công khai của SSI (iBoard) và VNDIRECT (dstock) vẫn gọi để hiển thị dữ liệu. Phần này mô tả cách gọi từng địa chỉ, tham số, các trường dùng tới và cách script mẫu xử lý dữ liệu.

7.1 Nguyên tắc chung

• Phương thức GET, không cần đăng nhập hay khoá API.
• Gửi kèm header giống trình duyệt: User-Agent của Chrome trên Windows và Accept nhận JSON. Riêng VNDIRECT cần thêm hai header Referer và Origin, đều là trang dstock.vndirect.com.vn; thiếu hai header này máy chủ trả lỗi 403.
• API SSI trả về trường code có giá trị SUCCESS khi thành công; dữ liệu nằm trong trường data.
• API có phân trang (stock-info của SSI, tự doanh của VNDIRECT): lặp số trang cho tới khi hết dữ liệu.
• Đơn vị và giờ: giá lịch sử của SSI tính theo nghìn đồng (21.60 = 21.600 đ); mốc thời gian là Unix giây, nến ngày được đóng dấu 00:00 giờ Việt Nam, nên đổi sang múi giờ Asia/Ho_Chi_Minh trước khi lấy ngày.
• Ngày tháng mỗi API một kiểu: 20261007 (bảng giá SSI), 07/10/2026 (stock-info, maturityDate), 2026-10-07 (VNDIRECT).

7.2 Sáu địa chỉ đang dùng

Các địa chỉ dưới đây đều dùng giao thức https.

7.3 Chi tiết và lưu ý từng API

• Bảng CW (1) trả toàn bộ CW đang niêm yết trong 1 lần gọi. Chế độ Realtime còn dùng best1Bid / best1Offer (giá mua / bán tốt nhất) để lấy giá giữa khi mã chưa khớp lệnh. Trong giờ giao dịch, matchedPrice là giá khớp gần nhất; ngoài giờ là giá đóng cửa. Khi chưa khớp lệnh thì dùng refPrice. Tỷ lệ chuyển đổi dạng chữ “1.7245:1” → lấy số trước dấu hai chấm.
• Giá lịch sử (3) dùng chung cho mã CW và mã cổ phiếu. Hệ thống tải 1 lần cho mỗi cổ phiếu, đủ dài cho kỳ hạn CW dài nhất (+45 ngày); GARCH tải khoảng 5 năm. Nếu ngày as-of không phải hôm nay, giá CW được lấy từ nến của ngày as-of.
• listedShare (4) phải gọi từng mã. Hệ thống chỉ gọi cho mã mới, mã cũ đọc lại từ Excel.
• Stock-info (5) lấy từ 01/01 năm hiện tại tới ngày as-of. Giá trị khớp phiên cuối = “Market trading value”; trung bình 20 / 60 phiên cuối = ADV 1 tháng / 3 tháng; trung bình cả kỳ = ADV từ đầu năm.
• Tự doanh VNDIRECT (6): hệ thống lọc theo mã phía máy chủ, lọc theo ngày phía Python (từ ngày giao dịch đầu tiên tới ngày as-of), và gọi lại tối đa 3 lần nếu lỗi để không biến lỗi mạng thành số 0. Lượng CW nhà đầu tư nắm giữ ước tính = khối lượng tự doanh bán − khối lượng tự doanh mua, cộng luỹ kế. Không dùng netVol của VNDIRECT vì ngược dấu (= mua − bán).
• Kiểm tra ngày đã có dữ liệu: gọi (6), lọc theo ngày cần kiểm tra và chỉ lấy 5 bản ghi; có bản ghi nghĩa là VNDIRECT đã công bố tự doanh ngày đó. Đây là nguồn công bố muộn nhất nên quyết định ngày as-of.

7.4 Tự tìm hoặc kiểm tra lại một API

1. Mở trang bảng giá (iboard.ssi.com.vn hoặc dstock.vndirect.com.vn) bằng Chrome, nhấn F12 → tab Network → lọc Fetch/XHR.
2. Thao tác trên trang (chọn nhóm chứng quyền, mở biểu đồ, mở tab tự doanh) và xem các yêu cầu mới xuất hiện.
3. Bấm vào một yêu cầu: tab Headers cho địa chỉ, tham số, header cần gửi; tab Preview/Response cho cấu trúc JSON.
4. Chuột phải vào yêu cầu → Copy → sao chép yêu cầu dưới dạng lệnh để thử lại ngoài trình duyệt, hoặc viết lại bằng thư viện requests của Python.
5. Khi API đổi: so cấu trúc JSON mới với bảng ở mục 7.2, sửa địa chỉ trong config/api_config.py và tên trường trong file src/… tương ứng.

7.5 Cách gọi cụ thể

Mọi lần gọi đều là yêu cầu GET kèm header giống trình duyệt như mục 7.1, thời gian chờ tối đa 30 giây. Ví dụ đơn giản nhất gồm hai lần gọi:

1. Gọi địa chỉ (1) để lấy bảng chứng quyền HOSE, rồi đếm số phần tử trong danh sách coveredWarrantData để biết số CW đang niêm yết.
2. Gọi địa chỉ (6) với header bổ sung của VNDIRECT, lọc theo một mã CW (ví dụ CACB2516), sắp theo ngày, trang 1, 100 dòng mỗi trang; đọc totalPages để biết còn bao nhiêu trang và xem bản ghi đầu tiên để kiểm tra cấu trúc.

7.6 Script mẫu: 6 hàm tương ứng 6 địa chỉ

Script viết bằng Python, cần hai thư viện requests và pandas. Kết quả in ra màn hình và ghi CSV vào thư mục api_output cạnh file script.

Khi chạy thử, script lần lượt:

1. Lấy bảng CW, in số mã và ngày giao dịch, đếm riêng số mã do K phát hành; ghi ra file CSV.
2. Lấy bảng VNALL, in số mã; ghi ra file CSV.
3. Chọn một mã CW của K làm ví dụ (nếu không có thì lấy mã đầu tiên của bảng), kèm cổ phiếu cơ sở của nó.
4. Tải lịch sử 400 ngày của cổ phiếu cơ sở, in số phiên và giá đóng cửa gần nhất; ghi ra file CSV.
5. In số lượng CW niêm yết của mã ví dụ.
6. Tải lịch sử giao dịch từ đầu năm, tính ADV 20 phiên (tỷ đồng).
7. Nghỉ 0,5 giây rồi tải tự doanh của mã ví dụ, in số ngày có dữ liệu và lượng bán ròng luỹ kế; ghi ra file CSV.

8. Quá trình xây dựng

Giai đoạn 1 được suy ra từ thứ tự các thư mục lưu code cũ (không có ngày cụ thể). Giai đoạn 2 là các thay đổi từ tháng 10/2026.

Giai đoạn 1 · Dựng lõi tính toán

1. Bảng Horizon trong Excel: lấy bảng CW + cổ phiếu từ SSI, tính IV, delta, HV, breakeven, ghi vào template Excel có định dạng sẵn.
2. Thêm dashboard HTML: tách phần dựng trang, xuất 1 file tự chứa.
3. Cache theo bước: chạy lại trong ngày không tải lại; bỏ các câu hỏi y/n.
4. Một ngày as-of cho mọi nguồn: quy tắc 15:00, lùi ngày khi tự doanh chưa công bố, đưa giá về giá đóng cửa, bảng DATA CHECK.
5. Tự doanh theo ngày → Tab 2 phân tích dòng tiền nhà đầu tư.
6. GARCH theo kỳ hạn CW: giới hạn persistence ≤ 0,99, backtest walk-forward, workbook GARCH riêng.
7. Gộp tên issuer, lãi suất 7% chung cho mọi CW.

Giai đoạn 2 · Ổn định và nối nguồn tồn kho (10/2026)

1. 05/10: rà toàn bộ mã nguồn, viết tài liệu cấu trúc; phát hiện bản đóng gói thiếu workbook chính nên “chạy không ra dữ liệu”.
2. 06–07/10: main.py kiểm tra workbook ngay từ đầu; phát hiện file tồn kho xuất sai tiểu khoản từ 02/10.
3. 08/10: lọc đúng tiểu khoản CW, bù ngày thiếu từ tự doanh (vẽ nét đứt + cảnh báo). Ước tính sau đó trùng khớp số thật.
4. 08/10: chuyển sang file tồn kho K_Prop (Power Query): đọc ngày dạng Excel, cho phép nhiều file, log từng file.
5. 08/10: K_Prop tự làm mới khi chạy; cảnh báo “History cut” khi dữ liệu tồn kho bắt đầu muộn hơn ngày batch giao dịch.
6. 08/10 · bản hoàn chỉnh: chế độ Realtime trong phiên (Run CW Realtime.bat): giá đang giao dịch mỗi 5 phút, dashboard tự tải lại, phần tự doanh giữ ngày Sync.

9. Vận hành

Cảnh báo thường gặp

10. Muốn sửa gì thì sửa ở đâu