Chuyển từ vnstock 4.x

Trang này dành cho bạn đang có mã viết cho thư viện vnstock 4.x, bản Cộng đồng. Thế hệ 5 vẫn tên vnstock, vẫn có Market, Reference, Fundamental, nên phần lớn mã viết theo giao diện hợp nhất của 4.x chạy được sau vài chỗ sửa. Mã viết theo kiểu Vnstock().stock(...) thì phải viết lại.

Việc cần làm, theo thứ tự:

1. Cài thế hệ 5 vào một môi trường ảo mới.
2. Đăng nhập lại bằng khoá API.
3. Thay các tên đã bỏ (Vnstock, các hằng, các hàm khoá).
4. Rà lại tham số và cột đầu ra ở những chỗ mã của bạn phụ thuộc.
5. Đổi except Exception thành bắt đúng lớp lỗi.

1. Cài đặt

Thế hệ 5 nằm trên kho thư viện của vnstocks.com, không nằm trên PyPI. Lệnh pip install -U vnstock trơn sẽ lấy lại bản 4.x từ PyPI, nên lệnh cài phải kèm kho thư viện của vnstocks.com:

python3 -m venv ~/.venv5x
source ~/.venv5x/bin/activate    # Windows: py -m venv "$HOME\.venv5x"; & "$HOME\.venv5x\Scripts\Activate.ps1"
pip install -U --extra-index-url https://vnstocks.com/api/packages vnstock
vnstock version                          # kiểm phiên bản đã cài
vnstock doctor                           # bảy phép kiểm môi trường

Thế hệ 5 cần Python 3.10 trở lên và chỉ phụ thuộc pandas. Không cần cài thêm vnai.

Bản 4.x và thế hệ 5 cùng tên gói, nên cài chung một môi trường thì bản sau đè bản trước. Giữ mã cũ chạy song song bằng cách để mỗi bản một môi trường ảo.

Bạn cần sửa gì: đổi lệnh cài trong README, notebook, Dockerfile, CI của bạn sang lệnh trên.

2. Đăng nhập và cấp quyền

Ba hàm khoá cũ chuyển sang lệnh vnstock

# 4.x
from vnstock import register_user
register_user()

# Thế hệ 5
import os
import vnstock

vnstock.login(os.environ["VNSTOCK_API_KEY"])   # một lần trên mỗi máy
print(vnstock.status())

Khoá lưu trên máy sau lần đăng nhập đầu, đã mã hoá trong ~/.vnstock/auth/. Máy đã từng nhập khoá cho bản 4.x (tệp ~/.vnstock/api_key.json) thì thế hệ 5 nhập khoá đó vào kho mã hoá ở lần chạy đầu, một lần duy nhất; sau đó sửa tệp cũ không đổi được khoá của thế hệ 5. Chạy vnstock status để kiểm; nếu báo "Khách" hoặc sai cấp, đăng nhập lại bằng vnstock register. Lấy khoá tại trang tài khoản. Các lệnh còn lại xem ở Đăng nhập và dòng lệnh.

Ba cấp người dùng

Nhóm hàm của Khách và Cộng đồng gồm: giá lịch sử của cổ phiếu, chỉ số, phái sinh, chứng quyền; bảng giá và khớp lệnh của cổ phiếu, phái sinh, chứng quyền; thông tin công ty; ba báo cáo tài chính; danh sách mã và phân ngành; danh sách chỉ số, nhóm chỉ số và thông tin từng chỉ số (Reference().index.list(), .groups(), Reference().index("VN30").info()); trạng thái thị trường (Reference().market.status()); tìm kiếm mã; giá ngoại hối, hàng hoá thế giới, chỉ số thế giới, tiền mã hoá; tỷ giá ngân hàng.

Hai điểm khác bản 4.x mà người dùng Cộng đồng sẽ gặp:

• Fundamental().equity(symbol).ratio() cần cấp tài trợ.
• Dữ liệu quỹ mở (Fund(), Reference().fund, Market().fund) cần cấp tài trợ từ Bronze, xem Dữ liệu quỹ mở.

Gọi hàm ngoài cấp của mình thì nhận EntitlementError, mã VNSTOCK_TIER_ROUTE (hàm chưa mở) hoặc VNSTOCK_TIER_SOURCE (nguồn chưa mở). Thư viện không gửi truy vấn nào đi trong trường hợp này.

