Cấp tài khoản và giới hạn

Thư viện vnstock thế hệ 5 có một bộ tên hàm cho mọi người. Khoá API quyết định bạn gọi được hàm nào, dùng được nguồn nào và nhận về bao nhiêu dữ liệu. Trang này liệt kê đủ những điều đó cho từng cấp.

Ba cấp

Cấp	Điều kiện	Hàm và nguồn
Khách	Chưa đăng nhập, không có khoá API	42 tuyến dữ liệu, 6 nguồn, giới hạn chặt nhất
Cộng đồng	Đăng nhập bằng khoá API, chưa có gói tài trợ còn hạn	Cùng 42 tuyến và 6 nguồn như Khách, nhiều kỳ báo cáo hơn, trần dòng cao hơn
Tài trợ	Gói Bronze, Silver, Golden hoặc Diamond còn hạn	Mọi tuyến, mọi nguồn, báo cáo tài chính đủ chỉ tiêu

Khoá cấp Cộng đồng miễn phí cho cá nhân, học tập và nghiên cứu. Lấy khoá tại trang tài khoản, rồi đăng nhập một lần theo hướng dẫn ở Đăng nhập và dòng lệnh.

Bốn cấp tài trợ mở cùng một tập hàm và nguồn. Các cấp khác nhau ở độ lớn của hạn mức chung và số thiết bị. Chi tiết từng cấp ở trang chương trình tài trợ.

Xem mình đang ở cấp nào:

Python

import vnstock

print(vnstock.status()["tier"])   # "guest", "free", hoặc tên gói tài trợ

Giới hạn theo cấp

Giới hạn	Khách	Cộng đồng	Tài trợ
Tuyến dữ liệu	42 tuyến (bảng bên dưới)	42 tuyến, như Khách	Mọi tuyến
Nguồn (`source=`)	`kbs`, `vci`, `builtin`, `dukascopy`, `binance`, `vcb`	Như Khách	Mọi nguồn
Số kỳ báo cáo tài chính	4 kỳ gần nhất	8 kỳ gần nhất	Không giới hạn
Chỉ tiêu báo cáo tài chính	Rút gọn: chỉ chỉ tiêu cấp 1	Rút gọn: chỉ chỉ tiêu cấp 1	Đủ chỉ tiêu
Lịch sử nến 1 phút (`1m`)	180 ngày	180 ngày	Không giới hạn
Lịch sử nến `5m` tới `1H`	365 ngày	365 ngày	Không giới hạn
Lịch sử nến ngày, tuần, tháng	2.920 ngày (khoảng 8 năm)	2.920 ngày	Không giới hạn
Khớp lệnh trong phiên mỗi lần gọi	Tối đa 5.000 lệnh	Tối đa 5.000 lệnh	Không giới hạn
Trần dòng cho chuỗi theo thời gian	5.000 nến ngày	10.000 nến ngày	Không giới hạn
Danh mục tham chiếu	Không cắt	Không cắt	Không cắt

Cách đọc từng dòng:

