finlens — Dữ liệu chứng khoán Việt Nam cho Python

Thư viện Python lấy dữ liệu thị trường chứng khoán Việt Nam — giá cuối ngày và trong phiên, khớp lệnh từng lệnh (tick-by-tick), dòng tiền theo nhóm nhà đầu tư, báo cáo tài chính và danh mục mã — trả về thẳng dưới dạng pandas.DataFrame.

Phủ HOSE (HSX), HNX và UPCOM: 1.645 cổ phiếu và chứng chỉ quỹ, 632 chứng quyền có bảo đảm, hợp đồng phái sinh VN30F1M, và các chỉ số VNINDEX, VN30, HNX-INDEX, UPCOM-INDEX.

Python library for Vietnam stock market data — daily and intraday OHLCV, tick-by-tick trades, foreign investor flows, financial statements. Covers HOSE, HNX and UPCOM. Returns pandas DataFrames.

pip install finlens

import finlens

client = finlens.client(api_key="flk_...")  # hoặc đặt biến FINLENS_API_KEY

df = client.eod.stock.ohlcv("HPG,VCB,FPT", start="2026-01-01", end="2026-01-05")
print(df)
#   symbol       date   open   high    low  close       volume
# 0    FPT 2026-01-05  94.40  94.40  91.93  93.71    7129300.0
# 1    HPG 2026-01-05  23.57  23.70  22.94  23.17   59427911.0
# 2    VCB 2026-01-05  ...

Giá ở đây tính bằng nghìn đồng — 23.17 nghĩa là 23.170 VND.

---

Mục lục

• Vì sao dùng finlens
• Cài đặt và khoá API
• Lấy được những dữ liệu gì
• Đơn vị — đọc trước khi tính toán
• Tra cứu nhanh
• Xử lý lỗi
• Async
• Câu hỏi thường gặp

---

Vì sao dùng finlens

Trả về pandas.DataFrame trần, không phải wrapper. Ghi được to_parquet, nối được pd.concat, dùng được mọi tutorial pandas bạn từng đọc.

Nhiều mã trong một request. ohlcv("HPG,VCB,FPT,...") với 50 mã là một lời gọi HTTP chứ không phải 50 lời gọi tuần tự.

Đơn vị được khai báo, không phải đoán. Mỗi frame mang theo df.attrs["finlens"]["units"]. Giá cổ phiếu Việt Nam thường ghi bằng nghìn đồng còn chứng quyền bằng đồng — nhầm chỗ này sai đúng 1000 lần và không có lỗi nào báo. Thư viện tách chúng thành các namespace riêng nên một lời gọi không bao giờ trả về bảng trộn hai đơn vị.

Kết quả rỗng vẫn đúng cột, đúng kiểu. Ngày thị trường nghỉ, df["close"] vẫn chạy — không KeyError.

Type hint đầy đủ, docstring tiếng Việt. Autocomplete và help() hoạt động; mypy --strict chạy sạch.

---

Cài đặt và khoá API

pip install finlens

Yêu cầu Python 3.11+ và pandas 3.0+.

Lấy khoá API tại finlens.vn. Khoá có dạng flk_....

import finlens

# Cách 1 — truyền thẳng
client = finlens.client(api_key="flk_...")

# Cách 2 — biến môi trường FINLENS_API_KEY (khuyến nghị)
client = finlens.client()

# Dùng như context manager để đóng kết nối gọn gàng
with finlens.client() as client:
    df = client.eod.stock.ohlcv("HPG")

Tạo client không chạm mạng — an toàn để đặt ở cell đầu notebook hoặc trong __init__ của một lớp.

client.whoami()  # gói dịch vụ, hạn mức, ngày hết hạn
client.status()  # trạng thái service (không cần khoá)

---

Lấy được những dữ liệu gì

Giá cuối ngày (EOD)

client.eod.stock.ohlcv("HPG", start="2020-01-01", interval="1w")
client.eod.index.ohlcv("VNINDEX")
client.eod.derivative.ohlcv("VN30F1M")
client.eod.warrant.ohlcv("CHPG2628")
client.eod.sector.ohlcv("8355")  # chỉ số ngành ICB

Cổ phiếu có từ 2007, chỉ số ngành từ 2000. interval nhận 1d, 1w, 1mo, 3mo, 6mo, 1y — gộp nhóm chạy ở server.

Giá cổ phiếu mặc định đã điều chỉnh quyền; thêm adjusted=False để lấy giá thô đúng như phiên hôm đó.

Trong phiên và tick-by-tick

client.intraday.stock.ohlcv("HPG", interval="5min")
client.intraday.stock.ticks("HPG", date="2026-08-03")  # từng lệnh khớp
client.intraday.stock.net_active_value("HPG", interval="1h")  # mua/bán chủ động

Tick có từ 2022. interval trong phiên: 1min, 5min, 15min, 30min, 1h, 4h.