Mỗi cấp có giới hạn về số kỳ báo cáo, độ dài lịch sử và số dòng mỗi lần gọi. Khi kết quả bị cắt, thư viện phát một cảnh báo cho mỗi loại cắt trong một phiên chạy, và ghi con số vào df.attrs (các khoá bắt đầu bằng tier_cap_). Báo cáo tài chính ở cấp Khách và Cộng đồng chỉ có các chỉ tiêu cấp 1. Xem con số hiện hành của cấp mình bằng vnstock usage.

Ba giới hạn hay gặp, giữ ngang bản 4.x:

• Danh mục không bị cắt. Reference().equity.list_by_industry(), Reference().industry.sectors() và các danh sách mã khác trả đủ mọi dòng ở mọi cấp.
• Khớp lệnh trong phiên tối đa 5.000 dòng ở cấp Khách và Cộng đồng. Market().equity(s).trades() (hay intraday()) mặc định trả 100 lệnh mỗi lần gọi (tối đa 1.000 lệnh trên nguồn VCI, hỗ trợ phân trang qua last_id); cần lấy nhiều hơn một lần thì truyền source="kbs" cùng limit=, ví dụ trades(limit=5000, source="kbs").
• Trạng thái thị trường (Reference().market.status()) tính ngay trên máy từ lịch giao dịch và lịch nghỉ có sẵn trong thư viện, như bản 4.x, nên mọi cấp đều gọi được và không có truy vấn nào gửi đi.

3. Tên đã bỏ và tên thay thế

Các tên dưới đây không còn ở gốc gói. from vnstock import <tên> báo ImportError kèm lời chỉ đường song ngữ, nên bạn biết ngay phải thay bằng gì.

Các tên thay ở bảng trên dùng được ở mọi cấp, kể cả Khách.

Thế hệ 5 tập trung vào việc chuẩn hoá dữ liệu, nên bỏ hai phần phụ của 4.x: lớp gửi tin nhắn vnstock.bot và thuộc tính vẽ biểu đồ df.viz. Mã dùng chúng nhận UnsupportedError mã VNSTOCK_FEATURE_REMOVED, kèm cách làm thay:

Ví dụ phổ biến nhất, lấy giá lịch sử:

# 4.x
from vnstock import Vnstock

stock = Vnstock().stock(symbol="FPT", source="VCI")
df = stock.quote.history(start="2024-01-01", end="2024-03-31", interval="1D")

# Thế hệ 5
from vnstock import Market

df = Market().equity("FPT").ohlcv(start="2024-01-01", end="2024-03-31", interval="1D")

Báo cáo tài chính và thông tin công ty:

# 4.x
stock = Vnstock().stock(symbol="FPT", source="VCI")
bs = stock.finance.balance_sheet(period="year")
profile = stock.company.overview()

# Thế hệ 5
from vnstock import Fundamental, Reference

bs = Fundamental().equity("FPT").balance_sheet(period="year")
profile = Reference().company("FPT").info()

Các lớp kiểu cũ Quote, Listing, Company, Finance, Trading vẫn import được từ vnstock để mã cũ chạy tiếp. Chúng trả cột thô như tài liệu bản Mở rộng mô tả, ví dụ Listing().all_symbols() có organ_name, Company("FPT").officers() có officer_name. Một số cột của bản cũ chưa có; thư viện bỏ hẳn cột đó chứ không điền giá trị đoán. Nhóm lớp này sẽ ngừng dần, nên mã mới hãy gọi thẳng Market, Reference, Fundamental.

Quote(...).history(length=N) vẫn hiểu N là số ngày như trước. Ở giao diện hợp nhất, length=N là số nến (xem mục 5).

4. Tính năng đã ngừng

Những hàm sau vẫn còn tên, nhưng khi gọi thì báo UnsupportedError mã VNSTOCK_FEATURE_REMOVED, kèm phiên bản bắt đầu ngừng và gợi ý nếu có.

Retail().exchange_rate() (tỷ giá Vietcombank) vẫn chạy như cũ, mở cho mọi cấp người dùng.

