Quyền dùng và hạn mức

vnstock_quant cấp quyền theo nhóm tính năng, không theo từng hàm. Bộ quy tắc do máy chủ Vnstock quyết định và gửi về máy bạn; thư viện chỉ thi hành. Trang này là bảng tra duy nhất về quyền và hạn mức; các trang nhóm hàm chỉ ghi một dòng "cần cấp nào" và trỏ về đây.

Thế hệ 6 không có hạn mức lượt gọi dữ liệu

Mọi phép tính của vnstock_quant chạy trên máy bạn. Tải dữ liệu qua vnstock 6 (ví dụ Dataset.load(), from_vnstock()) cũng không bị đếm lượt: dữ liệu đi thẳng từ Open API của nguồn tới máy bạn, bằng khoá của bạn. Tần suất gọi do từng nguồn giới hạn theo điều khoản của nguồn đó; xem Tần suất gọi của nguồn.

Nhóm tính năng theo cấp

Cấp được nhận diện trên máy: guest khi chưa đăng nhập, free với tài khoản Cộng đồng, rồi bronze, silver, golden, diamond theo gói quyền sử dụng. Hai cấp đầu có cùng quyền.

Nhóm tính năng	Mã trong `features`	Mở gì	Cộng đồng	Bronze	Silver trở lên
Chỉ báo kỹ thuật cơ bản	`ta_basic`	10 chỉ báo: SMA, EMA, RSI, MACD, Stoch, Bollinger Bands, ATR, OBV, VWAP, Pivots	Có, theo lượt thử	Có	Có
Chỉ báo kỹ thuật đầy đủ	`ta`	Đủ 58 chỉ báo của `vnstock_quant.ta`	Chưa mở	Chưa mở	Có
Chỉ số tài chính cơ bản	`fa_basic`	10 chỉ số: P/E, P/B, EPS, BVPS, ROE, ROA, biên lợi nhuận gộp và ròng, D/E, thanh toán hiện hành	Có, theo lượt thử	Có	Có
Chỉ số tài chính đầy đủ	`fa`	Đủ 100 chỉ số theo bốn mẫu ngành, tra công thức và kỳ dữ liệu	Chưa mở	Có	Có
Chỉ số tài chính mở rộng	`fa_advanced`	Dòng tiền theo CFA, DuPont, Altman Z, Piotroski F, Beneish M	Chưa mở	Có	Có
Rủi ro, giá điều chỉnh, vi cấu trúc	`risk`	`vnstock_quant.risk`, `vnstock_quant.prices`, `vnstock_quant.micro`	Chưa mở	Có	Có
Danh mục và định giá	`portfolio`	`vnstock_quant.portfolio`, `vnstock_quant.valuation`	Chưa mở	Có	Có
Backtest cơ bản	`bt_basic`	Một mã, bảng quy tắc với 10 chỉ báo cơ bản	Có, theo lượt thử	Có	Có
Backtest một mã đầy đủ	`bt`	Đủ chỉ báo trong bảng quy tắc, mọi chế độ khớp lệnh	Chưa mở	Có	Có
Backtest danh mục	`bt_portfolio`	Nhiều mã, tái cân bằng theo tỷ trọng	Chưa mở	Có	Có
Tối ưu và chống quá khớp	`bt_optimize`	Dò tham số, walk-forward, Monte Carlo	Chưa mở	Có	Có

Các cấp từ Silver trở lên khác nhau ở quy mô mỗi lần chạy (bảng bên dưới), không khác ở nhóm tính năng.

Kiểm tra cấp và nhóm tính năng của chính bạn mà không trừ lượt:

Python

import vnstock_quant as vq

status = vq.entitlement()
status["tier"], status["features"], status["policy_version"]
# ('free', ['ta_basic', 'fa_basic', 'bt_basic'], 'quant_entitlement_v3')

Lượt dùng thử của bản Cộng đồng

Bản Cộng đồng có hai bộ đếm lượt thử trong ngày, tách nhau và không liên quan đến việc tải dữ liệu. Lượt được đếm trên máy, không cần khoá API, và làm mới lúc 00:00 giờ Việt Nam.

	Chỉ báo và chỉ số (`vnstock_quant`)	Backtest (`vnstock_quant.backtest`)
