Metadata-Version: 2.4
Name: finlens
Version: 1.0.1
Summary: Python client for Vietnamese stock market data — daily & intraday prices, investor flows and financial statements as pandas DataFrames.
Author: FinLens Team
License-Expression: MIT
Project-URL: Homepage, https://finlens.vn
Project-URL: Documentation, https://docs.finlens.vn/python-sdk
Project-URL: Changelog, https://docs.finlens.vn/python-sdk/changelog
Keywords: finlens,vietnam,vietnam-stock-market,vietnamese-stocks,stock-market-data,stock-api,financial-data,financial-statements,ohlcv,vnindex,pandas,market-data,api-client
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=3.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: packaging>=23.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: respx>=0.21; extra == "dev"
Requires-Dist: hypothesis>=6.100; extra == "dev"
Requires-Dist: ruff==0.16.1; extra == "dev"
Requires-Dist: mypy==2.3.0; extra == "dev"
Requires-Dist: pandas-stubs>=2.1; extra == "dev"
Requires-Dist: nox>=2024.4.15; extra == "dev"
Requires-Dist: pyyaml>=6.0; extra == "dev"
Requires-Dist: jinja2>=3.1; extra == "dev"
Provides-Extra: cache
Requires-Dist: pyarrow>=15.0; extra == "cache"
Dynamic: license-file

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

[![PyPI](https://img.shields.io/pypi/v/finlens.svg)](https://pypi.org/project/finlens/)
[![Python](https://img.shields.io/pypi/pyversions/finlens.svg)](https://pypi.org/project/finlens/)
[![License](https://img.shields.io/pypi/l/finlens.svg)](https://opensource.org/license/mit)

**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.*

```bash
pip install finlens
```

```python
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](#vì-sao-dùng-finlens)
- [Cài đặt và khoá API](#cài-đặt-và-khoá-api)
- [Lấy được những dữ liệu gì](#lấy-được-những-dữ-liệu-gì)
- [Đơn vị — đọc trước khi tính toán](#đơn-vị--đọc-trước-khi-tính-toán)
- [Tra cứu nhanh](#tra-cứu-nhanh)
- [Xử lý lỗi](#xử-lý-lỗi)
- [Async](#async)
- [Câu hỏi thường gặp](#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

```bash
pip install finlens
```

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

Lấy khoá API tại [finlens.vn](https://finlens.vn). Khoá có dạng `flk_...`.

```python
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.

```python
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)

```python
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

```python
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ư

```python
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

```python
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

```python
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.

```python
# 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:

```python
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`.

```python
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ý:

```python
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](https://docs.finlens.vn/python-sdk/changelog). Đá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](https://docs.finlens.vn/python-sdk)
- Changelog: [docs.finlens.vn/python-sdk/changelog](https://docs.finlens.vn/python-sdk/changelog)
- Trang chủ: [finlens.vn](https://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.

```python
>>> finlens.build_info()
{'version': '1.0.1', 'commit': 'a1b2c3d', 'built_at': '...', 'cython': '3.2.9', ...}
```

---

## Giấy phép

MIT — xem [toàn văn giấy phép](https://opensource.org/license/mit). File `LICENSE` cũng đi kèm trong gói.

<!--
Từ khoá: dữ liệu chứng khoán Việt Nam, chứng khoán Việt Nam Python, API chứng
khoán, thư viện Python chứng khoán, VNINDEX, VN30, VN30F1M, HOSE, HSX, HNX,
UPCOM, giá cổ phiếu lịch sử, dữ liệu intraday, tick by tick, khớp lệnh, khối
ngoại, dòng tiền nhà đầu tư, tự doanh, báo cáo tài chính, ngành ICB, chứng quyền
có bảo đảm, phái sinh, pandas, DataFrame, phân tích định lượng, backtest.
Vietnam stock market data Python, Vietnamese stocks API, HOSE HNX UPCOM data,
VNINDEX historical data, intraday tick data Vietnam, foreign investor flows,
financial statements Vietnam, pandas DataFrame, quantitative finance Vietnam.
-->