Quỹ mở không ngừng, nhưng đổi nguồn và đổi điều kiện: dữ liệu lấy từ CafeF và DigiInvest, chỉ dành cho cấp tài trợ từ Bronze. Tên cũ Fund().listing(), Fund().top_holding()… vẫn trả dữ liệu với bộ cột cũ, kèm FutureWarning, tới hết ngày 06/04/2027. Chi tiết ở Dữ liệu quỹ mở.

Bắt lỗi ngừng hỗ trợ để mã không dừng giữa chừng:

from vnstock import Retail
from vnstock.core.exceptions import UnsupportedError

try:
    gold = Retail().gold()
except UnsupportedError as e:
    if e.code == "VNSTOCK_FEATURE_REMOVED":
        gold = None   # bỏ bước này
    else:
        raise

5. Tham số

interval

Thế hệ 5 nhận mọi cách viết khung nến mà bản 4.x và vnstock_data từng nhận. Không phân biệt chữ hoa, chữ thường, trừ M (tháng) và m (phút).

Cổ phiếu và chỉ số trong nước không có khung 4 giờ; nguồn sẽ báo lỗi nếu bạn hỏi khung này.

interval="m" là nến 1 phút ở mọi nguồn, interval="M" là nến tháng, giống bản Mở rộng. Ở bản 4.x, khi nguồn là KBS (mặc định của giao diện hợp nhất), m lại là nến tháng. Mã 4.x nào viết interval="m" để lấy nến tháng thì đổi thành interval="1M".

source

source= có tác dụng thật: hỏi nguồn nào thì nhận dữ liệu từ nguồn đó, hoặc nhận lỗi nếu hàm không có nguồn ấy. Thư viện không tự đổi sang nguồn khác khi nguồn bạn chọn lỗi. Viết hoa hay thường đều được ("VCI" và "vci" như nhau). Danh sách nguồn từng hàm ở Nguồn dữ liệu.

Các nguồn của 4.x không còn: msn, tcbs, fmp, dnse. Truyền chúng vào, hoặc gõ sai tên nguồn, thì nhận UnsupportedError nêu tên các nguồn dùng được cho đúng hàm đó, không nhận dữ liệu của nguồn khác. Tiền mã hoá chỉ có nguồn binance; truyền nguồn khác cho Market().crypto(...) cũng nhận lỗi chỉ sang source="binance".

Khoảng thời gian

Ngày nhận ba dạng: YYYY-MM-DD, YYYY-MM (hiểu là ngày đầu tháng) và YYYY (ngày đầu năm). Dạng khác như 01-09-2026 hay 2026/09/01 nhận InputError, vì đọc theo kiểu nào cũng có thể sai ngày. Truyền rõ start và end là cách chắc nhất để nhận đúng khoảng bạn muốn.

Không truyền start thì thư viện đếm theo số nến, giống bản 4.x:

• ohlcv() không đối số trả 100 nến mới nhất của khung đang hỏi.
• length=N (số nguyên, hoặc chuỗi chữ số như "150") là N nến của khung đang hỏi. length=100, interval="1m" là 100 nến một phút, không phải 100 ngày. count_back=N cũng vậy.
• length dạng chuỗi kỳ ("10d", "3M", "1Y") là một khoảng thời gian, khung nào cũng vậy.
• limit=N khi không có start là N nến mới nhất.

Bản Mở rộng vnstock_data hiểu length=N là N ngày. Nếu bạn từng dùng cả hai bản, đọc thêm Chuyển từ vnstock_data 3.x.

from vnstock import Market

eq = Market().equity("FPT")
df = eq.ohlcv(start="2026-09-01", end="2026-09-30", interval="1D")   # cách khuyên dùng
df = eq.ohlcv("2026-09-01", "2026-09-30", "1W")                     # theo vị trí cũng được
df = eq.ohlcv()                                                     # 100 nến ngày mới nhất
df = eq.ohlcv(length=30, interval="1H")                             # 30 nến giờ mới nhất
df = eq.ohlcv(length="3M")                                          # 3 tháng gần nhất

Báo cáo tài chính: luôn ghi tên tham số

Thế hệ 5 theo chữ ký của bản Mở rộng: tham số vị trí đầu tiên của income_statement, balance_sheet, cash_flow là loại hình doanh nghiệp (com_type), không phải kỳ báo cáo. Viết income_statement("quarter") như bản 4.x sẽ nhận InputError. Ghi rõ tên:

