Giá lịch sử cổ phiếu Việt Nam bằng Python (EOD)

Danh sách đầy đủ ở Changelog.

Bảng chỉ liệt kê những phương thức thực sự tồn tại, và chỗ nào không liệt kê thì gọi vào sẽ ném AttributeError ngay tại chỗ:

client.eod.warrant.supply_demand("CHPG2628")     # AttributeError
client.eod.derivative.supply_demand("VN30F1M")   # AttributeError
client.eod.index.active_volume("VNINDEX")        # AttributeError
client.eod.stock.basis("HPG")                    # AttributeError

Sổ lệnh đặt chỉ tồn tại cho cổ phiếu trong dữ liệu; hỏi nó cho chỉ số, ngành, chứng quyền hay phái sinh cho ra 0 dòng. Còn basis() cần một chỉ số cơ sở để trừ, và chỉ hợp đồng tương lai mới có thứ đó.

Một sự vắng mặt trong dữ liệu phải là một sự vắng mặt trong API — cùng lý do client.intraday.index không có net_active_value(). Phát ra một phương thức luôn trả bảng rỗng là bắt bạn tự đoán xem đó là "không có giao dịch" hay "không có dữ liệu".

client.eod.sector.ohlcv() trả về chỉ số ngành, tính bằng điểm chỉ số. client.eod.sector.investor.flow() trả về dòng tiền, tính bằng VND thô.

Hai bảng cùng khoá theo icb, cùng nằm trong một namespace, nên cám dỗ chia bảng này cho bảng kia là có thật — và làm vậy là chia hai đại lượng không cùng thứ nguyên. Không có exception nào được ném.

Trong từ vựng cũ 1M là một tháng còn 1m là một phút — phân biệt duy nhất bằng chữ hoa, trong khi hai giá trị đó lệch nhau 43.200 lần. Cả hai đều nhận một lỗi rõ ràng thay vì bị đoán ý:

Interval '1M' nhập nhằng: có thể là một phút hoặc một tháng.
Dùng '1min' cho một phút, hoặc '1mo' cho một tháng.

Với dữ liệu cuối ngày, giá trị bạn cần là 1mo. Lỗi là finlens.InvalidIntervalError, mã FL_VALIDATION_INTERVAL_AMBIGUOUS.

date là phiên cuối kỳ, nhưng open là giá mở cửa của phiên đầu kỳ. Hai cột trên cùng một dòng trỏ tới hai phiên khác nhau, và điều đó là đúng: dòng ấy mô tả cả kỳ, chỉ được dán nhãn bằng phiên cuối.

Nên đừng đọc một dòng 1mo như thể nó là phiên ngày 24/01. open của nó không phải giá mở cửa hôm 24/01, và volume của nó không phải khối lượng riêng phiên ấy — đó là tổng cả tháng.

client.eod.stock trả giá bằng nghìn VND, client.eod.warrant trả giá bằng VND thô. Đây đúng là kịch bản sai âm thầm: hai bảng cùng tên cột, cùng kiểu, và phép trừ giữa chúng vẫn chạy. Đọc df.attrs["finlens"]["units"]["close"] trước khi tính bất cứ thứ gì bắc cầu giữa hai namespace.

Int32 viết hoa là kiểu số nguyên nullable của pandas, không phải int32 của numpy. Phiên nào nguồn không có số mã cấu thành thì đó là thiếu, và int32 thường sẽ biến cái thiếu ấy thành 0 — tức thành "ngành này không có mã nào", một câu khác hẳn, mà không có lỗi nào được ném.

df[df["n_stocks"].isna()]     # đúng
df[df["n_stocks"] == 0]       # sai — trộn "thiếu dữ liệu" với "không có mã nào"

Cột này được phát ra chứ không bị giấu vì nó giải thích những bước nhảy của chuỗi chỉ số: một ngành từ 3 mã lên 5 mã thì chuỗi đứt đoạn ở đúng chỗ ấy, và không cột nào khác nói ra được.