Cột side của tick có ba giá trị: buy (bên mua nâng giá chạm bên bán), sell (bên bán hạ giá chạm bên mua), và auction (khớp lệnh định kỳ ATO/ATC). Phiên định kỳ không có bên chủ động nên xếp nó vào mua hay bán đều sai — nó chiếm 1,4%–8,6% khối lượng tuỳ mã, quá lớn để giấu.

ticks() lấy một mã, một phiên mỗi lần gọi: một phiên phái sinh sôi động là hơn 90.000 dòng.

Dòng tiền theo nhóm nhà đầu tư

client.eod.stock.investor.flow("HPG", group="foreign")
client.eod.stock.investor.breakdown("HPG")  # tất cả các nhóm
client.eod.sector.investor.flow("8355")  # theo ngành ICB

Nhóm	Có từ	Phạm vi
foreign	2010	cả ba sàn
foreign_individual, foreign_institutional	2024	HOSE
local_individual, local_institutional	2024	HOSE
proprietary (tự doanh)	2022	cả ba sàn

Bốn nhóm chi tiết cộng lại bằng 0 — mua ròng của nhóm này là bán ròng của nhóm kia. foreign và proprietary đến từ nguồn khác và nằm trên trục riêng; meta.additive_groups trong response nói rõ nhóm nào cộng được với nhau.

Báo cáo tài chính

client.financials.statement("HPG", kind="balance_sheet", period="quarterly")
client.financials.periods("HPG")  # kỳ nào có số liệu
client.financials.line_items(com_type="NH", kind="balance_sheet")

Có từ 2004. Bốn loại hình doanh nghiệp (CT phi tài chính, NH ngân hàng, CK chứng khoán, BH bảo hiểm) có cây chỉ tiêu khác nhau, nhưng frame ở dạng long và mỗi dòng mang company_type của chính nó — nên statement(["HPG", "VCB"]) chạy được dù hai mã khác loại hình.

Tra cứu danh mục

client.meta.symbols()  # 1.645 mã
client.meta.symbols(exchange="HOSE")  # 431 mã
client.meta.symbols(icb="8300")  # toàn ngành ngân hàng
client.meta.symbols(kind="fund")  # 24 chứng chỉ quỹ niêm yết
client.meta.sectors(level=2)  # 19 ngành ICB cấp 2
client.meta.sectors(level=4)  # 106 ngành ICB cấp 4
client.meta.warrants(underlying="HPG")  # chứng quyền của HPG

Tham số icb= nhận cả mã cấp 2 lẫn cấp 4 — bạn không cần biết mã mình cầm thuộc cấp nào.

# Lấy danh sách mã để lặp
tickers = client.meta.symbols(exchange="HOSE")["symbol"].tolist()

---

Đơn vị — đọc trước khi tính toán

Đây là nguồn lỗi số một khi làm việc với dữ liệu chứng khoán Việt Nam, và nó sai âm thầm: không exception nào, chỉ là một con số sai.

Loại	Cột giá	Khối lượng	Giá trị tiền
Cổ phiếu, ETF, chứng chỉ quỹ	nghìn VND (22.3 = 22.300 đ)	cổ phiếu	VND
Chỉ số	điểm chỉ số	cổ phiếu	—
Phái sinh	điểm chỉ số	hợp đồng	VND
Chứng quyền	VND thô	chứng quyền	VND

Luôn đọc thay vì giả định:

df.attrs["finlens"]["units"]  # {'close': 'kVND', 'volume': 'share', ...}
df.attrs["finlens"]["price_basis"]  # 'adjusted' hoặc 'raw'
df.attrs["finlens"]["as_of"]  # mốc nước của dữ liệu

⚠️ DataFrame.attrs không sống sót qua pd.concat hay merge của pandas. Đọc đơn vị trước khi ghép frame.

---

Tra cứu nhanh

Bạn muốn	Gọi
Giá VNINDEX theo tháng	client.eod.index.ohlcv("VNINDEX", interval="1mo")
Khối ngoại mua ròng HPG	client.eod.stock.investor.flow("HPG")
Từng lệnh khớp một phiên	client.intraday.stock.ticks("HPG", date="2026-08-03")
Cân đối kế toán theo quý	client.financials.statement("HPG", kind="balance_sheet", period="quarterly")
Mọi mã ngành ngân hàng	client.meta.symbols(icb="8300")
Chứng quyền còn hạn	client.meta.warrants()
Giá thô, chưa điều chỉnh	client.eod.stock.ohlcv("HPG", adjusted=False)

Mọi phương thức đều nhận refresh=True để bỏ qua cache, và on_error="raise" để một mã lỗi làm cả lời gọi thất bại thay vì chỉ cảnh báo.

---

Xử lý lỗi

Mọi lỗi kế thừa finlens.FinLensError và mang theo .code, .request_id, .doc_url.

import finlens

try:
    df = client.eod.stock.ohlcv("HPG")
except finlens.RateLimitError as e:
    print(f"Chờ {e.retry_after} giây")