from vnstock import Fundamental

fin = Fundamental().equity("FPT")
fin.income_statement(period="quarter")
fin.income_statement(period="Q")      # viết tắt, như "quarter"

period nhận year và quarter, viết tắt Y và Q, chữ hoa hay thường đều được.

6. Đầu ra

Ngày, kiểu dữ liệu, khung rỗng

• Ngày nằm ở cột (time, date, report_date…), không nằm ở index.
• Cột chữ có kiểu string, giá có kiểu float64, thời gian có múi giờ: Asia/Ho_Chi_Minh cho dữ liệu Việt Nam, UTC cho tiền mã hoá, ngoại hối, hàng hoá thế giới.
• Ô trống là <NA> hoặc NaN, không phải chuỗi rỗng.
• Không có dữ liệu thì nhận bảng rỗng vẫn đủ cột.
• df.attrs["source"] cho biết dữ liệu lấy từ nguồn nào.

So sánh thời gian có múi giờ với một chuỗi ngày trơn có thể không ra kết quả bạn muốn. Hai cách sửa:

import pandas as pd
from vnstock import Market

df = Market().equity("FPT").ohlcv(start="2026-09-01", end="2026-09-30")

# Lọc theo ngày lịch
day = df[df["time"].dt.date == pd.Timestamp("2026-09-04").date()]

# Hoặc bỏ múi giờ nếu mã cũ cần thời gian không múi
df["time"] = df["time"].dt.tz_localize(None)

Hàm danh sách trả DataFrame

Reference().equity.list_by_group(), Reference().index.members(), Reference().etf.list(), Reference().futures.list() trả DataFrame một cột symbol, không trả Series như bản 4.x. Lấy danh sách mã:

from vnstock import Reference

vn30 = Reference().equity.list_by_group("VN30")["symbol"].tolist()

Đây là cách trả của bản Mở rộng. Các lớp kiểu cũ như Listing().symbols_by_group() vẫn trả Series như trước.

Cột đổi tên hoặc bớt

Thế hệ 5 dùng bộ tên cột của bản Mở rộng cho mọi cấp, để mã của người tài trợ không phải đổi theo. Mã viết cho 4.x thì cần đổi tên cột ở những chỗ đọc cột theo tên. Những chỗ hay gặp:

Báo cáo tài chính dạng dài

Báo cáo tài chính mặc định trả dạng dài: mỗi dòng là một chỉ tiêu của một kỳ, cột period, id, name, order, level, unit, value. Muốn dạng rộng như bản 4.x (mỗi kỳ một cột), truyền format="wide". Tham số cũ orient= vẫn được hiểu.

from vnstock import Fundamental

fin = Fundamental().equity("FPT")
long_df = fin.income_statement(period="year")                    # dạng dài, mặc định
wide_df = fin.income_statement(period="year", format="wide")     # mỗi kỳ một cột

Dạng dài là mặc định của bản Mở rộng, và thế hệ 5 giữ như vậy cho mọi cấp.

7. Nguồn mặc định đã đổi

Giao diện hợp nhất của thế hệ 5 lấy nguồn mặc định theo bản Mở rộng, không theo bản 4.x. Vì vậy nhiều hàm đổi nguồn mặc định. Số liệu có thể lệch nhỏ so với trước, nhất là giá điều chỉnh quanh ngày chia cổ tức, tách cổ phiếu. Muốn giữ nguồn cũ ở hàm có tham số source, truyền nó vào, hoặc đặt một lần cho cả chương trình bằng set_route():

from vnstock.ui.config import set_route

# Từ đây, ohlcv của cổ phiếu lấy từ KBS khi lời gọi không ghi source=
set_route("market.equity.ohlcv", "kbs", "quote", "Quote", "history")

Thứ tự chọn nguồn: source= của lời gọi, rồi nguồn đặt bằng set_route(), rồi nguồn mặc định. set_route() chỉ nhận nguồn có sẵn trong thư viện; ba đối số cuối giữ cho tương thích và không được dùng.

Khớp lệnh cổ phiếu là chỗ duy nhất thế hệ 5 lấy nguồn khác bản Mở rộng: VCI, trong khi bản Mở rộng lấy VND.

