Cấp tài khoản và giới hạn
Mục lục
Trang này viết cho phiên bản trước thế hệ 6 và được giữ để tra cứu. Phiên bản hiện hành là vnstock v6.0.1 — xem tài liệu v6.0.1 và hướng dẫn chuyển sang thế hệ 6.
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 | 8 tuyến để chạy thử, 3 nguồn, ít lượt gọi |
| Cộng đồng | Đăng nhập bằng khoá API, chưa có gói quyền sử dụng còn hạn | 42 tuyến, 6 nguồn, báo cáo tài chính 8 kỳ |
| Gói quyền sử dụng | 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 |
Cấp Khách dành cho lần chạy thử đầu tiên: lấy giá lịch sử, xem bảng giá, lấy danh sách mã, đọc hồ
sơ công ty. Muốn dùng tiếp, hay chạy trong một quy trình tự động, hãy đăng nhập bằng khoá API.
Từ bản phát hành sau 5.0.1, chạy trong một dịch vụ CI (GitHub Actions, GitLab CI…) luôn cần khoá
API: đặt khoá vào secret của CI với tên VNSTOCK_API_KEY. Cấp Cộng đồng dùng được 1 thiết bị, nên
máy CI dùng chung suất đó; chạy CI đều đặn trên nhiều máy thuộc các cấp quyền sử dụng.
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 quyền sử dụng 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 ở bảng giá các gói quyền sử dụng.
Xem mình đang ở cấp nào:
import vnstock
print(vnstock.status()["tier"]) # "guest", "free", hoặc tên gói quyền sử dụngGiới hạn theo cấp
| Giới hạn | Khách | Cộng đồng | Gói quyền sử dụng |
|---|---|---|---|
| Tuyến dữ liệu | 8 tuyến (bảng bên dưới) | 42 tuyến (bảng bên dưới) | Mọi tuyến |
Nguồn (source=) | vci, kbs, builtin | kbs, vci, builtin, dukascopy, binance, vcb | Mọi nguồn |
| Lượt gọi mỗi phút, giờ, ngày, tháng | 10, 100, 300, 1.000 | Theo hạn mức của tài khoản, xem vnstock usage | Theo cấp quyền sử dụng |
| Số kỳ báo cáo tài chính | Không có báo cáo tài chính | 8 kỳ gần nhất | Không giới hạn |
| Chỉ tiêu báo cáo tài chính | Không có | Rút gọn: chỉ chỉ tiêu cấp 1 | Đủ chỉ tiêu |
Lịch sử nến 1 phút (1m) | 30 ngày | 180 ngày | Không giới hạn |
Lịch sử nến 5m tới 1H | 90 ngày | 365 ngày | Không giới hạn |
| Lịch sử nến ngày, tuần, tháng | 365 ngày | 2.920 ngày (khoảng 8 năm) | Không giới hạn |
| Khớp lệnh trong phiên mỗi lần gọi | Không có | Tối đa 5.000 lệnh | Không giới hạn |
| Trần dòng cho chuỗi theo thời gian | 1.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 |
Số lượt gọi của cấp Khách áp từ bản thư viện phát hành sau 5.0.1. Bản 5.0.1 vẫn dùng số cũ của chính nó; phạm vi tuyến, nguồn và độ dài lịch sử thì áp cho mọi bản thế hệ 5.
Cách đọc từng dòng:
- Số kỳ báo cáo.
income_statement,balance_sheet,cash_flowgiữ các kỳ gần nhất. Hỏiperiod="quarter"ở cấp Cộng đồng thì nhận 8 quý gần nhất; hỏi theo năm thì nhận 8 năm. - Báo cáo rút gọn. Ở cấp 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 quyền sử dụng 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 Cộng đồng 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 ghilimit. Muốn nhiều hơn, truyềnlimit=, tối đa 5.000 ở cấp 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ồnvci(mặc định) nhậnlimittừ 1 tới 1.000 và phân trang qualast_id; cần nhiều lệnh trong một lần gọi thì dùngsource="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 quyền sử dụng. 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_INVALIDtrướ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 có hàm đó. Ví dụReference().equity.list_by_industry()trả đủ 8.202 dòng (chạy ngày 10/10/2026).
8 tuyến mở cho Khách
| Tuyến | Hàm công khai | Nguồn |
|---|---|---|
market.equity.ohlcv | Market().equity(s).ohlcv (history) | vci, kbs |
market.equity.quote | Market().equity(s).quote (price_board), Market().quote(symbols) | kbs, vci |
market.index.ohlcv | Market().index(s).ohlcv | kbs, vci |
reference.equity.list | Reference().equity.list | vci |
reference.index.list | Reference().index.list | builtin |
reference.market.symbols_by_group | Reference().equity.list_by_group (by_group), Reference().index.members | vci, kbs |
fundamental.company.info | Reference().company(s).info | vci, kbs |
fundamental.company.overview | Reference().company(s).overview | vci, kbs |
Gọi một hàm khác ở cấp Khách thì nhận EntitlementError kèm đường lấy khoá API. Thư viện không gửi
truy vấn nào đi trong trường hợp đó.
42 tuyến mở cho 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 quyền sử dụng.
Market: giá và khớp lệnh
| Tuyến | Hàm công khai | Nguồn dùng được |
|---|---|---|
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 |
|---|---|---|
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 quyền sử dụng.
Fundamental: báo cáo tài chính
| Tuyến | Hàm công khai | Nguồn dùng được |
|---|---|---|
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), thuyết minh (.note) và tài liệu công bố
(.filing, kể cả tải tệp) chỉ dành cho cấp quyền sử dụng.
Retail
| Tuyến | Hàm công khai | Nguồn dùng được |
|---|---|---|
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 quyền sử dụng 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,tradescủa chỉ số;tradescủ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, tài liệu công bố.
- 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ụ chạy ngày 10/10/2026, khi cấp Khách còn mở báo cáo tài chính với 4 kỳ (nay cấp Cộng đồng giữ 8 kỳ, cấp Khách không có báo cáo tài chính):
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:
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:
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:
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.
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 năm thư viện Vnstock
(vnstock, vnstock_quant, vnstock_news, vnstock_pipeline và vnstock_mcp, 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 lượt gọi công cụ được tính theo trọng số riêng do Vnstock đặt và hành vi sử dụng, chứ không
chỉ đếm số lần gọi; lượt gọi qua vnstock_mcp chỉ bị tính một lần, ở thư viện mà công cụ gọi tới.
Bạn chỉ cần đọc phần trăm còn lại:
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 khungHạ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/11Trang 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 đó.
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òngDù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:
vnstock policyChí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 Cộng đồng: 42/117 chức năngVì chính sách đổi được, bảng 42 tuyến ở trên là ảnh chụp ngày 18/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
FutureWarningnê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
UnsupportedErrormãVNSTOCK_RELEASE_EXPIRED, kèm lệnh cập nhật.vnstock status,vnstock policy,vnstock registervẫ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
UnsupportedErrormãVNSTOCK_RELEASE_DISABLED, kèm lý do.
Xem hạn của bản đang cài:
import vnstock
r = vnstock.status()["release"]
print(r["version"], r["expires_on"], r["days_left"])Cập nhật:
pip install -U --extra-index-url https://vnstocks.com/api/packages vnstock