Dữ liệu thị trường

Lớp Market() gom các hàm truy xuất dữ liệu giao dịch: giá lịch sử theo nến, danh sách lệnh khớp, bảng giá, sổ lệnh, thống kê phiên. Bạn chọn loại tài sản trước, rồi gọi hàm:

from vnstock import Market

mkt = Market()
mkt.equity("FPT").ohlcv()                 # 100 nến ngày mới nhất của FPT
mkt.index("VNINDEX").ohlcv(length="3M")   # VNINDEX ba tháng gần nhất
mkt.quote(["FPT", "VCB"])                 # bảng giá nhiều mã một lần

Trang này nói về tài sản trong nước. Phần khác nằm ở trang riêng:

• Quỹ mở Market().fund(symbol): Dữ liệu quỹ mở.
• Tiền mã hoá, ngoại hối, hàng hoá và chỉ số thế giới Market().index(symbol, scope="global"): Tài sản quốc tế.
• Trạng thái phiên giao dịch (đang mở cửa hay nghỉ): Reference().market.status(), xem Tham chiếu.
• Định giá P/E, P/B toàn thị trường: Analytics.

Tóm tắt

Cột "Cấp" theo quy tắc ở Cấp quyền và giới hạn. Mọi cấp là Khách (không khoá), Cộng đồng và Tài trợ. Tài trợ là từ Bronze trở lên.

Ở cấp Khách và Cộng đồng, các hàm mở cho mọi cấp chỉ nhận nguồn kbs và vci. Gọi source="vnd", "mas" hay "asean" thì nhận EntitlementError mã VNSTOCK_TIER_SOURCE. Gọi hàm dành cho tài trợ thì nhận EntitlementError mã VNSTOCK_TIER_ROUTE. Trong cả hai trường hợp thư viện không gửi truy vấn nào đi.

1. Tham số chung

Mã và chữ hoa

Mã viết hoa hay thường đều được: "fpt" và "FPT" như nhau. Market() nhận vài tham số (index, random_agent, show_log) chỉ để mã cũ chạy được; chúng không đổi kết quả của các hàm trên trang này.

Cửa sổ thời gian của ohlcv()

ohlcv() của mọi loại tài sản trên trang này có cùng chữ ký:

ohlcv(start=None, end=None, interval="1D", *, limit=None, source=None,
      count_back=None, length=None, floating=2)

Thư viện chọn khoảng dữ liệu theo thứ tự sau:

Một con số ở length là số nến, không phải số ngày. length=100, interval="1m" là 100 nến một phút, không phải 100 ngày. Muốn tính theo ngày thì viết có đơn vị: length="100d".

Đơn vị của length dạng khoảng thời gian: d (ngày), W (tuần), M (tháng), Y (năm). Thư viện đổi ra ngày lịch: "30d" là 30 ngày, "2W" là 14, "3M" là 90, "1Y" là 365. Với length, "6m" viết thường vẫn là sáu tháng (180 ngày).

start nhận YYYY-MM-DD. YYYY-MM và YYYY được hiểu là ngày đầu tháng, đầu năm ("2026-10" là "2026-10-01"). Cách viết khác báo InputError. end mặc định là hôm nay theo giờ Việt Nam (UTC+7), không theo đồng hồ máy bạn, nên máy chủ đặt giờ UTC vẫn lấy đúng ngày.

fpt = Market().equity("FPT")

fpt.ohlcv()                                   # 100 nến ngày mới nhất
fpt.ohlcv(start="2026-10-01", end="2026-10-09")
fpt.ohlcv(start="2026-10")                    # từ 01/10/2026 tới hôm nay
fpt.ohlcv(length=5, interval="1m")            # 5 nến một phút mới nhất
fpt.ohlcv(count_back=2, interval="5m")        # 2 nến năm phút mới nhất
fpt.ohlcv(length="30d")                       # nến ngày trong 30 ngày lịch gần nhất
fpt.ohlcv(length="3d", interval="1H")         # nến giờ trong 3 ngày gần nhất

Chạy ngày 10/10/2026, fpt.ohlcv(length="30d") trả 22 nến, từ 10/09 tới 09/10/2026.