Market().index(symbol, scope="global") (chỉ số thế giới) vẫn có, nhưng đổi nguồn từ MSN sang Dukascopy như bản Mở rộng, và thời gian theo UTC. Khi nguồn từ chối truy cập tự động, lời gọi báo ChallengeRequiredError (mã VNSTOCK_SOURCE_CHALLENGE) và thư viện không thử lại. Giá ngoại hối và hàng hoá thế giới lấy qua Market().forex(), Market().commodity().

8. Lỗi có kiểu

Thế hệ 5 luôn ném ngoại lệ có kiểu, không in lỗi rồi trả None. Mọi ngoại lệ đều kế thừa VnstockError. Mỗi ngoại lệ có code (mã ổn định để rẽ nhánh), kind, action (việc nên làm tiếp), message_vi, message_en.

AccessDeniedError, RateLimitedError và ChallengeRequiredError là lớp con của NetworkError. InputError đồng thời là lớp con của ValueError, nên except ValueError trong mã cũ vẫn bắt được lỗi mã sai hay tham số sai.

Mã không tồn tại thì nhận InputError. Mã có thật nhưng khoảng thời gian bạn hỏi không có giao dịch thì vẫn nhận bảng rỗng đủ cột.

from vnstock import Market
from vnstock.core.exceptions import (
    EntitlementError, InputError, NetworkError, VnstockError,
)

try:
    df = Market().equity("FPT").ohlcv(start="2026-09-01", end="2026-09-30")
except EntitlementError as e:
    print("Cấp hiện tại chưa mở:", e.code)
except InputError as e:
    print("Tham số sai:", e.message_vi)
except NetworkError as e:
    print("Lỗi kết nối:", e.code, e.action)
except VnstockError as e:
    print("Lỗi khác:", e.code)

Thông báo hai ngôn ngữ

Lỗi, cảnh báo và đầu ra dòng lệnh hiện cả tiếng Việt lẫn tiếng Anh, tiếng Việt trước. Chọn một ngôn ngữ:

vnstock settings language vi      # chỉ tiếng Việt
vnstock settings language en      # chỉ tiếng Anh
vnstock settings language both    # cả hai (mặc định)
VNSTOCK_LANG=en python script.py  # chỉ cho một lần chạy

Mã nào đang so str(e) với một câu tiếng Anh cố định thì đổi sang đọc e.message_en, hoặc tốt hơn là so e.code.

Chạy trên Google Colab

Một số nguồn chặn dải địa chỉ dùng chung của dịch vụ đám mây. Trên Google Colab, bạn có thể gặp AccessDeniedError (HTTP 403) dù mã đúng. Thông báo lỗi khi đó nói rõ bạn đang chạy trên Colab và gợi ý chạy cùng đoạn mã trên máy của mình (Python hoặc Jupyter cài trên máy). Chờ rồi thử lại thường không giúp được.

Bản 4.x tự đổi nguồn phân ngành sang KBS khi chạy trên Colab. Thế hệ 5 không đổi nguồn theo môi trường.

9. Thời hạn tương thích

Sau ngày ghi trong bảng, phần cũ báo lỗi thay vì trả dữ liệu. Python hiện FutureWarning theo mặc định, nên bạn sẽ thấy cảnh báo ngay trong notebook.

Mỗi bản thư viện còn có hạn dùng riêng, xem ở Đăng nhập và dòng lệnh.

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

Mã 4.x của tôi chỉ dùng Market, Reference, Fundamental. Có cần sửa không? Ít. Rà mục 5 (tham số) và mục 6 (cột đầu ra) ở những chỗ mã của bạn đọc cột theo tên.

Tôi không muốn đăng nhập. Thư viện vẫn chạy ở cấp Khách với giới hạn chặt hơn. Khoá cấp Cộng đồng miễn phí cho cá nhân, học tập và nghiên cứu.

Số liệu giá khác bản 4.x vài đồng. Nguồn mặc định của giá lịch sử cổ phiếu đổi từ KBS sang VCI. Hai nguồn điều chỉnh giá sau sự kiện quyền theo cách khác nhau. Truyền source="kbs" để nhận số như trước.

Dữ liệu truy xuất qua thư viện đến từ nguồn bên thứ ba và chỉ để tham khảo. Hãy tự kiểm tra trước khi dùng cho quyết định của mình.