Số kỳ báo cáo. income_statement, balance_sheet, cash_flow giữ các kỳ gần nhất. Hỏi period="quarter" ở cấp Khách thì nhận 4 quý gần nhất; hỏi theo năm thì nhận 4 năm.
Báo cáo rút gọn. Ở cấp Khách và Cộng đồng, ba báo cáo tài chính chính chỉ giữ chỉ tiêu cấp 1, không có các dòng chi tiết bên dưới và không có thuyết minh. Cấp tài trợ nhận đủ cây chỉ tiêu.
Lịch sử theo khung nến. Thư viện giữ phần mới nhất của chuỗi nến, lùi tối đa số ngày của khung đó. Hỏi nến ngày từ năm 2010 ở cấp Khách thì nhận khoảng 8 năm gần nhất.
Khớp lệnh. trades() trả 100 lệnh mới nhất khi bạn không ghi limit. Muốn nhiều hơn, truyền limit=, tối đa 5.000 ở cấp Khách và Cộng đồng. Mỗi nguồn còn có giới hạn riêng cho một lần truy vấn: nguồn vci (mặc định) nhận limit từ 1 tới 1.000 và phân trang qua last_id; cần nhiều lệnh trong một lần gọi thì dùng source="kbs".
Nhịp truy vấn. Khi một lời gọi hàm cần nhiều truy vấn tới nguồn (ví dụ lấy nhiều trang khớp lệnh), thư viện nghỉ giữa hai truy vấn liên tiếp: 1 giây ở cấp Khách và Cộng đồng, 0,1 giây ở cấp tài trợ. Một lời gọi gửi tối đa 50 truy vấn; vượt mức đó thì báo lỗi mã VNSTOCK_PROVIDER_REQUEST_BUDGET_INVALID trước khi gửi.
Trần dòng. Đây là lưới an toàn cuối cho các bảng dài theo thời gian, tính bằng số nến ngày. Với khung nhỏ hơn, thư viện quy đổi theo số nến trong một ngày giao dịch: 5.000 nến ngày tương đương 32.500 nến giờ, hay khoảng 1,95 triệu nến phút. Vì thế với nến phút, thứ giới hạn bạn là cửa sổ 180 ngày, không phải trần dòng. Nến tuần và tháng tính một đổi một.
Danh mục tham chiếu không bị cắt. Mọi hàm Reference() như danh sách mã, phân ngành, thành phần chỉ số trả đủ bảng ở mọi cấp. Ví dụ Reference().equity.list_by_industry() trả đủ 8.202 dòng ở cấp Khách (chạy ngày 10/10/2026).

42 tuyến mở cho Khách và Cộng đồng

Tên tuyến (cột đầu) là tên bạn thấy trong thông báo lỗi và trong df.attrs["route"]. Tên cũ của hàm, nếu có, ghi trong ngoặc. Mọi tuyến khác chỉ mở cho cấp tài trợ.

Market: giá và khớp lệnh

Tuyến	Hàm công khai	Nguồn dùng được ở hai cấp này
`market.equity.ohlcv`	`Market().equity(s).ohlcv` (`history`); cũng phục vụ `Market().etf(s).ohlcv`, `Market().bond(s).ohlcv`	`vci`, `kbs`
`market.equity.trades`	`Market().equity(s).trades` (`intraday`); cũng phục vụ ETF, trái phiếu	`vci`, `kbs`
`market.equity.quote`	`Market().equity(s).quote` (`price_board`), `Market().quote(symbols)`; cũng phục vụ ETF, trái phiếu	`kbs`, `vci`
`market.index.ohlcv`	`Market().index(s).ohlcv`	`kbs`, `vci`
`market.global_index.ohlcv`	`Market().index(s, scope="global").ohlcv`	`dukascopy`
`market.futures.ohlcv`	`Market().futures(s).ohlcv`	`kbs`, `vci`
`market.futures.quote`	`Market().futures(s).quote`	`kbs`
`market.futures.trades`	`Market().futures(s).trades`	`kbs`
`market.warrant.ohlcv`	`Market().warrant(s).ohlcv`	`kbs`, `vci`
`market.warrant.quote`	`Market().warrant(s).quote`	`kbs`
`market.warrant.trades`	`Market().warrant(s).trades`	`kbs`
`market.crypto.ohlcv`	`Market().crypto(s).ohlcv`	`binance`
`market.forex.ohlcv`	`Market().forex(s).ohlcv`	`dukascopy`
`market.commodity.ohlcv`	`Market().commodity(s).ohlcv`	`dukascopy`

Reference: danh mục và thông tin công ty