Khung nến interval

1m (phút, chữ thường) khác 1M (tháng, chữ hoa). Cách viết ngoài bảng, ví dụ "1min", "2H", báo InputError mã VNSTOCK_INPUT_INTERVAL. Bảng đầy đủ xem bằng:

from vnstock._core import get_interval_aliases, normalize_interval

normalize_interval("daily")    # '1D'

Thư viện còn nhận 4H, nhưng nguồn vci không có khung này và báo UnsupportedError mã VNSTOCK_VCI_INTERVAL_UNAVAILABLE.

Nến tuần và nến tháng mang ngày của phiên cuối trong tuần, trong tháng. Nến của tháng đang chạy mang ngày phiên gần nhất (chạy ngày 10/10/2026, nến tháng 10 mang ngày 09/10/2026).

Nến trong phiên lấy từ nguồn nào

Chỉ số, hợp đồng tương lai, chứng quyền, ETF và trái phiếu có nguồn mặc định kbs. Khi bạn không ghi source= và hỏi nến trong phiên (1m, 5m, 15m, 30m, 1H), thư viện lấy từ vci, vì nguồn này giữ lịch sử nến phút dài hơn. Nến ngày, tuần, tháng vẫn lấy từ kbs. Cổ phiếu lấy ohlcv từ vci ở mọi khung. Nguồn thực tế của một kết quả nằm ở df.attrs["source"].

Các tham số khác của ohlcv()

Một truy vấn tới nguồn trả tối đa 20.000 nến. Cửa sổ dài hơn thì thư viện giữ các nến mới nhất, ghi df.attrs["request_cap_rows"] và phát cảnh báo. Giới hạn này đến từ nguồn, không phải từ cấp.

Cột trả về của ohlcv()

Mọi loại tài sản trên trang này trả cùng sáu cột:

Đơn vị giá: cổ phiếu, ETF và chứng quyền tính bằng nghìn đồng (57.9 là 57.900 đồng); chỉ số và hợp đồng tương lai tính bằng điểm. Giá cổ phiếu là giá đã điều chỉnh theo sự kiện quyền, nên nến cũ có thể có hai chữ số lẻ (67.08).

Nến ngày mang giờ 07:00+07:00. Muốn lấy riêng ngày, dùng df["time"].dt.date.

df.attrs mang source, symbol, interval, start, end, length của lời gọi.

Giới hạn theo cấp

Khi cấp cắt bớt, thư viện giữ phần mới nhất, ghi lý do vào df.attrs (tier_cap_history_days hoặc tier_cap_rows) và phát cảnh báo. Trần dòng tính theo nến ngày; với khung nhỏ hơn, thư viện quy đổi theo số nến mỗi phiên, nên với nến phút thứ chặn là giới hạn 180 ngày. Các con số này do chính sách từ vnstocks.com quy định và có thể đổi; vnstock policy cho biết mức đang áp cho máy của bạn.

Nguồn source=

Mỗi hàm có nguồn mặc định riêng, ghi ở từng mục dưới đây. Truyền source= thì thư viện dùng đúng nguồn đó và không tự chuyển sang nguồn khác khi lỗi. Bảng đầy đủ ở Nguồn dữ liệu.

2. Cổ phiếu: Market().equity(symbol)

from vnstock import Market

fpt = Market().equity("FPT")

2.1. ohlcv(): giá lịch sử

Chữ ký và tham số ở mục 1. Tên cũ history(start, end, interval, **kwargs) nhận đúng các tham số đó.

fpt.ohlcv(start="2026-10-01", end="2026-10-09")

Dữ liệu mẫu (chạy 10/10/2026, nguồn vci, nghìn đồng):

Nến một phút, fpt.ohlcv(length=5, interval="1m"), ba nến cuối của phiên 09/10/2026:

Nến 14:45 là phiên khớp lệnh đóng cửa (ATC).

Hai nguồn vci và kbs điều chỉnh giá theo sự kiện quyền theo cách khác nhau, nên giá cũ có thể lệch vài đồng. Muốn số giống vnstock_data 3.x, truyền source="kbs".

