Dữ liệu quỹ đầu tư Việt Nam bằng Python

Danh mục của nhà đầu tư tổ chức là thứ khó lấy nhất và cũng dễ dùng nhất khi đã có. client.funds trả lời bốn câu: có những quỹ nào, quỹ này lãi lỗ ra sao, quỹ này đang nắm gì, và — chiều ngược lại — mã này đang được quỹ nào nắm.

188 quỹ; 149 quỹ có chuỗi giá trị tài sản ròng, 141 quỹ có danh mục nắm giữ. NAV theo ngày, danh mục theo tháng.

import finlens

client = finlens.client()

ds = client.funds.list(fund_type="Quỹ ETF")
nav = client.funds.nav("E1VFVN30", start="2026-01-01")
ai = client.funds.holders("HPG")

Tổng tỷ trọng không bằng 1, và đó không phải lỗi

Đây là chỗ dễ mắc nhất của cả trang, nên nó đứng trước phần tham chiếu.

Bảng holdings() liệt kê phần danh mục được công bố, không phải toàn bộ tài sản. Đo trên mười hai quỹ:

for ma in ["ABBF", "ACBC-BGF", "AEIF", "ASBF", "ABEF"]:
    h = client.funds.holdings(ma)
    print(ma, len(h), round(h["weight_ratio"].sum(), 4))

# ABBF      14  0.8939
# ACBC-BGF  24  0.5691
# AEIF      23  0.4969
# ASBF       3  0.2757
# ABEF      28  0.9864

Dải đo được là 0,2426 đến 0,9864, và không quỹ nào vượt 0,99. Quỹ công bố ít dòng thì tổng càng thấp — ASBF có ba dòng và tổng 0,2757.

Nên 1 − Σ weight_ratio không phải tỷ lệ tiền mặt. Muốn biết quy mô thật, đọc total_nav của nav().

list() — danh mục quỹ và hồ sơ

client.funds.list(
    *,
    fund_type=None,
    structure=None,
    manager=None,
    refresh=False,
    on_error="warn",
) -> DataFrame

Hai tham số đầu là từ vựng đóng và giữ nguyên tiếng Việt có dấu — chúng là nhãn phân loại của nguồn, không phải token ASCII.

Cột trả về

Frame có 28 cột. Những cột hay dùng nhất:

Hai cột đếm cuối là cách rẻ nhất để biết trước một quỹ có dữ liệu hay không, thay vì gọi rồi nhận bảng rỗng.

nav() — giá trị tài sản ròng theo ngày

client.funds.nav(
    funds,
    *,
    start=None,
    end=None,
    refresh=False,
    on_error="warn",
) -> DataFrame

Đây là phương thức duy nhất của nhóm tự phân trang: bảng nguồn có hơn 136 nghìn dòng, vượt xa hạn mức một request, và thư viện đi hết chuỗi cursor giúp bạn. Nó cũng là phương thức duy nhất giữ cache 30 phút thay vì 24 giờ.

Cột trả về

holdings() — quỹ này đang nắm gì

client.funds.holdings(
    fund,
    *,
    date=None,
    refresh=False,
    on_error="warn",
) -> DataFrame

Cột trả về

asset_type cho biết mã trong asset_code tra ở đâu: "stock" thì nó là mã chứng khoán tra được bằng client.meta.symbols(), còn "bond" thì nó là mã trái phiếu tra bằng client.bonds.list().

holders() — mã này đang được quỹ nào nắm

client.funds.holders(
    symbols,
    *,
    date=None,
    refresh=False,
    on_error="warn",
) -> DataFrame

Đây là phép tra ngược của holdings(), và là thứ không tự tính được từ một bảng phẳng: nó đòi quét danh mục của mọi quỹ rồi gom theo mã.

⚠️ Kết quả trải nhiều kỳ, không phải một ảnh chụp. holders("HPG") trả về 80 dòng nằm trên 5 kỳ quan sát khác nhau — lọc theo date nếu bạn chỉ cần kỳ gần nhất:

k = client.funds.holders("HPG")
moi_nhat = k[k["date"] == k["date"].max()]

Cột trả về

weight_ratio ở đây là tỷ trọng trong danh mục của quỹ, không phải tỷ lệ sở hữu trên vốn của doanh nghiệp. Hai đại lượng đó khác mẫu số hoàn toàn.

managers() — người điều hành quỹ

client.funds.managers(
    fund,
    *,
    refresh=False,
    on_error="warn",
) -> DataFrame

Cột trả về

Mã quỹ nhập nhằng

Một mã quỹ có thể thuộc hai tổ chức khác nhau. Khi đó thư viện không đoán:

import finlens

try:
    client.funds.nav("VVDIF")
except finlens.AmbiguousFundError as e:
    print(e.organization_ids)
    df = client.funds.nav(e.organization_ids[0])

Ngoại lệ mang theo fund_code và organization_ids để bạn chọn. Mọi frame của nhóm này luôn trả về cả fund_code lẫn organization_id, nên bạn có sẵn định danh không nhập nhằng ngay trong kết quả.

Độ phủ có lỗ, và API không lọc chúng đi

Quỹ không có dữ liệu trả về bảng rỗng đủ cột đúng dtype, không phải lỗi:

df = client.funds.nav("A+ Fund")
len(df)          # 0
len(df.columns)  # 14
df["nav_per_share"].sum()   # 0.0 — không KeyError

Kiểm trước bằng nav_point_count và holding_period_count của list() sẽ rẻ hơn là gọi rồi nhận bảng rỗng.

Thư viện không tính sẵn chỉ số nào

Không có suất sinh lợi 1 tháng / 3 tháng / từ đầu năm, không xếp hạng, không nhãn gom hay xả. finlens trả DataFrame; những thứ đó là hai dòng pandas:

nav = client.funds.nav("E1VFVN30", start="2026-01-01")
nav = nav.set_index("date")
loi_nhuan = nav["nav_per_share_adjusted"].pct_change(periods=20)

Tính ở máy chủ buộc phải chốt quy ước qui năm và quy ước điều chỉnh vào hợp đồng — loại quyết định sai một lần rồi sai lặng lẽ mãi. Sản phẩm MCP có tính sẵn những chỉ số này, và đó là khác biệt có chủ đích giữa hai bề mặt.