Lượt mỗi ngày	30 phép tính, tính chung chỉ báo kỹ thuật và chỉ số tài chính	3 lần chạy
Số mã mỗi lần	3 mã mỗi lần tải báo cáo tài chính qua `vnstock`	1 mã mỗi lần chạy
Xem số còn lại	`vq.entitlement()["trial"]`	`vq.entitlement()["backtest"]["trial"]`
Khi hết	`QuotaExceededError`, mã `QUANT_TRIAL_EXHAUSTED`	như bên trái

Hai bộ đếm tách nhau vì backtest có hạn mức riêng do máy chủ đặt, để một lần chạy thử không làm hụt lượt tính chỉ báo trong ngày. Máy chủ có thể đổi số lượt hoặc số mã mà bạn không cần cập nhật thư viện; bảng trên là mức mặc định hiện hành.

Quy mô mỗi lần chạy thử

Từng cấp giới hạn độ lớn của một lần backtest. Vượt ngưỡng thì thư viện báo QuotaExceededError với mã QUANT_QUOTA_LIMIT trước khi tính, kèm ngưỡng của cấp bạn trong thông điệp.

Cấp	Mã trong một danh mục	Tổ hợp tham số mỗi lần dò	Đường mô phỏng Monte Carlo
Cộng đồng	1	10	200
Bronze	10	100	1.000
Silver	30	1.000	5.000
Golden	100	10.000	20.000
Diamond	400	50.000	100.000

Xem các ngưỡng đang áp dụng cho bạn ở vq.entitlement()["backtest"]["quota"]. Các ngưỡng này áp dụng như nhau khi gọi bằng Python và khi gọi bằng JSON (bt.call("run_portfolio", ...), "sweep", "walk_forward", "monte_carlo"); deflated_sharpe_ratio không cần quyền riêng.

Số mã mỗi lần tải báo cáo tài chính

fa.Dataset.load() giới hạn số mã một lần gọi theo cấp: Cộng đồng 3, Bronze 100, Silver 400, Golden và Diamond không giới hạn. Vượt ngưỡng thì gặp TierRequiredError với mã QUANT_SCOPE_LIMIT. Đây là quyền gọi hàm, không phải cam kết tải được chừng ấy mã trong một lần: tốc độ tải do nguồn quyết định (mục dưới).

Tần suất gọi của nguồn

Mỗi nguồn giới hạn tần suất gọi theo điều khoản riêng; vnstock_quant và vnstock không nới được giới hạn đó. Khi nguồn từ chối vì gọi quá nhanh, lời gọi báo lỗi VNSTOCK_SOURCE_RATE_LIMITED. Đo ngày 06/11/2026: tải đủ báo cáo năm và quý của một mã (period="both") cần khoảng 54 lần gọi và mất khoảng 90 giây; tải mã thứ hai ngay sau đó đã bị nguồn từ chối, chờ vài phút thì chạy lại được.

Tải từng mã, lưu kết quả ra đĩa rồi dùng lại.
Chỉ cần số năm thì dùng period="year" (khoảng một phần ba số lần gọi).
Để vnstock_pipeline tải và lưu theo lịch nếu cần nhiều mã.

Khi quyền không đủ

Tình huống	Ngoại lệ	Mã
Nhóm tính năng chưa mở ở cấp hiện tại	`TierRequiredError`	`QUANT_TIER_REQUIRED`
Quá số mã cho phép của cấp	`TierRequiredError`	`QUANT_SCOPE_LIMIT`
Hết lượt thử trong ngày	`QuotaExceededError`	`QUANT_TRIAL_EXHAUSTED`
Một lần chạy thử quá lớn cho cấp	`QuotaExceededError`	`QUANT_QUOTA_LIMIT`
Không kiểm tra được quyền (khoá, thiết bị, mạng)	`AuthError`	theo `kind`
Nguồn từ chối vì gọi quá nhanh	lỗi của `vnstock`	`VNSTOCK_SOURCE_RATE_LIMITED`

Thuộc tính action của ngoại lệ nói việc nên làm tiếp. Cây ngoại lệ đầy đủ ở Quy ước dữ liệu và lỗi. Phạm vi từng gói quyền sử dụng: Bảng giá.

Đọc tiếp

Cài đặt và thiết lập — Đọc đủ các trường của vq.entitlement().
Cấp quyền và xử lý lỗi của backtest — Ví dụ bắt lỗi quyền khi chạy thử chiến lược.
Tải dữ liệu bằng vnstock — Điểm vào tải dữ liệu và nguồn đọc được.