Truy xuất và chuẩn hoá dữ liệu thị trường
Mục lục
Chọn nguồn bạn có khoá, mã trên trang sẽ điền theo. Chưa chọn thì mã giữ chỗ trống <nguồn>. Nguồn xếp theo bảng chữ cái, không phải khuyến nghị.
Lớp Market giúp bạn truy xuất và chuẩn hoá dữ liệu giao dịch trên thị trường: nến lịch sử (OHLCV), khớp lệnh từng lệnh, bảng giá, sổ lệnh 3 bậc, dữ liệu mua bán của khối ngoại và tự doanh, cùng dữ liệu chứng chỉ quỹ ETF, trái phiếu, hợp đồng tương lai phái sinh, diễn biến ngành, bộ lọc cổ phiếu, quỹ mở, tiền mã hoá, tỷ giá ngoại hối, hàng hoá và chỉ số quốc tế.
Cú pháp gọi hàm cơ bản của lớp Market
Cấu trúc gọi chuẩn theo thứ tự: Market(nguồn) → nhóm_tài_sản(mã) → tên_hàm(). Bạn cũng có thể truyền nguồn qua tham số source= bên trong hàm như cách viết ở thế hệ 5:
from vnstock import Market
Market("<nguồn>").equity("FPT").ohlcv(start="2026-10-01", end="2026-10-30", interval="1D")
Market().equity("FPT").ohlcv(source="<nguồn>", length=100) # tương thích cách gọi của thế hệ 5Mỗi hàm được hỗ trợ bởi một tập nguồn nhất định (ghi rõ tại cột Nguồn ở các bảng bên dưới). Ví dụ khi lấy dữ liệu khớp lệnh trong phiên:
Market("<nguồn>").equity("FPT").trades()Lấy dữ liệu giao dịch khối ngoại của chỉ số thị trường:
Market("<nguồn>").index("VNINDEX").foreign_flow(start="2026-10-01")Lấy dữ liệu nến lịch sử của cặp tiền mã hoá:
Market("<nguồn>").crypto("BTCUSDT").ohlcv(interval="1H")Lấy dữ liệu nến của hợp đồng tương lai chỉ số VN30:
Market("<nguồn>").futures("VN30F1M").ohlcv(length=100) # chuỗi hợp đồng tương lai liên tục kỳ hạn 1 tháng
Market("<nguồn>").futures("41I1GB000").ohlcv(length=100) # một mã hợp đồng cụ thể theo chuẩn KRXNếu bạn không truyền tên nguồn vào Market() hay source=, thư viện sẽ tự động tra quy tắc nguồn mặc định đã thiết lập qua vnstock.sources (Cách chọn nguồn dữ liệu).
Bảng tra cứu nhanh theo nhu cầu phân tích
| Dữ liệu bạn cần lấy | Cú pháp gọi hàm tiêu biểu | Nguồn hỗ trợ (source=) |
|---|---|---|
| Nến lịch sử cổ phiếu, ETF, chỉ số Việt Nam | Market("<nguồn>").equity("FPT").ohlcv(...), .index("VNINDEX").ohlcv(...) | dnse, fhsc, ssi, tcbs |
| Bảng giá trong phiên và sổ lệnh 3 bậc giá | Market("<nguồn>").equity("FPT").quote(), .order_book() | fhsc, tcbs (order_book hỗ trợ thêm dnse) |
| Khớp lệnh chi tiết từng lệnh và khối lượng theo bước giá | Market("<nguồn>").equity("FPT").trades(), .volume_profile() | dnse, tcbs |
| Giao dịch thoả thuận trên sàn | Market("tcbs").equity.block_trades(exchange="HOSE") | tcbs |
| Giao dịch khối ngoại, room ngoại và tự doanh | Market("<nguồn>").equity("FPT").foreign_flow(), .foreign_room(), Market("fhsc").equity("FPT").proprietary_flow() | dnse, fhsc, ssi (tự doanh cổ phiếu: fhsc; tự doanh chỉ số: ssi) |
| Hợp đồng tương lai phái sinh và chứng quyền có bảo đảm | Market("<nguồn>").futures("VN30F1M").ohlcv(), Market("<nguồn>").warrant("CFPT2501").quote() | dnse, ssi, tcbs (tuỳ hàm) |
| Chứng chỉ quỹ ETF và lợi suất trái phiếu | Market("<nguồn>").etf("E1VFVN30").ohlcv(), Market("fhsc").bond("VN10Y").yield_history(...) | dnse, fhsc, ssi, tcbs (ETF tuỳ hàm); fhsc (trái phiếu) |
| Diễn biến chỉ số ngành và độ rộng thị trường | Market("fhsc").sector("banks").ohlcv(), .sector.comparison(), .index("VNINDEX").breadth() | fhsc |
| Sàng lọc cổ phiếu theo tiêu chí thị trường | Market("fhsc").equity.screener(exchange="HOSE", sort="-change_percent") | fhsc |
| Thống kê cung cầu và mua bán chủ động | Market("<nguồn>").equity("FPT").active_flow(), Market("tcbs").equity("FPT").supply_demand_daily() | fhsc, tcbs |
| Giá vàng, bạc bán lẻ trong nước | Retail("fhsc").gold(), .silver(), .gold.history("GOLD_BAR_SJC", start=...) | fhsc (xem chi tiết tại mục bên dưới) |
| Lịch sử NAV và hiệu suất tăng trưởng quỹ mở | Market("fhsc").fund("DCDS").history(), .performance() | fhsc |
| Thị trường tiền mã hoá giao ngay | Market("<nguồn>").crypto("BTCUSDT").ohlcv(), .quote(), .order_book(), .trades(), .aggregate_trades(), .best_bid_ask() | binance, fhsc, fmp (order_book, trades, aggregate_trades, best_bid_ask: binance) |
| Tỷ giá ngoại hối, hàng hoá và chỉ số chứng khoán quốc tế | Market("<nguồn>").forex("USDVND").ohlcv(), .commodity("GC").ohlcv(), .index("^GSPC", scope="global").ohlcv() | fhsc, fmp |
Các tham số dùng chung và quy ước đơn vị, thời gian
| Tên tham số | Kiểu dữ liệu | Giá trị mặc định | Ý nghĩa và quy ước truyền vào |
|---|---|---|---|
start, end | str, date, datetime | end là ngày hôm nay; với hàm nến, start mặc định lùi 30 ngày trước end | Chuỗi ngày dạng YYYY-MM-DD, YYYY-MM, YYYY (tính từ ngày đầu kỳ), hoặc chuỗi ISO có kèm giờ |
interval | str | "1D" | Khung thời gian nến: 1m 3m 5m 15m 30m 1H 4H 1D 1W 1M (phân biệt chữ hoa/thường: m là phút, M là tháng; vẫn chấp nhận D, day, H, W, month, riêng "DAY" in hoa sẽ báo lỗi). Mỗi nguồn hỗ trợ một số khung nhất định |
date | str | Phiên gần nhất | Ngày giao dịch cần xem ở hàm volume_profile() trên nguồn dnse; truyền vào nguồn chỉ hỗ trợ phiên hiện tại sẽ báo VNSTOCK_INPUT_PARAM |
length | int, str | Số lượng nến (100 hoặc "100b" lấy 100 nến gần nhất) hoặc độ dài thời gian tính lùi từ end ("3M", "1Y", "10d", "2W") | |
count_back | int | Chỉ giữ lại đúng N nến gần nhất ở kết quả cuối | |
limit | int | Giới hạn số dòng trả về tối đa (ưu tiên giữ các dòng mới nhất) | |
board | str, None | "G1" | Bảng giao dịch áp dụng cho các hàm trong phiên (quote, order_book, trades, expected_price); "G1" là bảng lô chẵn chính, truyền None để lấy mọi bảng |
floating | int | 2 | Số chữ số thập phân làm tròn cho các cột giá; truyền None để giữ nguyên số gốc |
source | str | Chỉ định nguồn dữ liệu cho riêng lời gọi hàm này | |
compat | str | "v5" | Chọn hồ sơ đầu ra: "v5" giữ tên cột, thứ tự và đơn vị như thế hệ 5; "v6" dùng bộ quy ước đồng nhất mới (Chuẩn hoá và bộ cột dữ liệu) |
columns | str | "standard" | Chọn bộ cột trả về: "standard" (chuẩn), "common" (giao nhau) hoặc "all" (thêm cột riêng của nguồn) |
Mỗi hàm chỉ nhận những tham số được liệt kê tại cột Tham số của hàm đó trong bảng danh mục bên dưới, cộng với 4 tham số tuỳ chỉnh chung là source, floating, compat, columns. Nếu truyền tham số không thuộc danh sách này, hàm sẽ báo lỗi VNSTOCK_INPUT_PARAM ngay lập tức.
Quy ước về khối lượng và đơn vị giá:
- Khối lượng giao dịch: tính theo đơn vị cổ phiếu đồng nhất trên mọi nguồn và mọi bảng giao dịch; riêng hợp đồng tương lai tính theo số hợp đồng. Hàm
volume_profile()chỉ tính trên bảng lô chẵn chínhG1(tương tự hàmtrades()). - Đơn vị giá (ở hồ sơ mặc định
v5): giữ nguyên như thế hệ 5 — dữ liệu nến (ohlcv) và khớp lệnh (trades) tính bằng nghìn đồng; trong khi bảng giá (quote), sổ lệnh (order_book), giao dịch thoả thuận (block_trades), khớp lệnh theo bước giá (volume_profile),trade_history()vàsession_stats()tính bằng đồng. Chỉ số và hợp đồng tương lai chỉ số tính bằng điểm. Tiền mã hoá, ngoại hối và hàng hoá tính theo đồng tiền định giá của cặp tài sản. Khi chuyển sang hồ sơcompat="v6", toàn bộ các cột giá cổ phiếu trên mọi bảng đều được quy về nghìn đồng.
Quy ước về thời gian và gộp nến:
- Nến ngày mang mốc thời gian
07:00+07:00(tương ứng00:00 UTCcủa ngày giao dịch) giống thế hệ 5. Ở hồ sơv5, các hàmforeign_flow(),proprietary_flow()vàtrade_history()sắp xếp phiên mới nhất lên đầu với mốc giờ00:00+07:00. Khi chuyển sang hồ sơv6, tất cả các hàm này đều sắp xếp tăng dần theo thời gian và dùng chung mốc07:00+07:00với bảng nến để bạn ghép bảng trực tiếp (Chuẩn hoá và bộ cột dữ liệu). - Đối với nguồn có nến ngày (
1D) nhưng không có sẵn nến tuần (1W) hoặc nến tháng (1M), thư viện sẽ tự động tải dữ liệu nến1Dcủa trọn kỳ rồi tổng hợp thành nến tuần/tháng, gắn mốc ngày đầu kỳ và ghi nhậndf.attrs["resampled_from"] = "1D". - Nếu bạn gọi hàm lấy nến ngay trong giờ giao dịch (hoặc khi tuần/tháng hiện tại chưa kết thúc), dòng nến cuối cùng là nến của kỳ đang diễn ra nên giá đóng cửa và khối lượng vẫn còn thay đổi. Thư viện đánh dấu trạng thái này qua cờ
df.attrs["last_bar_partial"] = True. Bạn có thể loại bỏ nến chưa đóng bằng cách kiểm tra thuộc tính này:
df = Market("<nguồn>").equity("FPT").ohlcv(start="2026-10-01")
if df.attrs.get("last_bar_partial"):
df = df.iloc[:-1]Danh mục hàm chi tiết theo từng lớp tài sản
Bảng áp dụng cho bản 6.0.1, hồ sơ v5 (mặc định). Mỗi nhóm ghi cách gọi, ý nghĩa từng hàm, tham số riêng của hàm và nguồn có dữ liệu. Ý nghĩa của từng tham số riêng ở cuối mục; mọi hàm còn nhận source, floating, compat, columns. "Tên cũ" là tên của thế hệ 5 cho cùng dữ liệu, vẫn gọi được.
Trên máy bạn: vnstock tools liệt kê mọi hàm, vnstock doc Market.equity.ohlcv in chi tiết một hàm.
Cổ phiếu (equity)
Cách gọi: Market("<nguồn>").equity("FPT").<hàm>(...); Market("<nguồn>").equity.<hàm>(...) cho hàm ghi không cần mã.
Nến và giá mới nhất
| Hàm | Ý nghĩa | Tham số riêng | Nguồn (source=) |
|---|---|---|---|
close_price() | Giá đóng cửa mới nhất | — | dnse |
expected_price() | Giá, khối lượng khớp dự kiến trong phiên định kỳ ATO, ATC | start, end, board | dnse |
last_trade() | Lệnh khớp gần nhất | — | dnse |
ohlcv() (tên cũ: history) | Nến giá cổ phiếu, chứng chỉ quỹ ETF | start, end, interval, length, count_back, limit | dnse, fhsc, ssi, tcbs |
Bảng giá và sổ lệnh
| Hàm | Ý nghĩa | Tham số riêng | Nguồn (source=) |
|---|---|---|---|
order_book() (tên cũ: price_depth) | Ba bậc giá mua, bán tốt nhất | board | dnse, fhsc, tcbs |
order_book_history() | Các lần chụp sổ lệnh trong phiên | start, end | dnse |
order_book_intraday() | Các lần chụp sổ lệnh của phiên gần nhất, 5 phút một lần | — | fhsc |
quote() (tên cũ: price_board) | Bảng giá: giá, khối lượng phiên, ba bậc giá, khối ngoại của nhiều mã | board | fhsc, tcbs |
Khớp lệnh và thống kê phiên
| Hàm | Ý nghĩa | Tham số riêng | Nguồn (source=) |
|---|---|---|---|
block_trades() (tên cũ: put_through), không cần mã | Giao dịch thoả thuận đã khớp trong phiên, mọi mã của một sàn | exchange, date | tcbs |
session_stats() (tên cũ: trading_stats) | Thống kê gộp một khoảng của một mã: tổng, bình quân mỗi phiên, khối ngoại, lệnh mua bán | start, end, length, limit | ssi |
session_volume() | Khớp lệnh và thoả thuận của phiên gần nhất | — | fhsc |
trade_history() | Thống kê từng phiên của một mã: giá, khớp lệnh, thoả thuận, lệnh đặt | start, end, length, limit | ssi |
trades() (tên cũ: intraday) | Từng lệnh khớp trong phiên | start, end, limit, board | dnse, tcbs |
volume_history() | Khớp lệnh và thoả thuận theo phiên | start, end | fhsc |
volume_profile() (tên cũ: matched_by_price) | Khối lượng khớp theo từng mức giá, tách mua, bán chủ động | date | dnse, tcbs |
Khối ngoại, tự doanh, người nội bộ
| Hàm | Ý nghĩa | Tham số riêng | Nguồn (source=) |
|---|---|---|---|
foreign_flow() | Khối ngoại mua, bán của một mã theo ngày (1D) hoặc trong phiên | start, end, interval, length, limit | dnse, fhsc, ssi |
foreign_room(), không cần mã | Room ngoại còn lại và tổng room của nhiều mã | group | dnse, fhsc, ssi |
foreign_room_board(), không cần mã | Room khối ngoại của cả một sàn hoặc một rổ | exchange | tcbs |
foreign_room_history() | Lịch sử room khối ngoại | start, end | fhsc |
foreign_session() | Giao dịch khối ngoại của phiên gần nhất | — | fhsc |
insider_deal() | Giao dịch của người nội bộ, cổ đông lớn | start, end | fhsc |
proprietary_flow() | Tự doanh công ty chứng khoán mua, bán một mã, theo ngày | start, end, length, limit | fhsc |
proprietary_session() | Giao dịch tự doanh của phiên gần nhất | — | fhsc |
Mua bán chủ động, cung cầu
| Hàm | Ý nghĩa | Tham số riêng | Nguồn (source=) |
|---|---|---|---|
active_flow() | Khối lượng mua chủ động, bán chủ động theo phút, ngày, tháng (số liệu nguồn tự tính) | interval | fhsc |
active_session() | Lệnh mua, bán chủ động của phiên gần nhất | — | fhsc |
supply_demand_daily() | Tỷ lệ mua, bán chủ động theo phiên, khoảng một tháng | investor | tcbs |
supply_demand_intraday() | Cung cầu chủ động trong phiên, có khối lượng | investor | tcbs |
supply_demand_session() | Tỷ lệ mua, bán chủ động theo phút của phiên hiện tại | investor | tcbs |
Tổng quan và bộ lọc
| Hàm | Ý nghĩa | Tham số riêng | Nguồn (source=) |
|---|---|---|---|
screener(), không cần mã | Bộ lọc cổ phiếu toàn thị trường | exchange, index, sector, window, date, sort | fhsc |
summary() | Chỉ số định giá và sinh lời mới nhất của một mã | — | fhsc |
Cột trả về (hồ sơ v5, mặc định)
| Hàm | Cột |
|---|---|
active_flow() | time, active_buy_volume, active_sell_volume, active_buy_percent, active_sell_percent, active_buy_sell_ratio |
active_session() | symbol, time, active_buy_volume, active_sell_volume, active_buy_percent, active_sell_percent, buy_order_count, sell_order_count |
block_trades() | symbol, match_price, match_volume, match_value, accumulated_value, time |
close_price() | symbol, time, close |
expected_price() | time, expected_price, expected_volume |
foreign_flow() | time, buy_vol, buy_val, sell_vol, sell_val, net_vol, net_val |
foreign_room() | symbol, time, foreign_room, foreign_room_total, foreign_buy_volume, foreign_sell_volume, foreign_owned_volume, foreign_room_limit_percent |
foreign_room_board() | symbol, foreign_room, foreign_buy_volume, foreign_sell_volume, close, total_volume, total_value |
foreign_room_history() | time, foreign_room, foreign_owned_volume, max_foreign_volume, max_foreign_percent |
foreign_session() | symbol, time, foreign_buy_volume, foreign_buy_value, foreign_sell_volume, foreign_sell_value, foreign_net_volume, foreign_net_value |
insider_deal() | id, symbol, person_name, position, transaction_type, registered_volume, traded_volume, start_date, end_date, status, shares_before, shares_after, ownership_percent_before, ownership_percent_after, relation_type, related_person_name |
last_trade() | time, price, volume, side, accumulated_volume |
ohlcv() | time, open, high, low, close, volume |
order_book() | bid_price_1, bid_vol_1, bid_price_2, bid_vol_2, bid_price_3, bid_vol_3, ask_price_1, ask_vol_1, ask_price_2, ask_vol_2, ask_price_3, ask_vol_3, time, total_bid_volume, total_ask_volume |
order_book_history() | time, bid_price_1, bid_volume_1, bid_price_2, bid_volume_2, bid_price_3, bid_volume_3, ask_price_1, ask_volume_1, ask_price_2, ask_volume_2, ask_price_3, ask_volume_3 |
order_book_intraday() | time, bid_price_1, bid_volume_1, bid_price_2, bid_volume_2, bid_price_3, bid_volume_3, ask_price_1, ask_volume_1, ask_price_2, ask_volume_2, ask_price_3, ask_volume_3 |
proprietary_flow() | time, buy_vol, buy_val, sell_vol, sell_val, net_vol, net_val |
proprietary_session() | symbol, time, proprietary_buy_volume, proprietary_buy_value, proprietary_sell_volume, proprietary_sell_value, proprietary_net_volume, proprietary_net_value |
quote() | symbol, exchange, reference_price, ceiling_price, floor_price, open_price, high_price, low_price, close_price, bid_price_1, bid_vol_1, bid_price_2, bid_vol_2, bid_price_3, bid_vol_3, ask_price_1, ask_vol_1, ask_price_2, ask_vol_2, ask_price_3, ask_vol_3, foreign_buy_volume, foreign_sell_volume, time, price_change, price_change_percent, average_price, total_volume, total_value, foreign_room, next_reference_price, next_ceiling_price, next_floor_price, last_volume |
screener() | symbol, name, exchange, sector_slug, close, price_change_percent, market_cap, outstanding_shares, pe, pb, eps, total_volume, total_value, foreign_net_value, foreign_net_volume, foreign_room, proprietary_net_value, proprietary_net_volume |
session_stats() | symbol, time, average_match_volume, average_match_value, average_deal_volume, average_deal_value, average_volume, average_value, total_match_volume, total_match_value, total_deal_volume, total_deal_value, total_volume, total_value, fr_buy_volume_total, fr_buy_value_total, fr_sell_volume_total, fr_sell_value_total, fr_net_volume_total, fr_net_value_total, fr_buy_volume_total_avg, fr_buy_value_total_avg, fr_sell_volume_total_avg, fr_sell_value_total_avg, fr_net_volume_total_avg, fr_net_value_total_avg, total_buy_trade_volume, total_sell_trade_volume, total_buy_trade_volume_avg, total_sell_trade_volume_avg, total_buy_trade, total_sell_trade, total_buy_trade_avg, total_sell_trade_avg, total_net_trade_volume, total_net_trade_volume_avg, average_buy_volume_per_trade, average_sell_volume_per_trade, close_price, reference_price |
session_volume() | symbol, time, matched_volume, matched_value, block_volume, block_value, total_volume, total_value |
summary() | eps, pe, pb, roe, dividend_yield, symbol, roa, ev_ebitda, gross_margin, nim, industry_pe, industry_pb, industry_ev_ebitda |
supply_demand_daily() | time, active_buy_percent, active_sell_percent, buy_sell_ratio |
supply_demand_intraday() | time, active_buy_percent, active_sell_percent, buy_sell_ratio, active_buy_volume, active_sell_volume, accumulated_buy_volume, accumulated_sell_volume |
supply_demand_session() | time, active_buy_percent, active_sell_percent, buy_sell_ratio |
trade_history() | trading_date, reference_price, open, close, price_change, percent_price_change, high, low, average_price, matched_volume, matched_value, deal_volume, deal_value, total_volume, total_value, total_buy_trade, total_buy_trade_volume, total_sell_trade, total_sell_trade_volume, symbol, foreign_buy_volume, foreign_buy_value, foreign_sell_volume, foreign_sell_value, foreign_net_volume, foreign_net_value |
trades() | time, price, volume, match_type, id, accumulated_volume |
volume_history() | time, matched_volume, matched_value, block_volume, block_value, total_volume, total_value |
volume_profile() | price, buy_volume, sell_volume, unknown_volume, total_volume |
Chứng chỉ quỹ ETF (etf)
Cách gọi: Market("<nguồn>").etf("E1VFVN30").<hàm>(...); Market("<nguồn>").etf.<hàm>(...) cho hàm ghi không cần mã.
Nến và giá mới nhất
| Hàm | Ý nghĩa | Tham số riêng | Nguồn (source=) |
|---|---|---|---|
ohlcv() (tên cũ: history) | Nến giá chứng chỉ quỹ ETF | start, end, interval, length, count_back, limit | dnse, fhsc, ssi, tcbs |
Bảng giá và sổ lệnh
| Hàm | Ý nghĩa | Tham số riêng | Nguồn (source=) |
|---|---|---|---|
order_book() (tên cũ: price_depth) | Ba bậc giá mua, bán tốt nhất của chứng chỉ quỹ ETF | board | dnse, fhsc, tcbs |
quote() (tên cũ: price_board) | Bảng giá chứng chỉ quỹ ETF | board | fhsc, tcbs |
Khớp lệnh và thống kê phiên
| Hàm | Ý nghĩa | Tham số riêng | Nguồn (source=) |
|---|---|---|---|
block_trades() (tên cũ: put_through), không cần mã | Giao dịch thoả thuận đã khớp của chứng chỉ quỹ ETF | exchange, date | tcbs |
session_stats() (tên cũ: trading_stats) | Thống kê gộp nhiều phiên của chứng chỉ quỹ ETF | start, end, length, limit | ssi |
trade_history() | Thống kê từng phiên của chứng chỉ quỹ ETF | start, end, length, limit | ssi |
trades() (tên cũ: intraday) | Khớp lệnh từng lệnh của chứng chỉ quỹ ETF | start, end, limit, board | dnse, tcbs |
volume_profile() (tên cũ: matched_by_price) | Khối lượng khớp theo từng mức giá của chứng chỉ quỹ ETF | date | dnse, tcbs |
Khối ngoại, tự doanh, người nội bộ
| Hàm | Ý nghĩa | Tham số riêng | Nguồn (source=) |
|---|---|---|---|
foreign_flow() | Giao dịch khối ngoại của chứng chỉ quỹ ETF | start, end, interval, length, limit | dnse, fhsc, ssi |
proprietary_flow() | Giao dịch tự doanh của chứng chỉ quỹ ETF | start, end, length, limit | fhsc |
Cột trả về (hồ sơ v5, mặc định)
| Hàm | Cột |
|---|---|
block_trades() | symbol, match_price, match_volume, match_value, accumulated_value, time |
foreign_flow() | time, buy_vol, buy_val, sell_vol, sell_val, net_vol, net_val |
ohlcv() | time, open, high, low, close, volume |
order_book() | bid_price_1, bid_vol_1, bid_price_2, bid_vol_2, bid_price_3, bid_vol_3, ask_price_1, ask_vol_1, ask_price_2, ask_vol_2, ask_price_3, ask_vol_3, time, total_bid_volume, total_ask_volume |
proprietary_flow() | time, buy_vol, buy_val, sell_vol, sell_val, net_vol, net_val |
quote() | symbol, exchange, reference_price, ceiling_price, floor_price, open_price, high_price, low_price, close_price, bid_price_1, bid_vol_1, bid_price_2, bid_vol_2, bid_price_3, bid_vol_3, ask_price_1, ask_vol_1, ask_price_2, ask_vol_2, ask_price_3, ask_vol_3, foreign_buy_volume, foreign_sell_volume, time, price_change, price_change_percent, average_price, total_volume, total_value, foreign_room, next_reference_price, next_ceiling_price, next_floor_price, last_volume |
session_stats() | symbol, time, average_match_volume, average_match_value, average_deal_volume, average_deal_value, average_volume, average_value, total_match_volume, total_match_value, total_deal_volume, total_deal_value, total_volume, total_value, fr_buy_volume_total, fr_buy_value_total, fr_sell_volume_total, fr_sell_value_total, fr_net_volume_total, fr_net_value_total, fr_buy_volume_total_avg, fr_buy_value_total_avg, fr_sell_volume_total_avg, fr_sell_value_total_avg, fr_net_volume_total_avg, fr_net_value_total_avg, total_buy_trade_volume, total_sell_trade_volume, total_buy_trade_volume_avg, total_sell_trade_volume_avg, total_buy_trade, total_sell_trade, total_buy_trade_avg, total_sell_trade_avg, total_net_trade_volume, total_net_trade_volume_avg, average_buy_volume_per_trade, average_sell_volume_per_trade, close_price, reference_price |
trade_history() | trading_date, reference_price, open, close, price_change, percent_price_change, high, low, average_price, matched_volume, matched_value, deal_volume, deal_value, total_volume, total_value, total_buy_trade, total_buy_trade_volume, total_sell_trade, total_sell_trade_volume, symbol, foreign_buy_volume, foreign_buy_value, foreign_sell_volume, foreign_sell_value, foreign_net_volume, foreign_net_value |
trades() | time, price, volume, match_type, id, accumulated_volume |
volume_profile() | price, buy_volume, sell_volume, unknown_volume, total_volume |
Trái phiếu (bond)
Cách gọi: Market("<nguồn>").bond("MÃ").<hàm>(...).
| Hàm | Ý nghĩa | Tham số riêng | Nguồn (source=) |
|---|---|---|---|
ohlcv() (tên cũ: history) | Nến giá trái phiếu niêm yết | start, end, interval, length, count_back, limit | fhsc |
order_book() (tên cũ: price_depth) | Ba bậc giá mua, bán tốt nhất của trái phiếu | board | fhsc |
quote() (tên cũ: price_board) | Bảng giá trái phiếu | board | fhsc |
yield_history() | Lịch sử lợi suất trái phiếu chính phủ 10 năm | start, end | fhsc |
Cột trả về (hồ sơ v5, mặc định)
| Hàm | Cột |
|---|---|
ohlcv() | time, open, high, low, close, volume |
order_book() | bid_price_1, bid_price_2, bid_price_3, ask_price_1, ask_price_2, ask_price_3, time, bid_volume_1, bid_volume_2, bid_volume_3, ask_volume_1, ask_volume_2, ask_volume_3 |
quote() | symbol, exchange, reference_price, time, open, high, low, close, price_change, price_change_percent, total_volume, yield_percent |
yield_history() | time, yield_percent |
Chỉ số (index)
Cách gọi: Market("<nguồn>").index("VNINDEX").<hàm>(...); Market("<nguồn>").index.<hàm>(...) cho hàm ghi không cần mã.
| Hàm | Ý nghĩa | Tham số riêng | Nguồn (source=) |
|---|---|---|---|
breadth() | Độ rộng thị trường của chỉ số, phiên hiện tại | — | fhsc |
comparison(), không cần mã | Bảng so sánh các chỉ số | exchange, window, sort | fhsc |
foreign_flow() | Khối ngoại mua, bán theo chỉ số, theo ngày | start, end, length, limit | fhsc, ssi |
foreign_session() | Giao dịch khối ngoại theo chỉ số, phiên gần nhất | — | fhsc |
ohlcv() (tên cũ: history) | Nến chỉ số | start, end, interval, length, count_back, limit | dnse, fhsc, ssi, tcbs |
proprietary_flow() | Tự doanh công ty chứng khoán mua, bán theo chỉ số, theo ngày | start, end, length, limit | ssi |
quote() (tên cũ: price_board, summary) | Chỉ số trong phiên: giá trị, thay đổi, khối lượng, độ rộng thị trường | start, end | dnse, fhsc, ssi |
trade_history() | Thống kê từng phiên của một chỉ số: giá trị, thanh khoản, độ rộng | start, end, length, limit | ssi |
Cột trả về (hồ sơ v5, mặc định)
| Hàm | Cột |
|---|---|
breadth() | symbol, time, advance_count, decline_count, unchanged_count, limit_up_count, limit_down_count, constituent_count |
comparison() | symbol, name, exchange, close, price_change_percent, market_cap, constituent_count, advance_count, decline_count, unchanged_count, total_volume, total_value, foreign_net_value |
foreign_flow() | time, foreign_buy_volume, foreign_buy_value, foreign_sell_volume, foreign_sell_value, foreign_net_volume, foreign_net_value |
foreign_session() | symbol, time, foreign_buy_volume, foreign_buy_value, foreign_sell_volume, foreign_sell_value, foreign_net_volume, foreign_net_value |
ohlcv() | time, open, high, low, close, volume |
proprietary_flow() | time, proprietary_buy_volume, proprietary_buy_value, proprietary_sell_volume, proprietary_sell_value, proprietary_net_volume, proprietary_net_value |
quote() | symbol, reference_price, high_price, low_price, close_price, total_volume, time, price_change, percent_change, advances, declines, no_change, accumulated_volume, accumulated_value, put_through_volume, put_through_value, ceiling_count, floor_count, advance_volume, decline_volume, unchanged_volume |
trade_history() | trading_date, price_change, percent_price_change, reference_price, close, matched_volume, matched_value, deal_volume, deal_value, total_volume, total_value, total_stock_up_price, total_stock_down_price, total_stock_no_change_price, total_stock_ceiling, total_stock_floor |
Chỉ số quốc tế (index(..., scope="global"))
Cách gọi: Market("<nguồn>").index("MÃ", scope="global").<hàm>(...).
| Hàm | Ý nghĩa | Tham số riêng | Nguồn (source=) |
|---|---|---|---|
history() (tên cũ: ohlcv) | Nến chỉ số quốc tế | start, end, interval, limit | fhsc, fmp |
Cột trả về (hồ sơ v5, mặc định)
| Hàm | Cột |
|---|---|
history() | time, open, high, low, close, volume |
Ngành, diễn biến thị trường (sector)
Cách gọi: Market("<nguồn>").sector("MÃ").<hàm>(...); Market("<nguồn>").sector.<hàm>(...) cho hàm ghi không cần mã.
| Hàm | Ý nghĩa | Tham số riêng | Nguồn (source=) |
|---|---|---|---|
breadth() | Độ rộng của ngành, phiên hiện tại | — | fhsc |
comparison(), không cần mã | Bảng so sánh các ngành | level, parent, window, sort | fhsc |
foreign_flow() | Khối ngoại theo ngành qua các phiên | start, end | fhsc |
foreign_session() | Khối ngoại theo ngành, phiên gần nhất | — | fhsc |
ohlcv() | Lịch sử chỉ số ngành theo phiên | start, end | fhsc |
performance() | Chỉ số ngành, phiên hiện tại | — | fhsc |
Cột trả về (hồ sơ v5, mặc định)
| Hàm | Cột |
|---|---|
breadth() | sector_slug, time, advance_count, decline_count, unchanged_count, limit_up_count, limit_down_count, constituent_count |
comparison() | sector_slug, name, sector_level, close, price_change_percent, market_cap, constituent_count, advance_count, decline_count, unchanged_count, total_volume, total_value, foreign_net_value |
foreign_flow() | time, foreign_buy_volume, foreign_buy_value, foreign_sell_volume, foreign_sell_value, foreign_net_volume, foreign_net_value |
foreign_session() | sector_slug, time, foreign_buy_volume, foreign_buy_value, foreign_sell_volume, foreign_sell_value, foreign_net_volume, foreign_net_value |
ohlcv() | time, open, high, low, close, volume, total_value |
performance() | sector_slug, name, time, reference_price, open, high, low, close, price_change, price_change_percent, total_volume, total_value |
Hợp đồng tương lai (futures)
Cách gọi: Market("<nguồn>").futures("VN30F1M").<hàm>(...).
| Hàm | Ý nghĩa | Tham số riêng | Nguồn (source=) |
|---|---|---|---|
ohlcv() (tên cũ: history) | Nến hợp đồng tương lai: một hợp đồng, hoặc chuỗi liên tục | start, end, interval, length, count_back, limit | dnse, ssi |
order_book() (tên cũ: price_depth) | Ba bậc giá mua, bán tốt nhất của hợp đồng tương lai | — | dnse, tcbs |
quote() (tên cũ: price_board, summary) | Bảng giá hợp đồng tương lai | — | dnse, tcbs |
trades() (tên cũ: intraday) | Từng lệnh khớp hợp đồng tương lai | start, end, limit, board | dnse |
Cột trả về (hồ sơ v5, mặc định)
| Hàm | Cột |
|---|---|
ohlcv() | time, open, high, low, close, volume |
order_book() | bid_price_1, bid_vol_1, bid_price_2, bid_vol_2, bid_price_3, bid_vol_3, ask_price_1, ask_vol_1, ask_price_2, ask_vol_2, ask_price_3, ask_vol_3, time, total_bid_volume, total_ask_volume |
quote() | symbol, exchange, reference_price, ceiling_price, floor_price, open_price, high_price, low_price, close_price, total_volume, bid_price_1, bid_vol_1, bid_price_2, bid_vol_2, bid_price_3, bid_vol_3, ask_price_1, ask_vol_1, ask_price_2, ask_vol_2, ask_price_3, ask_vol_3, basis, open_interest, foreign_buy_volume, foreign_sell_volume, last_trading_date, time, price_change, price_change_percent, average_price |
trades() | time, price, volume, match_type, id, accumulated_volume |
Chứng quyền (warrant)
Cách gọi: Market("<nguồn>").warrant("CFPT2601").<hàm>(...).
| Hàm | Ý nghĩa | Tham số riêng | Nguồn (source=) |
|---|---|---|---|
ohlcv() (tên cũ: history) | Nến chứng quyền | start, end, interval, length, count_back, limit | ssi, tcbs |
order_book() (tên cũ: price_depth) | Sổ lệnh chứng quyền, 3 bước giá | — | dnse |
quote() (tên cũ: price_board, summary) | Bảng giá chứng quyền | — | tcbs |
trades() (tên cũ: intraday) | Khớp lệnh chứng quyền | start, end, limit | dnse |
Cột trả về (hồ sơ v5, mặc định)
| Hàm | Cột |
|---|---|
ohlcv() | time, open, high, low, close, volume |
order_book() | bid_price_1, bid_vol_1, bid_price_2, bid_vol_2, bid_price_3, bid_vol_3, ask_price_1, ask_vol_1, ask_price_2, ask_vol_2, ask_price_3, ask_vol_3, time |
quote() | symbol, exchange, reference_price, ceiling_price, floor_price, open_price, high_price, low_price, close_price, bid_price_1, bid_vol_1, bid_price_2, bid_vol_2, bid_price_3, bid_vol_3, ask_price_1, ask_vol_1, ask_price_2, ask_vol_2, ask_price_3, ask_vol_3, foreign_buy_volume, foreign_sell_volume, break_even_point, underlying_price, time, price_change, price_change_percent, total_volume, exercise_price, conversion_ratio, maturity_date, issuer, underlying_symbol, next_reference_price, next_ceiling_price, next_floor_price, last_volume |
trades() | time, price, volume, match_type, id, accumulated_volume |
Tiền mã hoá (crypto)
Cách gọi: Market("<nguồn>").crypto("BTCUSDT").<hàm>(...).
Nến và giá mới nhất
| Hàm | Ý nghĩa | Tham số riêng | Nguồn (source=) |
|---|---|---|---|
chart_ohlcv() | Nến tiền mã hoá để vẽ biểu đồ: bỏ đoạn lịch sử trước lần gián đoạn gần nhất và phần giá bất thường lúc mở lại | start, end, interval, limit | binance |
last_price() | Giá khớp gần nhất của tiền mã hoá | — | binance, fhsc |
ohlcv() (tên cũ: history) | Nến tiền mã hoá | start, end, interval, limit | binance, fhsc, fmp |
reference_price() | Giá tham chiếu của tiền mã hoá | — | fhsc |
Bảng giá và sổ lệnh
| Hàm | Ý nghĩa | Tham số riêng | Nguồn (source=) |
|---|---|---|---|
best_bid_ask() | Giá mua, giá bán tốt nhất kèm khối lượng tại thời điểm gọi | — | binance |
order_book() (tên cũ: price_depth) | Sổ lệnh tiền mã hoá, 10 bước giá | limit | binance |
quote() (tên cũ: price_board) | Bảng giá tiền mã hoá: giá 24 giờ và bước giá tốt nhất | — | binance, fhsc |
Khớp lệnh và thống kê phiên
| Hàm | Ý nghĩa | Tham số riêng | Nguồn (source=) |
|---|---|---|---|
aggregate_trades() | Khớp lệnh gộp: các lệnh khớp cùng lúc, cùng giá của một lệnh chủ động thành một dòng | start, end, limit | binance |
daily_stats() (tên cũ: summary) | Thống kê ngày giao dịch của tiền mã hoá (ngày UTC) | — | binance |
rolling_stats() | Thống kê cửa sổ trượt của tiền mã hoá (mặc định 1 ngày) | — | binance |
trades() (tên cũ: intraday, trade_history) | Khớp lệnh tiền mã hoá | limit | binance |
vwap() | Giá bình quân gia quyền theo khối lượng trong cửa sổ ngắn | — | binance |
Cột trả về (hồ sơ v5, mặc định)
| Hàm | Cột |
|---|---|
aggregate_trades() | time, price, base_volume, side, trade_id, first_trade_id, last_trade_id |
best_bid_ask() | symbol, time, bid_price_1, bid_amount_1, ask_price_1, ask_amount_1 |
chart_ohlcv() | time, open, high, low, close, volume, quote_volume, trade_count |
daily_stats() | symbol, price_change, price_change_percent, weighted_avg_price, open_price, high_price, low_price, last_price, volume, quote_volume, open_time, close_time, first_id, last_id, count |
last_price() | symbol, price |
ohlcv() | time, open, high, low, close, volume, quote_volume, trade_count |
order_book() | bid_price_1, bid_vol_1, bid_price_2, bid_vol_2, bid_price_3, bid_vol_3, bid_price_4, bid_vol_4, bid_price_5, bid_vol_5, bid_price_6, bid_vol_6, bid_price_7, bid_vol_7, bid_price_8, bid_vol_8, bid_price_9, bid_vol_9, bid_price_10, bid_vol_10, ask_price_1, ask_vol_1, ask_price_2, ask_vol_2, ask_price_3, ask_vol_3, ask_price_4, ask_vol_4, ask_price_5, ask_vol_5, ask_price_6, ask_vol_6, ask_price_7, ask_vol_7, ask_price_8, ask_vol_8, ask_price_9, ask_vol_9, ask_price_10, ask_vol_10, time |
quote() | symbol, reference_price, open_price, high_price, low_price, close_price, bid_price_1, bid_vol_1, ask_price_1, ask_vol_1, time, price_change, price_change_percent, base_volume, quote_volume, average_price, trade_count |
reference_price() | symbol, reference_price, timestamp |
rolling_stats() | symbol, price_change, price_change_percent, weighted_avg_price, open_price, high_price, low_price, last_price, volume, quote_volume, open_time, close_time, first_id, last_id, count |
trades() | time, price, volume, side, id, quote_volume |
vwap() | mins, price, close_time |
Tỷ giá (forex)
Cách gọi: Market("<nguồn>").forex("USDVND").<hàm>(...).
| Hàm | Ý nghĩa | Tham số riêng | Nguồn (source=) |
|---|---|---|---|
ohlcv() (tên cũ: history) | Nến tỷ giá | start, end, interval, limit | fhsc, fmp |
quote() | Giá mua, bán hiện tại của cặp ngoại tệ | — | fhsc |
Cột trả về (hồ sơ v5, mặc định)
| Hàm | Cột |
|---|---|
ohlcv() | time, open, high, low, close, volume |
quote() | symbol, time, bid_price, ask_price |
Hàng hoá (commodity)
Cách gọi: Market("<nguồn>").commodity("MÃ").<hàm>(...).
| Hàm | Ý nghĩa | Tham số riêng | Nguồn (source=) |
|---|---|---|---|
ohlcv() (tên cũ: history) | Nến hàng hoá (vàng, bạc, dầu…) | start, end, interval, limit | fhsc, fmp |
quote() | Giá hiện tại của hàng hoá | — | fhsc |
Cột trả về (hồ sơ v5, mặc định)
| Hàm | Cột |
|---|---|
ohlcv() | time, open, high, low, close, volume |
quote() | symbol, time, reference_price, open, high, low, close, price_change, price_change_percent, total_volume |
Quỹ mở (fund)
Cách gọi: Market("<nguồn>").fund("MÃ").<hàm>(...).
| Hàm | Ý nghĩa | Tham số riêng | Nguồn (source=) |
|---|---|---|---|
history() (tên cũ: nav, ohlcv) | NAV trên một chứng chỉ quỹ mở theo ngày | start, end | fhsc |
performance() | Lợi suất của quỹ mở theo kỳ, tính từ chuỗi NAV | — | fhsc |
Cột trả về (hồ sơ v5, mặc định)
| Hàm | Cột |
|---|---|
history() | time, nav |
performance() | period, period_label, nav_start, nav_end, return_percent, annualized |
Vàng bán lẻ trong nước (gold)
Cách gọi: Retail("<nguồn>").gold.<hàm>(...).
| Hàm | Ý nghĩa | Tham số riêng | Nguồn (source=) |
|---|---|---|---|
history() | Lịch sử giá vàng bán lẻ theo ngày, một sản phẩm hoặc mọi sản phẩm | product, start, end | fhsc |
price() | Giá vàng bán lẻ trong nước theo từng sản phẩm và nhà bán: giá mua vào, giá bán ra | date | fhsc |
Cột trả về (hồ sơ v5, mặc định)
| Hàm | Cột |
|---|---|
history() | name, buy_price, sell_price, time, product_code, seller, seller_name, quantity_unit |
price() | name, buy_price, sell_price, time, product_code, seller, seller_name, quantity_unit |
Bạc bán lẻ trong nước (silver)
Cách gọi: Retail("<nguồn>").silver.<hàm>(...).
| Hàm | Ý nghĩa | Tham số riêng | Nguồn (source=) |
|---|---|---|---|
history() | Lịch sử giá bạc bán lẻ theo ngày, một sản phẩm hoặc mọi sản phẩm | product, start, end | fhsc |
price() | Giá bạc bán lẻ trong nước theo từng sản phẩm và nhà bán: giá mua vào, giá bán ra | date | fhsc |
Cột trả về (hồ sơ v5, mặc định)
| Hàm | Cột |
|---|---|
history() | name, buy_price, sell_price, time, product_code, seller, seller_name, quantity_unit |
price() | name, buy_price, sell_price, time, product_code, seller, seller_name, quantity_unit |
Ý nghĩa tham số riêng {#y-nghia-tham-so-rieng}
| Tham số | Ý nghĩa | Mặc định |
|---|---|---|
board | Bảng giao dịch; None trả mọi bảng | G1 |
count_back | Số dòng mới nhất cần lấy | None |
date | Một ngày giao dịch | None = ngày giao dịch gần nhất |
end | Ngày kết thúc, tính cả ngày đó | None = hôm nay giờ Việt Nam |
exchange | Lọc theo sàn | None = mọi sàn |
group | Lọc theo rổ chỉ số (VN30, HNX30…) | None |
index | Rổ chỉ số | — |
interval | Khung thời gian | 1D |
investor | Nhóm nhà đầu tư: all, sheep, wolf, shark | — |
length | Số nến (100, "100b") hoặc khoảng thời gian ("3M", "1Y", "10d") tính lùi từ end | None |
level | Cấp ngành trong cây ICB: 1 hoặc 3 | — |
limit | Số dòng tối đa; không có khung thời gian thì là số dòng mới nhất (mặc định 100 với chuỗi thời gian) | None |
parent | Mã ngành cấp 1 để lấy các nhóm ngành con | — |
product | Mã sản phẩm vàng, bạc (cột product_code); bỏ trống là mọi sản phẩm | — |
sector | Mã ngành cấp 1 | — |
sort | Trường sắp xếp, thêm dấu trừ ở đầu để giảm dần | — |
start | Ngày bắt đầu | None |
window | Cửa sổ luỹ kế của các trường dòng tiền: 1D, 1W, 1M, 3M, 6M, 1Y, YTD | — |
Cấu trúc bảng dữ liệu trả về của các hàm phổ biến
- Nến lịch sử (
equity("FPT").ohlcv()): gồm 6 cột chuẩn —time(kiểudatetime64[us, Asia/Ho_Chi_Minh], nến ngày mang mốc07:00+07:00),open,high,low,close(kiểufloat64, tính bằng nghìn đồng ở cả hai hồ sơv5vàv6, đã điều chỉnh theo sự kiện quyền) vàvolume(kiểuint64ởv5,Int64ởv6, đơn vị cổ phiếu). - Bảng giá (
equity("FPT").quote()): gồm 34 cột chuẩn; các cột giá (reference_price,ceiling_price,floor_price,open_price,close_price,bid_price_1..3,ask_price_1..3…) tính bằng đồng ở hồ sơv5và được quy đổi đồng nhất về nghìn đồng ở hồ sơv6(open,close,bid_volume_1…). - Khớp lệnh từng lệnh (
equity("FPT").trades()): gồmtime,price(nghìn đồng),volume,match_type(Buy,Sell,ATO,ATC,Unknownở hồ sơv5; tách thành hai cộtsidevàsessionở hồ sơv6),id(kiểustring— số thứ tự dòng trong lần truy vấn hiện tại, không phải mã lệnh cố định của sở giao dịch để ghép nối giữa hai lần gọi) vàaccumulated_volume. - Giao dịch khối ngoại (
equity("FPT").foreign_flow()): gồmtime,buy_vol,buy_val,sell_vol,sell_val,net_vol,net_val— ở hồ sơv5xếp phiên mới nhất lên đầu với mốc00:00+07:00; sang hồ sơv6xếp tăng dần theo thời gian với mốc07:00+07:00để ghép thẳng với bảng nến.
Cách truyền mã hợp đồng tương lai phái sinh
Khi làm việc với nhóm futures(...), bạn có thể truyền mã hợp đồng theo bất kỳ quy ước nào dưới đây. Thư viện sẽ tự động chuyển đổi sang định dạng mà nguồn đang chọn yêu cầu, giúp một mã mang cùng một ý nghĩa xuyên suốt mọi nguồn:
| Định dạng mã | Ví dụ minh hoạ | Ý nghĩa |
|---|---|---|
| Mã chuẩn KRX | 41I1GB000 | Chỉ định đúng hợp đồng cụ thể đó, tính từ ngày niêm yết đến ngày đáo hạn |
| Mã theo năm tháng | VN30F2611 | Chỉ định đúng hợp đồng đáo hạn tháng 11/2026, tương đương với mã KRX ở trên |
| Mã kỳ hạn liên tục | VN30F1M, VN30F2M, VN30F1Q, VN30F2Q | Chuỗi nối tiếp các hợp đồng theo vị trí kỳ hạn (tháng hiện tại, tháng kế tiếp, quý hiện tại, quý kế tiếp) |
Market("<nguồn>").futures("41I1GB000").ohlcv(start="2026-10-01", end="2026-11-07")
Market("<nguồn>").futures("VN30F2611").ohlcv(start="2026-10-01", end="2026-11-07") # trả về cùng một kết quả- Lưu ý khi dùng mã liên tục (
VN30F1M...): chuỗi giá sẽ có bước nhảy khi chuyển giao sang hợp đồng mới vào ngày đáo hạn. Thuộc tínhdf.attrs["contract_since"]cho biết ngày bắt đầu của hợp đồng hiện hành trong chuỗi. Nếu mô hình định lượng của bạn nhạy cảm với bước nhảy ngày đáo hạn, hãy truyền mã chuẩn KRX hoặc mã theo năm tháng của từng hợp đồng. - Với những nguồn không lưu lịch sử nến theo từng mã hợp đồng riêng lẻ, thư viện sẽ tự động ghép từ các chuỗi kỳ hạn liên tục (mỗi vị trí kỳ hạn là một yêu cầu mạng, tính theo quy tắc đáo hạn vào thứ Năm tuần thứ ba của tháng). Nếu ngày đáo hạn thực tế bị dời sớm do trùng ngày nghỉ lễ, phiên chuyển giao đó có thể chênh lệch nhẹ.
- Nếu truyền nhầm mã cổ phiếu cơ sở vào nhóm phái sinh (chẳng hạn
futures("FPT")), thư viện sẽ báo lỗiVNSTOCK_INPUT_SYMBOLkèm hướng dẫn các định dạng mã hợp lệ.
Lưu ý khi lấy dữ liệu nến trong phiên và sau giờ đóng cửa
- Các thanh nến trong ngày có khối lượng bằng 0 (nến đệm không có giao dịch) đều được lọc bỏ tự động ở mọi nguồn; số lượng dòng đã lược bỏ được ghi tại
df.attrs["rows_dropped_padding"]. - Phiên khớp lệnh định kỳ đóng cửa (ATC) được gom vào thanh nến mốc
14:45. Thanh nến này có thể chưa đủ ngay lúc 14:45; nếu bạn cần dữ liệu phiên đã chốt đầy đủ, hãy truy xuất sau 15:30. - Sàn HNX có thêm phiên giao dịch sau giờ từ 14:45 đến 15:00 (PLO). Tuỳ thuộc vào quy ước của từng nguồn dữ liệu mà khối lượng khớp trong khung giờ này có thể được gộp hoặc không gộp vào nến ngày.
Tra cứu giá vàng và bạc bán lẻ trong nước (Lớp Retail)
Lớp Retail giúp bạn lấy bảng giá mua vào – bán ra của các sản phẩm vàng và bạc bán lẻ từ các thương hiệu trong nước (qua nguồn fhsc). Bạn không cần nhớ mã từng loại vàng: mỗi lời gọi tự động trả về đầy đủ danh mục sản phẩm.
from vnstock import Retail
Retail("fhsc").gold() # bảng giá hiện tại của 10 sản phẩm vàng
Retail("fhsc").gold(date="2026-11-05") # bảng giá tại một ngày trong quá khứ
Retail("fhsc").gold.history("GOLD_BAR_SJC", start="2026-10-01") # chuỗi lịch sử của một sản phẩm cụ thể
Retail("fhsc").gold.history(start="2026-11-01") # chuỗi lịch sử của toàn bộ sản phẩm
Retail("fhsc").silver() # bảng giá bạc bán lẻ hiện tạiBảng kết quả gồm các cột name, buy_price, sell_price, time, product_code, seller, seller_name và quantity_unit. Trong đó, buy_price là giá cửa hàng mua vào và sell_price là giá cửa hàng bán ra, tính theo đơn vị nghìn đồng một chỉ (ví dụ: giá trị 13700 tương ứng với 13,7 triệu đồng/chỉ). Lưu ý khi gọi gold.history() cho toàn bộ sản phẩm, mỗi sản phẩm sẽ phát sinh một yêu cầu tới nguồn.
Đặc thù dữ liệu tiền mã hoá: khớp lệnh gộp và nến biểu đồ
- Khớp lệnh gộp (
aggregate_trades(start=None, end=None, limit=None)): gộp các lệnh khớp diễn ra cùng thời điểm, cùng mức giá của cùng một lệnh đặt chủ động thành một dòng duy nhất; hai cộtfirst_trade_idvàlast_trade_idcho biết khoảng mã lệnh gốc đã được gộp. Khi truyền tham sốstart, thư viện tự động lật trang đến hết ngày theo giờ UTC (tối đa 250 trang); với những cặp có mật độ giao dịch rất lớn vượt ngưỡng 250 trang, kết quả sẽ kèm cảnh báoVNSTOCK_DATA_TRUNCATED. - Giá chào mua/bán tốt nhất (
best_bid_ask()): trả về mức giá đặt mua cao nhất và giá chào bán thấp nhất kèm khối lượng tại thời điểm gọi. - Nến vẽ biểu đồ (
chart_ohlcv(...)): trả về chuỗi nến phục vụ hiển thị biểu đồ của nguồn (không phải giá điều chỉnh). Chuỗi này có thể khác hàmohlcv()chuẩn ở những mã từng tạm ngừng giao dịch rồi giao dịch trở lại, vì đoạn lịch sử trước lần gián đoạn có thể không được giữ. Do đó, khi nghiên cứu và kiểm thử định lượng, bạn nên dùng hàmohlcv()để giữ trọn vẹn lịch sử giao dịch.
Cách tải toàn bộ dữ liệu khớp lệnh trong phiên (trades)
Hàm trades() tự động lật qua từng trang dữ liệu để lấy đủ các lệnh khớp trong khoảng thời gian bạn yêu cầu. Với nguồn dnse, nếu không truyền ngày, thư viện sẽ lấy phiên giao dịch gần nhất (nếu gọi vào cuối tuần sẽ lấy dữ liệu phiên thứ Sáu).
Số bản ghi tối đa trên mỗi trang do từng nguồn quy định, nên những mã có thanh khoản lớn sẽ cần nhiều yêu cầu tuần tự. Thư viện đặt một ngưỡng dừng an toàn về số trang và ghi cảnh báo vào log khi chạm ngưỡng. Khi gặp cảnh báo chạm trần phân trang, bạn chỉ cần chia nhỏ khoảng thời gian (start, end) thành các khung giờ ngắn hơn để lấy tiếp.
Các hàm chưa hỗ trợ và bí danh tương thích từ thế hệ 5
Những hàm từng có ở thế hệ 5 nhưng hiện chưa có nguồn dữ liệu tương ứng trên cổng Open API của thế hệ 6 vẫn giữ nguyên tên để không gây lỗi cú pháp, nhưng khi gọi sẽ phát cảnh báo CompatibilityWarning và trả về lỗi UnsupportedError có mã VNSTOCK_ROUTE_UNSUPPORTED (thay vì trả về bảng rỗng dễ gây hiểu lầm). Bạn có thể dùng dir(Market("<nguồn>").equity("FPT")) hoặc chạy lệnh vnstock tools Market --all trong Terminal để xem toàn bộ danh sách hàm, bao gồm cả những hàm chưa có nguồn.
Các cách gọi tắt trực tiếp trên Market() từ thế hệ 5 vẫn hoạt động bình thường và trả về đúng bảng của nhóm cổ phiếu:
Market("<nguồn>").quote("FPT,VNM")tương đương vớiMarket("<nguồn>").equity.quote("FPT,VNM");Market("<nguồn>").put_through()tương đương vớiMarket("<nguồn>").equity.block_trades();Market("<nguồn>").future(...)tương đương vớiMarket("<nguồn>").futures(...).
Quy ước mã chỉ số quốc tế, tỷ giá ngoại hối và hàng hoá
Market("<nguồn>").index("SPX", scope="global").ohlcv(start="2026-10-01")
Market("<nguồn>").forex("USDVND").ohlcv(start="2026-10-01")
Market("<nguồn>").commodity("GC").ohlcv(start="2026-10-01")Bảng mã chuẩn cho chỉ số chứng khoán quốc tế:
Bạn có thể truyền mã chuẩn ở cột đầu tiên cho bất kỳ nguồn nào. Các cách viết quen thuộc khác (như ^GSPC, SP500, JPN225…) vẫn được thư viện tự động nhận diện và ánh xạ về mã chuẩn chung (ghi nhận tại df.attrs["symbol"]). Nếu nguồn đang chọn không có dữ liệu của chỉ số đó, hàm sẽ báo lỗi VNSTOCK_INPUT_SYMBOL kèm danh sách các mã khả dụng trên nguồn.
| Mã chuẩn chung | Tên chỉ số quốc tế | Nguồn hỗ trợ (source=) |
|---|---|---|
SPX | S&P 500 (Mỹ) | fmp, fhsc |
DJI | Dow Jones Industrial Average (Mỹ) | fmp, fhsc |
IXIC | Nasdaq Composite (Mỹ) | fmp, fhsc |
NDX | Nasdaq 100 (Mỹ) | fmp |
RUT | Russell 2000 (Mỹ) | fmp, fhsc |
VIX | CBOE Volatility Index | fmp, fhsc |
DXY | U.S. Dollar Index | fmp, fhsc |
N225 | Nikkei 225 (Nhật Bản) | fmp, fhsc |
HSI | Hang Seng (Hồng Kông) | fmp, fhsc |
SSEC | Shanghai Composite (Trung Quốc) | fmp, fhsc |
KS11 | KOSPI (Hàn Quốc) | fmp, fhsc |
SET | SET Index (Thái Lan) | fmp, fhsc |
JKSE | Jakarta Composite (Indonesia) | fmp, fhsc |
PSEI | PSEi (Philippines) | fhsc |
FTSE | FTSE 100 (Anh) | fmp |
GDAXI | DAX (Đức) | fmp |
FCHI | CAC 40 (Pháp) | fmp |
STOXX50E | Euro Stoxx 50 (Châu Âu) | fmp |
AXJO | S&P/ASX 200 (Úc) | fmp |
FTSEEM | FTSE Emerging Markets | fhsc |
Các mã nằm ngoài bảng quy đổi trên sẽ được gửi nguyên văn tới nguồn dữ liệu.
Tất cả các nhóm tài sản quốc tế đều trả về cột thời gian time theo múi giờ chuẩn UTC. Khi truyền mã tài sản, bạn lưu ý:
- Chỉ số quốc tế (
index): dùng chung phương thức.index(...)nhưng thêm tham sốscope="global"(mặc địnhscope="vn"dành cho chỉ số trong nước). Không nên trộn lẫn số liệu của hai nguồn trong cùng một chuỗi thời gian. - Tỷ giá ngoại hối (
forex) và tiền mã hoá (crypto): viết liền cặp tiền tệ định giá nhưUSDVND,EURUSD,BTCUSDT. - Hàng hoá quốc tế (
commodity): truyền mã hợp đồng hàng hoá nhưGChoặcGCUSDtuỳ theo nguồn (bạn có thể dùngReference("fmp").search.symbol(...)để tìm mã trênfmphoặcReference("fhsc").commodity.list()trênfhsc). Riêng bảng tỷ giá niêm yết tại các ngân hàng thương mại của lớpRetailthế hệ 5 hiện chưa có trên các cổng Open API (Retail().exchange_rate()sẽ trả về mã lỗiVNSTOCK_ROUTE_UNSUPPORTED).