2.2. trades(): danh sách lệnh khớp

trades(limit=None, *, last_id=None, side=None, source=None)

Không truyền limit thì hàm trả 100 lệnh mới nhất. Muốn nhiều hơn, truyền limit=:

• Nguồn vci (mặc định) nhận từ 1 tới 1.000 lệnh mỗi lần. Hỏi nhiều hơn thì nhận InputError mã VNSTOCK_VCI_TRADES_PAGE_LIMIT; lấy tiếp bằng last_id. Nguồn này trả 100 lệnh mỗi truy vấn, nên limit lớn hơn 100 là nhiều truy vấn lần lượt. 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ợ. Ví dụ limit=1000 ở cấp Khách mất khoảng 10 giây. Một lời gọi hàm gửi tối đa 50 truy vấn.
• Nguồn kbs trả được 5.000 lệnh trong một lần gọi (limit=5000, source="kbs").
• Khách và Cộng đồng bị cắt ở 5.000 lệnh mới nhất mỗi lần gọi, ghi ở df.attrs["tier_cap_rows"].

Tên cũ intraday(page_size=100, last_time=None, **kwargs): page_size là limit, last_time là last_id.

match_type viết hoa chữ đầu với vci (Buy, ATC) và viết thường với kbs (buy, atc). Khi so sánh, dùng df["match_type"].str.lower().

Dữ liệu mẫu (fpt.trades(limit=5), chạy 10/10/2026, nguồn vci, phiên 09/10/2026):

2.3. quote(): bảng giá của mã

quote(*, source=None)

Trả một dòng, giá tính bằng đồng. Tên cũ: price_board().

Dữ liệu mẫu (chạy 10/10/2026, nguồn kbs, cuối phiên 09/10/2026, chọn 8 trong 23 cột):

Muốn bảng giá nhiều mã một lần, dùng Market().quote(symbols) (mục 8).

2.4. order_book(): sổ lệnh

order_book(limit=None, *, source=None)

Cấp tài trợ. Trả một dòng với 12 cột bid_price_1..3, bid_vol_1..3, ask_price_1..3, ask_vol_1..3, giá tính bằng đồng. Tên cũ: price_depth().

Dữ liệu mẫu (chạy 10/10/2026, nguồn kbs, cuối phiên 09/10/2026):

2.5. volume_profile(): khối lượng theo mức giá

volume_profile(*, source=None)

Cấp tài trợ. Khối lượng khớp của phiên hiện tại (hoặc phiên gần nhất) ở từng mức giá, giá thấp nhất trước. Tên cũ: matched_by_price().

Dữ liệu mẫu (chạy 10/10/2026, nguồn kbs, phiên 09/10/2026, FPT có 26 mức giá):

2.6. session_stats(): thống kê gộp

session_stats(limit=None, *, source=None, start=None, end=None)

Cấp tài trợ. Trả một dòng cho mã, gộp các tổng và trung bình trong khoảng start–end. Không truyền khoảng thì nguồn tự chọn khoảng gộp. Tên cũ: trading_stats().

Với nguồn vci, bảng có 65 cột, chia thành các nhóm:

Dữ liệu mẫu (fpt.session_stats(start="2026-10-01", end="2026-10-09"), chạy 10/10/2026, nguồn vci, giá trị tính bằng đồng):

2.7. trade_history(): thống kê giao dịch theo ngày

trade_history(start=None, end=None, limit=None, resolution="1D", *, source=None)

Cấp tài trợ. Mỗi phiên một dòng, phiên mới nhất trước. Không truyền khoảng thì trả 100 phiên mới nhất. Đây không phải danh sách lệnh khớp; lệnh khớp ở trades().

Bảng có 39 cột. Nhóm chính:

Dữ liệu mẫu (fpt.trade_history(limit=3), chạy 10/10/2026, nguồn vci):

2.8. foreign_flow() và proprietary_flow(): khối ngoại, tự doanh

foreign_flow(limit=None, source=None, *, start=None, end=None)
proprietary_flow(limit=None, source=None, *, start=None, end=None)