Khi resample, n_stocks lấy giá trị của phiên cuối kỳ — đúng phiên mà date trỏ tới — chứ không phải tổng. Nó là một trạng thái, không phải một lượng cộng dồn được.

Trung vị của tỷ lệ buy_order_volume / volume — cùng mã, cùng phiên, với volume là khối lượng khớp của ohlcv() — là 2,756 lần. 99,77% số dòng có khối lượng đặt lớn hơn hoặc bằng khối lượng khớp, và có rất nhiều phiên khối lượng khớp bằng 0 mà sổ lệnh vẫn có lệnh đặt.

Đó là lý do mọi tên cột ở đây mang chữ _order_. Trừ một cột của bảng này cho volume của ohlcv(), hay đặt nó cạnh buy_volume của investor.flow(), là so hai đại lượng chênh nhau khoảng ba lần — và không có exception nào chặn phép tính đó.

dat  = client.eod.stock.supply_demand("HPG", start="2026-08-01")
khop = client.eod.stock.ohlcv("HPG", start="2026-08-01")

# dat["buy_order_volume"] - khop["volume"]   <- vô nghĩa, và vẫn chạy

Đại lượng này trả lời "áp lực đặt lệnh bên nào lớn hơn", không trả lời "ai đã mua bao nhiêu".

Int64 viết hoa là kiểu số nguyên nullable của pandas, không phải int64 của numpy. Máy chủ phát giá trị thiếu khi nguồn không ghi số lệnh trong khi vẫn ghi khối lượng, và điều đó xảy ra ở khoảng 11% số dòng. int64 thường không mang được giá trị thiếu nên nó sẽ biến cái thiếu ấy thành 0 — tức thành "phiên này không ai đặt lệnh mua", một câu khác hẳn, mà không có lỗi nào được ném.

df[df["buy_order_count"].isna()]    # đúng
df[df["buy_order_count"] == 0]      # sai — trộn "chưa biết" với "không có lệnh"

Và khi gộp kỳ: một kỳ chứa dù chỉ một phiên thiếu số lệnh thì cả ba cột _count của kỳ đó đều thiếu. Một tổng thiếu trông hợp lý còn nguy hiểm hơn một ô trống. Ba cột _volume không chịu ràng buộc này.

Hai đại lượng nghe giống nhau và không cộng được với nhau. Cùng một phiên VN30F1M, ba cột tương ứng của hai bảng lệch nhau 57,5% · 520% · 30,1%.

Phép cộng hay phép trừ giữa hai frame không ném exception nào, chỉ cho ra một con số sai. Đó là lý do hai phương thức mang hai cái tên khác hẳn nhau, chứ không phải cùng tên ở hai namespace.

active_buy_volume + active_sell_volume bằng đúng khối lượng khớp cả phiên. Nguồn chia trọn 100% khối lượng thành đúng hai phía, nên phiên định kỳ ATO/ATC — vốn không có bên chủ động nào — đã nằm sẵn trong một trong hai cột.

Hệ quả: active_buy_volume ở đây rộng hơn buy_volume của client.intraday.*.net_active_value(), nơi ATO/ATC có cột auction_volume riêng. Hai cái tên khác nhau chính vì hai định nghĩa khác nhau.

Muốn tách bạch phần khớp lệnh định kỳ thì dùng bảng trong phiên, không dùng bảng này — xem Dữ liệu trong phiên.

Đây là phương thức duy nhất của nhóm EOD không nhận interval, và client.intraday.derivative.basis() cũng vậy.

Gộp một chênh lệch qua nhiều bước không có nghĩa hiển nhiên nào: trung bình của kỳ, giá trị cuối kỳ và biên độ trong kỳ là ba câu trả lời khác nhau cho cùng một câu hỏi. Chọn hộ một trong ba là chôn một quyết định phân tích vào thư viện. Cần thì df.resample(...) trên chính frame này, nơi bạn tự chọn.

basis     = future_close - spot_close     # điểm chỉ số
basis_pct = basis / spot_close * 100      # phần trăm, thang 0–100

Hai chi tiết không suy ra được từ cái tên, nên cả hai được viết ra:

• Mẫu số là spot_close, không phải future_close. Hai mẫu số chỉ lệch nhau khoảng 0,3% nên chọn nhầm gần như không nhìn ra được trên một biểu đồ.
• Thang là 0–100, không phải 0–1. Nhân thêm 100 lần nữa là sai 100 lần, cũng không có gì báo.

basis thì là hiệu tuyệt đối — không chia cho gì, không nhân 100 — nên nó vẫn mang đơn vị của hai vế: điểm chỉ số. Dương là hợp đồng giao dịch cao hơn chỉ số (contango), âm là thấp hơn (backwardation).

Lý do rất cụ thể: df.attrs biến mất ngay khi bạn pd.concat hai frame. Khi đó hai dòng của hai hợp đồng trên hai chỉ số khác nhau trông y hệt nhau, trong khi basis của chúng đo hai thứ khác nhau — và không cột nào còn nói ra được điều đó.

Mã không phải phái sinh nhận lỗi 400 ngay. Nhưng một mã phái sinh có tồn tại mà không có chuỗi chỉ số cơ sở trong dữ liệu thì đi vào phần lỗi theo từng mã với mã lỗi FL_DATA_NO_UNDERLYING, ánh xạ về finlens.NoDataError:

df = client.eod.derivative.basis(["VN30F1M", "VN100F1M"])
# PartialDataWarning — df chỉ chứa VN30F1M
df.attrs["finlens"]["failed"]
# {'VN100F1M': {'code': 'FL_DATA_NO_UNDERLYING', 'message': ...}}

Mã lỗi này khác FL_DATA_EMPTY vì hai bệnh khác nhau: FL_DATA_EMPTY là khoảng bạn hỏi không có dòng nào, còn mã này là hợp đồng này không có chỉ số cơ sở, tức không đổi start/end nào cứu được. Nó cũng không phải InvalidSymbolError — mã bạn gõ hoàn toàn đúng.

Đây là hành vi mặc định on_error="warn"; đặt on_error="raise" nếu bạn muốn một mã hỏng làm hỏng cả lời gọi.

client.eod.stock.ohlcv() trả giá bằng nghìn VND, còn client.eod.stock.investor.flow() trả giá trị bằng VND thô. Khối lượng tính bằng cổ phiếu, không phải lô.

Đó chính là lý do dòng tiền sống trong một namespace riêng chứ không phải vài phương thức thêm vào client.eod.stock: hai bộ cột không cùng đơn vị.

1. Muốn cộng thì chỉ cộng bốn nhóm chi tiết. Chúng là phân hoạch duy nhất.
2. Bốn nhóm chi tiết trên thực tế chỉ có dữ liệu cho mã sàn HOSE. Với mã HNX hay UPCOM, chúng trả về bảng rỗng — hãy dùng foreign, nhóm phủ đủ ba sàn.
3. Tự doanh về trễ khoảng ba phiên. Những phiên gần nhất của nhóm proprietary có thể chưa có dòng nào, và đó không phải lỗi.

Ở cấp chỉ số chỉ có flow(). Và trong thực tế chỉ VNINDEX có dữ liệu — tài liệu 0.1.x hứa cả VN30, HNXINDEX và UPINDEX, không mã nào trong số đó có số liệu dòng tiền.

Điều đó nguy hiểm hơn một lỗi, vì mặc định on_error="warn" nghĩa là lời gọi không thất bại:

df = client.eod.index.investor.flow(["VNINDEX", "VN30"])
# PartialDataWarning — df chỉ chứa VNINDEX
df.attrs["finlens"]["failed"]

Đặt on_error="raise" nếu bạn muốn biết ngay thay vì phát hiện muộn.

Bốn nhóm chi tiết (foreign_individual, foreign_institutional, local_individual, local_institutional) không tồn tại ở cấp ngành — ở bất kỳ cấp ICB nào. Cái bị chặn là một nguồn, không phải một cấp: nguồn của bốn nhóm đó thực chất chỉ có sàn HOSE, trong khi ngay ở cấp 4 một ngành đã trải cả ba sàn — con số tổng hợp sẽ thiếu hẳn phần HNX và UPCOM mà không có gì trong bảng nói ra.