Tuyến	Hàm công khai	Nguồn dùng được ở hai cấp này
`reference.equity.list`	`Reference().equity.list`	`vci` (hàm không nhận `source=`)
`reference.market.symbols_by_exchange`	`Reference().equity.list_by_exchange` (`by_exchange`)	`vci`
`reference.market.symbols_by_group`	`Reference().equity.list_by_group` (`by_group`), `Reference().index.members`, `Reference().index(s).members`, `Reference().index.list_by_group`	`vci`, `kbs`
`reference.market.symbols_by_industries`	`Reference().equity.list_by_industry`	`vci`
`reference.market.industries_icb`	`Reference().industry.list`	`vci`
`reference.market.status`	`Reference().market.status`	`builtin`
`reference.index.list`	`Reference().index.list`	`builtin`
`reference.index.info`	`Reference().index(s).info`	`builtin`
`reference.index.groups`	`Reference().index.groups`	`kbs`
`reference.events.calendar`	`Reference().events.calendar`	`vci`
`reference.events.market`	`Reference().events.market`	`builtin`
`reference.search.symbol`	`Reference().search.symbol`	`dukascopy`
`reference.search.info`	`Reference().search.info`	`dukascopy`
`fundamental.company.info`	`Reference().company(s).info`	`vci`, `kbs`
`fundamental.company.overview`	`Reference().company(s).overview`	`vci`, `kbs`
`fundamental.company.officers`	`Reference().company(s).officers`	`vci`, `kbs`
`fundamental.company.shareholders`	`Reference().company(s).shareholders`	`vci`, `kbs`
`fundamental.company.ownership`	`Reference().company(s).ownership`	`kbs`, `vci`
`fundamental.company.subsidiaries`	`Reference().company(s).subsidiaries`	`vci`, `kbs`
`fundamental.company.affiliate`	`Reference().company(s).affiliate`	`vci`, `kbs`
`fundamental.company.capital_history`	`Reference().company(s).capital_history`	`kbs`, `vci`
`fundamental.company.events`	`Reference().company(s).events`	`vci`, `kbs`
`fundamental.company.insider_trading`	`Reference().company(s).insider_trading`	`kbs`, `vci`

Các tuyến fundamental.company.* nằm dưới Reference().company(s) nhưng không phải danh mục, nên vẫn chịu trần dòng của cấp. Reference().market.status() nhận thêm source="mas", nguồn đó chỉ dành cho cấp tài trợ.

Fundamental: báo cáo tài chính

Tuyến	Hàm công khai	Nguồn dùng được ở hai cấp này
`fundamental.equity.income_statement`	`Fundamental().equity(s).income_statement`	`vci`, `kbs`
`fundamental.equity.balance_sheet`	`Fundamental().equity(s).balance_sheet`	`vci`, `kbs`
`fundamental.equity.cash_flow`	`Fundamental().equity(s).cash_flow`	`vci`, `kbs`

Chỉ số tài chính (Fundamental().equity(s).ratio) và thuyết minh (.note) chỉ dành cho cấp tài trợ.

Retail

Tuyến	Hàm công khai	Nguồn dùng được ở hai cấp này
`retail.currency.exchange_rate`	`Retail().exchange_rate`	`vcb`
`retail.gold.price`	`Retail().gold`	Đã ngừng

retail.gold.price vẫn nằm trong danh sách của cấp nhưng hàm đã ngừng ở thế hệ 5: gọi Retail().gold() ở cấp nào cũng nhận UnsupportedError mã VNSTOCK_FEATURE_REMOVED. Vì vậy thực tế có 41 tuyến trả dữ liệu.

Những gì chỉ cấp tài trợ có, nói gọn:

Market: sổ lệnh, thống kê phiên, giao dịch thoả thuận, lô lẻ, khối lượng theo bước giá, dòng tiền nước ngoài và tự doanh, lịch sử giá (trade_history); quote, trades của chỉ số; trades của chỉ số thế giới, ngoại hối, hàng hoá; mọi hàm tiền mã hoá trừ ohlcv; sổ lệnh phái sinh, chứng quyền.
Reference: cơ cấu cổ đông (shareholders(mode="summary")), thông tin trái phiếu, hồ sơ hợp đồng tương lai và chứng quyền.
Fundamental: chỉ số tài chính, thuyết minh, kế hoạch năm, sức khoẻ tài chính.
Quỹ mở, Macro, Insights, Analytics.
Các nguồn vnd, mas, asean, cafef, digiinvest.

Khi kết quả bị cắt

Thư viện không cắt im lặng. Một kết quả bị rút ngắn theo cấp mang dấu trong df.attrs, và trong mỗi phiên chạy, lần đầu gặp mỗi loại cắt thì thư viện phát một UserWarning.