Cấp tài trợ, nguồn vci. Mỗi phiên một dòng, phiên mới nhất trước. limit là số phiên.

Dữ liệu mẫu fpt.foreign_flow(limit=3) (chạy 10/10/2026):

Dữ liệu mẫu fpt.proprietary_flow(limit=3) (chạy 10/10/2026):

2.9. block_trades(): giao dịch thoả thuận

block_trades(limit=1000, source=None)

Cấp tài trợ. Các giao dịch thoả thuận của mã trong phiên gần nhất, lấy từ danh sách thoả thuận của sàn niêm yết. Tên cũ: put_through(limit=None, source=None), với limit=None nghĩa là 1.000.

Với nguồn kbs (mặc định), cột trả về: symbol, time, exchange, match_price (đồng), match_volume, trading_date, reference_price, floor_price. Với vci: symbol, match_price, match_volume, change, change_percent, match_value, accumulated_volume, accumulated_value, time.

Mã không có giao dịch thoả thuận nào trong danh sách của nguồn thì hàm trả bảng rỗng có đủ cột. Chạy ngày 10/10/2026, fpt.block_trades() trả bảng rỗng ở cả kbs và vci. Dữ liệu mẫu theo sàn ở mục 8.

2.10. odd_lot(): bảng giá lô lẻ

odd_lot(limit=None, source=None)

Cấp tài trợ. Một dòng bảng giá lô lẻ của mã. Cột như quote() (giá tính bằng đồng), thêm match_price, match_vol (lệnh khớp gần nhất) và total_volume (tổng khối lượng lô lẻ trong phiên).

Dữ liệu mẫu (chạy 10/10/2026, nguồn kbs, phiên 09/10/2026):

2.11. Nhiều mã một lúc

Market().equity() nhận cả danh sách mã, như bản 4.x. Mỗi hàm được gọi lần lượt cho từng mã rồi xếp các bảng chồng lên nhau theo thứ tự mã truyền vào. Riêng quote() và price_board() hỏi cả danh sách trong một lần.

basket = Market().equity(["FPT", "VCB"])
basket.ohlcv(length=2)   # 4 dòng: 2 nến FPT rồi 2 nến VCB
basket.quote()           # 2 dòng, một truy vấn

Bảng xếp chồng không có cột mã: ohlcv() của hai mã trả sáu cột như một mã. Danh sách mã nằm ở df.attrs["symbol"]. Cần biết dòng nào của mã nào thì gọi từng mã và tự thêm cột:

import pandas as pd

frames = [Market().equity(s).ohlcv(length=2).assign(symbol=s) for s in ["FPT", "VCB"]]
df = pd.concat(frames, ignore_index=True)

3. Chỉ số: Market().index(symbol)

vnindex = Market().index("VNINDEX")

Mã chỉ số trong nước: VNINDEX, VN30, HNXINDEX, UPCOMINDEX và các chỉ số khác. Danh sách đầy đủ lấy bằng Reference().index.list(), xem Tham chiếu.

Chỉ số thế giới (USA30, JPN225…) mở bằng Market().index("USA30", scope="global"), xem Tài sản quốc tế.

3.1. ohlcv()

Như mục 1. Giá tính bằng điểm.

Dữ liệu mẫu vnindex.ohlcv(length=3) (chạy 10/10/2026, nguồn kbs):

vnindex.ohlcv(length=3, interval="15m") lấy từ vci, ba nến cuối phiên 09/10/2026:

3.2. quote()

quote(*, source=None)

Cấp tài trợ. Một dòng: symbol, reference_price, open_price, high_price, low_price, close_price (điểm), total_volume.

(chạy 10/10/2026, nguồn kbs, phiên 09/10/2026)

3.3. trade_history(): thống kê chỉ số theo ngày

trade_history(start=None, end=None, limit=None, resolution="1D", *, source=None)

Cấp tài trợ, nguồn vci. Mỗi phiên một dòng, phiên mới nhất trước; không truyền khoảng thì trả 100 phiên. Tham số như trade_history() của cổ phiếu (mục 2.7).