except finlens.DailyQuotaExceededError as e:
    print(f"Hết hạn mức ngày, mở lại lúc {e.resets_at}")
except finlens.InvalidSymbolError:
    print("Mã không tồn tại")
except finlens.FinLensError as e:
    print(f"{e.code}: {e}")

Cây ngoại lệ:

FinLensError
├── AuthError          InvalidApiKeyError · ApiKeyExpiredError · AccountExpiredError
├── TierError          DatasetNotInTierError · SymbolNotInTierError
├── QuotaError         RateLimitError · DailyQuotaExceededError
├── ValidationError    InvalidSymbolError · InvalidDateRangeError · InvalidIntervalError
├── TransportError     ConnectionFailedError · TlsVerificationError · RequestTimeoutError
└── DataError          SchemaMismatchError · NoDataError

ValidationError cũng kế thừa ValueError, nên except ValueError vẫn bắt được.

Một mã lỗi không làm mất các mã còn lại. Mặc định on_error="warn": bạn nhận về những mã thành công kèm một cảnh báo, chi tiết ở df.attrs["finlens"]["failed"].

---

Async

Mọi thứ có bản async với cùng chữ ký:

import asyncio
import finlens


async def main():
    async with finlens.AsyncClient(api_key="flk_...") as client:
        df = await client.eod.stock.ohlcv("HPG,VCB")


asyncio.run(main())

Bản đồng bộ và bất đồng bộ dùng chung một lõi, nên không có chuyện một bên được sửa bug còn bên kia thì không.

---

Câu hỏi thường gặp

Giá cổ phiếu tính bằng đơn vị gì? Nghìn đồng. 22.3 nghĩa là 22.300 VND. Chứng quyền thì ngược lại — VND thô. Luôn đọc df.attrs["finlens"]["units"].

Dữ liệu có từ năm nào? Giá cuối ngày cổ phiếu từ 2007, chỉ số ngành từ 2000, khối ngoại từ 2010, báo cáo tài chính từ 2004, tick trong phiên từ 2022. Nhóm nhà đầu tư chi tiết (cá nhân/tổ chức, trong nước/nước ngoài) từ 2024 và chỉ có ở HOSE.

Lấy được dữ liệu của phiên đang chạy không? Được. Dữ liệu trong phiên cập nhật liên tục và meta.as_of cho biết mốc nước. Lưu ý giá trong phiên là giá thô, chưa điều chỉnh quyền — khác với EOD.

Lấy được bao nhiêu mã một lần? Tuỳ gói dịch vụ, xem client.limits(). Thư viện tự chia nhỏ và gọi song song, bạn cứ truyền cả danh sách. Riêng ticks() là một mã một phiên.

Có sổ lệnh (order book) không? Không. ticks() trả lệnh đã khớp, không phải độ sâu sổ lệnh. Giá đặt và khối lượng chờ theo bậc không có trong nguồn dữ liệu.

Có dữ liệu quỹ mở, trái phiếu, hàng hoá không? Chưa. Chứng chỉ quỹ niêm yết (kind="fund") thì có; quỹ mở, NAV, trái phiếu và hàng hoá thì không.

Cache hoạt động thế nào? Tự động. Dữ liệu lịch sử cache 7 ngày, phiên gần nhất 60 giây, danh mục và cây ngành 24 giờ. refresh=True để bỏ qua, client.cache.stats() để xem.

Chạy sau proxy doanh nghiệp hoặc phần mềm diệt virus? Nếu gặp TlsVerificationError, trỏ tới CA bundle của tổ chức bạn: finlens.client(ca_bundle="/đường/dẫn/ca.pem") hoặc đặt biến môi trường FINLENS_CA_BUNDLE.

---

Nâng cấp từ 0.1.x

Phiên bản 1.0 là bản viết lại và có thay đổi phá vỡ tương thích. Danh sách đầy đủ nằm ở CHANGELOG.md và tài liệu. Đáng chú ý nhất:

• Tên cột dùng snake_case — Date thành date.
• interval="1M" bị từ chối vì nhập nhằng giữa một tháng và một phút; dùng 1mo hoặc 1min.
• net_active_value() trước đây trả ba đơn vị khác nhau dưới cùng một tên cột; nay luôn là VND và có meta.value_unit khai rõ.
• Mọi tham số sau mã chứng khoán là keyword-only.

---

Tài liệu và hỗ trợ

• Tài liệu: docs.finlens.vn/python-sdk
• Changelog: CHANGELOG.md
• Trang chủ: finlens.vn
• Hỗ trợ: client@finlens.vn

Khi báo lỗi, kèm theo finlens.build_info() và request_id trong thông báo lỗi — hai thứ đó cho biết chính xác bản build nào và request nào.

>>> finlens.build_info()
{'version': '1.0.0', 'commit': '7284a30', 'built_at': '2026-08-04T09:53:47+00:00', ...}

---

Giấy phép

MIT — xem LICENSE.