Khoá trong `df.attrs`	Nghĩa
`tier_cap_periods`	Số kỳ báo cáo được giữ
`tier_cap_level`	Có mặt (giá trị `1`) khi báo cáo đã được rút gọn còn chỉ tiêu cấp 1
`tier_cap_history_days`	Số ngày lịch sử được giữ của khung nến đang hỏi
`tier_cap_rows`	Số dòng được giữ: trần khớp lệnh, hoặc trần dòng đã quy đổi theo khung nến
`grant_cap_rows`	Trần dòng mỗi lần gọi ghi trong quyền sử dụng của tài khoản
`cap_tier`	Cấp đã áp phép cắt: `guest`, `free`…
`cap_rows_dropped`	Số dòng đã bỏ
`request_cap_rows`, `request_cap_window`	Không phải giới hạn của cấp: nguồn chỉ trả tối đa chừng ấy nến cho một lần truy vấn, áp cho mọi cấp. `request_cap_window` là số nến khoảng thời gian bạn chọn có thể chứa

Ví dụ ở cấp Khách, chạy ngày 10/10/2026:

Python

from vnstock import Fundamental

df = Fundamental().equity("FPT").income_statement(period="quarter")
print({k: v for k, v in df.attrs.items() if "cap" in k})
# {'cap_rows_dropped': 600, 'cap_tier': 'guest', 'tier_cap_periods': 4}

Cảnh báo đi kèm:

Text