Bảng có 36 cột. Ngoài điểm chỉ số (open, close, high, low, price_change, percent_price_change) và giá trị khớp lệnh, thoả thuận, bảng có độ rộng thị trường:

Dữ liệu mẫu vnindex.trade_history(limit=3) (chạy 10/10/2026):

3.4. trades()

Hàm nhận như trades() của cổ phiếu (mục 2.2). Cột trả về theo lược đồ: time, price, volume, match_type, id.

order_book(), session_stats() và stock_influence() có tên trên lớp chỉ số nhưng chưa chạy, xem mục 9.

4. Hợp đồng tương lai: Market().futures(symbol)

vn30f = Market().futures("VN30F1M")

Market().future(symbol) là tên khác, cho cùng kết quả. Mã hợp đồng dùng được dạng VN30F1M, VN30F2M (tháng gần, tháng kế tiếp). Danh sách lấy bằng Reference().futures.list().

4.1. ohlcv()

Như mục 1. Giá tính bằng điểm.

Dữ liệu mẫu vn30f.ohlcv(length=2) (chạy 10/10/2026, nguồn kbs):

vn30f.ohlcv(length=3, interval="1m") lấy từ vci:

4.2. quote()

quote(*, source=None)

Một dòng, 26 cột: như quote() của cổ phiếu (giá tính bằng điểm), thêm total_volume, basis (độ lệch so với chỉ số cơ sở) và open_interest (khối lượng hợp đồng mở).

Cột symbol trả mã hợp đồng của sàn, không phải mã gọi tắt: hỏi VN30F1M thì nhận 41I1GA000.

Dữ liệu mẫu (chạy 10/10/2026, nguồn kbs, phiên 09/10/2026):

4.3. trades()

Hàm nhận và trả như trades() của cổ phiếu (mục 2.2), với giới hạn 5.000 lệnh mỗi lần gọi ở cấp Khách và Cộng đồng. Nguồn mặc định là kbs.

4.4. order_book()

order_book(limit=None, *, source=None)

Cấp tài trợ. Cột như order_book() của cổ phiếu, giá tính bằng điểm.

(chạy 10/10/2026, nguồn kbs, cuối phiên 09/10/2026)

5. Chứng quyền: Market().warrant(symbol)

cw = Market().warrant("CHPG2625")

Danh sách chứng quyền đang lưu hành lấy bằng Reference().warrant.list() (chạy 10/10/2026: 339 mã).

5.1. ohlcv()

Như mục 1. Giá tính bằng nghìn đồng (0.16 là 160 đồng).

Dữ liệu mẫu cw.ohlcv(length=3) (chạy 10/10/2026, nguồn kbs):

5.2. quote()

Một dòng, 23 cột như quote() của cổ phiếu, giá tính bằng đồng.

(chạy 10/10/2026, nguồn kbs, phiên 09/10/2026)

5.3. trades() và order_book()

trades() nhận và trả như cổ phiếu (mục 2.2). order_book() (cấp tài trợ) trả 12 cột như cổ phiếu; chạy 10/10/2026, cw.order_book() cho bid_price_1 150.0, bid_vol_1 500000, ask_price_1 160.0, ask_vol_1 188700.

6. ETF: Market().etf(symbol)

etf = Market().etf("E1VFVN30")

Chứng chỉ quỹ ETF khớp lệnh trên cùng bảng với cổ phiếu, nên Market().etf() có đủ các hàm của Market().equity() với cùng tham số và cột trả về. Cấp quyền cũng như cổ phiếu: ohlcv, trades, quote mở mọi cấp, các hàm còn lại dành cho tài trợ. Danh sách ETF lấy bằng Reference().etf.list().

Khác cổ phiếu ở nguồn mặc định:

Dữ liệu mẫu etf.ohlcv(length=3) (chạy 10/10/2026, nguồn kbs, nghìn đồng):

etf.trades(limit=3) (nguồn kbs, phiên 09/10/2026):

etf.foreign_flow(limit=2) (nguồn vci):

7. Trái phiếu niêm yết: Market().bond(symbol)

bond = Market().bond("BID122005")