Yêu cầu chúng nhận một lỗi 400 rõ ràng chứ không phải một bảng rỗng im lặng, và kiểu SectorInvestorGroup đã chặn ngay lúc bạn gõ code. Muốn bốn nhóm đó thì hỏi ở cấp mã.

Hai nhóm còn lại nằm trên hai trục rời nhau nên cũng không cộng được với nhau: foreign lấy cả thoả thuận, còn proprietary đến từ một nguồn khác hẳn.

Cấp 4 đọc thẳng số gốc của nguồn. Cấp 2 là tổng của các ngành con cấp 4 do máy chủ cộng lại.

Phép cộng đó đầy đủ với nhóm foreign. Với proprietary thì có một khoảng trống đã biết: vài ngành cấp 4 có dữ liệu khối ngoại nhưng không có dữ liệu tự doanh, nên phần của chúng vắng khỏi tổng cấp 2 — máy chủ phát một cảnh báo nêu đích danh những ngành đó.

Và đừng chuyển kết luận này sang client.eod.sector.ohlcv(): ở đó cả hai cấp đều là số gốc, vì chỉ số ngành được tính sẵn ở cả hai cấp.

Bốn nhóm chi tiết (foreign_individual, foreign_institutional, local_individual, local_institutional) không tồn tại ở cấp hợp đồng phái sinh và nhận lỗi 400, không phải một bảng rỗng: nguồn của chúng khoá theo danh mục doanh nghiệp niêm yết, nơi không hợp đồng phái sinh nào có mặt.

Kiểu DerivativeInvestorGroup chỉ khai hai giá trị nên IDE gạch đỏ ngay lúc bạn gõ, trước cả một vòng gọi mạng.

Đây cũng là chỗ breakdown() ở đây khác client.eod.stock.investor.breakdown(): bỏ trống groups ở cấp mã cho sáu nhóm, bỏ trống ở đây cho hai.

Hai nhóm này nằm trên hai trục rời nhau và không cộng được với nhau — cùng lý do với cấp mã và cấp ngành.

Hai chỗ dễ đọc nhầm nhất của bảng này, và cả hai đều không có gì báo:

1. net_volume là chênh lệch hợp đồng ĐÃ KHỚP trong kỳ, không phải vị thế mở. Một nhóm mở rồi đóng hết trong cùng phiên có net_volume bằng 0 dù đã khớp hàng nghìn hợp đồng; ngược lại, net_volume dương không nói vị thế mở cuối phiên là bao nhiêu. Cộng dồn net_volume qua nhiều phiên không cho ra vị thế tích luỹ — bảng này không mang thông tin đó.

2. Các cột *_value là giá trị DANH NGHĨA của số hợp đồng đó, đã quy đổi ra VND thô bằng hệ số hợp đồng ở máy chủ — không phải số tiền nhà đầu tư thực bỏ ra, vốn chỉ là phần ký quỹ. Cũng vì vậy đừng tự nhân net_volume với giá đóng cửa của ohlcv() rồi so với net_value: bỏ quên hệ số hợp đồng là lệch 100.000 lần, và phép nhân đó vẫn chạy.

df.attrs["finlens"]["units"]["net_value"]    # 'VND'
df.attrs["finlens"]["units"]["net_volume"]   # 'contract'

Bộ tên cột giống hệt bản cổ phiếu, nên pd.concat một frame phái sinh với một frame cổ phiếu cho ra một cột net_volume mang hai đơn vị — và df.attrs không sống sót qua concat để nói ra điều đó.

DataFrame.attrs là thông tin đi kèm, không phải cơ chế bảo vệ — pandas bỏ nó khi bạn pd.concat hay df.merge. Đọc đơn vị trước khi ghép bảng.

Bảo vệ thật nằm ở chỗ tách namespace: một lời gọi không bao giờ trộn được hai đơn vị, vì client.eod.stock và client.eod.index không trả về cùng một bảng.