Kết quả đã được giới hạn theo quyền của cấp Khách (chưa đăng nhập): chỉ gồm 4 kỳ báo cáo gần nhất.
Đã bỏ 600 dòng. Đăng nhập bằng khoá API để có giới hạn của cấp Cộng đồng: vnstock register
(https://vnstocks.com/account#api-key).

Nến ngày từ 2010 tới nay ở cùng cấp:

Python

from vnstock import Market

df = Market().equity("FPT").ohlcv(start="2010-01-01", end="2026-10-09")
print(len(df), {k: v for k, v in df.attrs.items() if "cap" in k})
# 1995 {'cap_rows_dropped': 2187, 'cap_tier': 'guest', 'tier_cap_history_days': 2920}

Muốn biến cảnh báo thành lỗi để chương trình dừng khi dữ liệu không đủ, kiểm df.attrs sau mỗi lời gọi:

Python

if any(k.startswith("tier_cap_") for k in df.attrs):
    raise RuntimeError(f"Kết quả bị cắt theo cấp: {dict(df.attrs)}")

Hàm hay nguồn ngoài cấp

Gọi một tuyến hay một nguồn chưa mở cho cấp của bạn thì nhận EntitlementError trước khi thư viện gửi bất kỳ truy vấn nào đi. Thư viện không tự đổi sang nguồn được phép.

Python

from vnstock import Fundamental
from vnstock.core.exceptions import EntitlementError

try:
    Fundamental().equity("FPT").ratio()
except EntitlementError as e:
    print(e.code)    # VNSTOCK_TIER_ROUTE
    print(e.route)   # fundamental.equity.ratio
    print(e.action_vi)

Mã	Khi nào
`VNSTOCK_TIER_ROUTE`	Tuyến không thuộc cấp của bạn, ví dụ `Fundamental().equity(s).ratio()` ở cấp Khách
`VNSTOCK_TIER_SOURCE`	Nguồn không thuộc cấp của bạn, ví dụ `ohlcv(..., source="mas")` ở cấp Khách

Danh sách mã lỗi đầy đủ ở Xử lý lỗi.

Hạn mức chung theo giờ, ngày, tháng

Ngoài các giới hạn trên dữ liệu, mỗi tài khoản có một hạn mức chung cho mọi thư viện Vnstock (vnstock, vnstock_quant, vnstock_news, vnstock_pipeline, cả bản 4.x), trên mọi thiết bị. Hạn mức chia theo giờ, ngày và tháng, giờ Việt Nam: giờ đặt lại ở đầu giờ, ngày lúc 00:00, tháng vào ngày 1. Mỗi thư viện trừ vào hạn mức theo mức riêng do Vnstock đặt. Bạn chỉ cần đọc phần trăm còn lại:

Shell

vnstock usage            # phần trăm còn lại của giờ, ngày, tháng và mốc đặt lại
vnstock usage --detail   # thêm số đo kỹ thuật của từng khung

Text

Hạn mức còn lại, cấp Bronze (dùng chung cho mọi thư viện và thiết bị):
  giờ này    [██████████████████··]  90%   đặt lại lúc 15:00
  hôm nay    [████████████████····]  80%   đặt lại 00:00 ngày 13/10
  tháng này  [███████████████████·]  96%   đặt lại ngày 01/11

Trang tài khoản hiện cùng con số. Máy của bạn biết phần các thiết bị khác đã dùng sau mỗi lần đồng bộ với vnstocks.com, vài phút một lần khi đang dùng. Với vnstock-auth trước 0.7, vnstock usage còn tính khung 24 giờ và 30 ngày gần nhất trên riêng máy đó.

Python

import vnstock

u = vnstock.usage()
u["tier"]       # cấp hiện tại
u["resets_at"]  # mốc đặt lại của hour, day, month
u["rule"]       # quyền lợi của cấp: tuyến, nguồn, số kỳ, số ngày lịch sử, trần dòng

Dùng hết một khung thì lời gọi tiếp theo nhận EntitlementError mã VNSTOCK_AUTH_HOUR_LIMIT, VNSTOCK_AUTH_DAY_LIMIT hoặc VNSTOCK_AUTH_MONTH_LIMIT, kèm mốc đặt lại. Mã theo giờ có retryable=True. Ngoài hạn mức, thư viện giữ nhịp gọi vừa phải trong từng phút để không dồn yêu cầu tới nguồn; gọi quá nhanh thì nhận VNSTOCK_AUTH_MINUTE_LIMIT, chờ vài giây rồi gọi lại.

Chính sách thay đổi mà không cần cài lại

Danh sách tuyến, nguồn và các con số trên trang này nằm trong một chính sách có chữ ký do vnstocks.com phát, không gắn cứng trong bản bạn cài. Thư viện tải lại chính sách tối đa khoảng 10 phút một lần, nên một tuyến mới được mở hay một nguồn bị tạm tắt có hiệu lực trên máy bạn sau chừng đó, không cần pip install lại. Bản chính sách đã tải dùng được trong một khoảng ngắn khi mất mạng; quá khoảng đó mà vẫn không tải được thì lời gọi dữ liệu báo NetworkError mã VNSTOCK_POLICY_UNAVAILABLE.

Xem chính sách đang áp trên máy:

Shell

vnstock policy

Text

Chính sách bản 1 từ vnstocks.com, ký lúc 16:10 ngày 10/10/2026, bản đang lưu dùng được tới 17:10 ngày 10/10/2026
Nguồn đang tắt: không
Máy chủ đang tắt: không
Quyền của cấp Khách (chưa đăng nhập): 42/117 chức năng

Vì chính sách đổi được, bảng 42 tuyến ở trên là ảnh chụp ngày 10/10/2026. vnstock policy và vnstock.usage()["rule"] luôn cho danh sách đang áp.

Hạn dùng của bản đang cài

Mỗi bản vnstock dùng được 365 ngày, tính từ ngày bản đó được duyệt cho tải. Hạn dùng áp cho mọi cấp.

Còn dưới 30 ngày, lời gọi dữ liệu đầu tiên trong mỗi tiến trình phát một FutureWarning nêu ngày hết hạn và lệnh cập nhật. Cảnh báo này không bao giờ làm lời gọi thất bại, kể cả khi bạn chạy với -W error.
Hết hạn thì mọi lời gọi dữ liệu báo UnsupportedError mã VNSTOCK_RELEASE_EXPIRED, kèm lệnh cập nhật. vnstock status, vnstock policy, vnstock register vẫn chạy.
Một bản cũng có thể bị tắt sớm từ vnstocks.com, ví dụ khi có lỗi nghiêm trọng. Lời gọi khi đó báo UnsupportedError mã VNSTOCK_RELEASE_DISABLED, kèm lý do.

Xem hạn của bản đang cài:

Python

import vnstock

r = vnstock.status()["release"]
print(r["version"], r["expires_on"], r["days_left"])

Cập nhật:

Shell

pip install -U --extra-index-url https://vnstocks.com/api/packages vnstock

Mục lục

Ba cấp

Giới hạn theo cấp

42 tuyến mở cho Khách và Cộng đồng

Market: giá và khớp lệnh

Reference: danh mục và thông tin công ty

Fundamental: báo cáo tài chính

Retail

Khi kết quả bị cắt

Hàm hay nguồn ngoài cấp

Hạn mức chung theo giờ, ngày, tháng

Chính sách thay đổi mà không cần cài lại

Hạn dùng của bản đang cài

Tags