Trái phiếu niêm yết khớp trên cùng bảng với cổ phiếu, nên Market().bond() có các hàm và cột trả về như Market().equity(). quote() trả đúng 23 cột chuẩn như cổ phiếu. Cấp quyền như cổ phiếu. Danh sách mã lấy bằng Reference().bond.list().

Nguồn mặc định của ohlcv, trades, quote, order_book là kbs; các hàm còn lại theo cổ phiếu.

Trái phiếu niêm yết ít giao dịch. Chạy ngày 10/10/2026, bond.quote() trả một dòng với giá tham chiếu 100000.0, giá khớp 0.0 và các bước giá trống; bond.ohlcv(length=3) và bond.trades() trả bảng rỗng có đủ cột. Mã không có trên nguồn thì nhận InputError mã VNSTOCK_INPUT_SYMBOL_UNKNOWN.

8. Bảng giá nhiều mã và hàm toàn thị trường

Ba hàm gọi thẳng trên Market(), nhận một mã hoặc một danh sách mã.

8.1. Market().quote(symbols_list): bảng giá

Market().quote(symbols_list, **kwargs)

Mọi cấp. Hỏi cả danh sách trong một truy vấn. Cột như quote() của cổ phiếu (mục 2.3), mỗi mã một dòng. Danh sách có thể trộn cổ phiếu, ETF, chứng quyền. Tên cũ: Market().price_board().

Một chuỗi được hiểu là một mã: Market().quote("VCB") hỏi mã VCB, không tách thành V, C, B.

Market().quote(["FPT", "VCB", "E1VFVN30"])

Dữ liệu mẫu (chạy 10/10/2026, nguồn kbs, cuối phiên 09/10/2026, chọn 8 trong 23 cột):

8.2. Market().odd_lot(symbols_list): bảng giá lô lẻ

Market().odd_lot(symbols_list=None, **kwargs)

Cấp tài trợ, nguồn mặc định kbs. Truyền mã thì trả đúng các mã đó; không truyền thì trả cả sàn exchange. Cột như odd_lot() của cổ phiếu (mục 2.10).

Dữ liệu mẫu Market().odd_lot(["FPT", "VCB"]) (chạy 10/10/2026, phiên 09/10/2026):

8.3. Market().put_through(symbols_list): giao dịch thoả thuận

Market().put_through(symbols_list=None, **kwargs)

Cấp tài trợ, nguồn mặc định kbs. Nguồn công bố thoả thuận theo sàn (exchange, mặc định HOSE). Truyền mã thì giữ dòng của các mã đó; không truyền thì trả mọi dòng của sàn. Cột như block_trades() (mục 2.9) với nguồn kbs.

Dữ liệu mẫu Market().put_through(limit=3) (chạy 10/10/2026, sàn HOSE, phiên 09/10/2026):

9. Chưa hỗ trợ và sắp bỏ

Chưa hỗ trợ

Các tên dưới đây vẫn có trên lớp để mã cũ không vỡ khi nạp, nhưng gọi thì nhận UnsupportedError:

Giao dịch của người nội bộ có ở Reference().company(s).insider_trading(), xem Tham chiếu.

Sắp bỏ

Market().pe(), Market().pb(), Market().evaluation() vẫn trả kết quả, kèm một cảnh báo, và ngừng trả lời sau 31/12/2026. Dùng Analytics().valuation("VNINDEX").pe(), .pb(), .evaluation(), xem Analytics.

10. Bảng tên cũ

Tên cũ vẫn chạy và trỏ tới cùng hàm, cùng dữ liệu:

Market().put_through(symbols) trên Market() là hàm toàn sàn ở mục 8.3, không phải tên cũ.

Khác bản cũ cần biết khi chuyển mã:

• ohlcv() không truyền gì trả 100 nến mới nhất, không phải một năm.
• length=100 là 100 nến, không phải 100 ngày như vnstock_data 3.x. Muốn theo ngày, viết length="100d".
• source= có tác dụng thật ở mọi hàm có tham số này.

Chi tiết ở Chuyển từ vnstock 4.x và Chuyển từ vnstock_data 3.x. Lỗi và mã lỗi ở Xử lý lỗi.