Dữ liệu giao dịch (Trading & Quote)

Trong vnstock_data, dữ liệu thị trường và giao dịch được phân chia thành 2 module chính:

Module Quote: Trích xuất dữ liệu lịch sử giá OHLCV, khớp lệnh trong ngày (intraday), và độ sâu thị trường từ nhiều nguồn (VCI, KBS, VND, MAS) chuẩn hóa chung một cấu trúc.
Module Trading: Truy xuất các bảng giá trong phiên đặc thù, thống kê khối ngoại, tự doanh, và giao dịch nội bộ.

Phần I: Module Quote

Module quote cung cấp các hàm chuyên biệt để truy xuất dữ liệu thị trường (market data) bao gồm: lịch sử giá OHLCV, dữ liệu khớp lệnh trong ngày (intraday), và độ sâu thị trường (price depth/order book).

Hiện tại, module này hỗ trợ 4 nguồn dữ liệu chính thông qua cơ chế unified wrapper: VCI, KBS, VND, và MAS.

Khởi tạo

Để sử dụng, bạn khởi tạo class Quote từ package vnstock_data. Class này sẽ tự động routing request đến implementation phù hợp dựa trên tham số source.

Python

from vnstock_data import Quote

# Khởi tạo quote adapter với nguồn dữ liệu VCI (mặc định KBS nếu không truyền source)
quote = Quote(source='VCI')

Tham số khởi tạo:

Tham số	Kiểu dữ liệu	Mặc định	Mô tả
`source`	`str`	`'KBS'`	Mã nguồn dữ liệu. Hỗ trợ: `'VCI'`, `'KBS'`, `'VND'`, `'MAS'`.
`symbol`	`str`	`""`	(Tùy chọn) Mã chứng khoán (cổ phiếu, chỉ số, hợp đồng tương lai, chứng quyền, ETF, trái phiếu, vv) mặc định cho các gọi hàm sau này.

2. Lịch sử giá (History)

Truy xuất dữ liệu lịch sử giá (OHLCV) theo khung thời gian ngày. Dữ liệu này đã được điều chỉnh kỹ thuật (adjusted price) phù hợp để vẽ biểu đồ kỹ thuật.

Hàm: `history`

Python

def history(self, symbol=None, start=None, end=None, interval='1D', length=None)

Tham số:

symbol (str): Mã chứng khoán hoặc mã chỉ số.
- Hỗ trợ Index: HNXINDEX, UPCOMINDEX, VN30, VN100, HNX30 (chỉ khung ngày).
- Hỗ trợ Phái sinh: Tự động nhận diện và chuyển đổi mã hợp đồng tương lai sang kiểu mới để gọi hàm (Ví dụ: VN30F1M -> 41I1G2000).
start (str): Ngày bắt đầu (định dạng YYYY-mm-dd). Bắt buộc nếu không có length.
end (str): Ngày kết thúc (định dạng YYYY-mm-dd). Mặc định là ngày hiện tại.
length (str | int): Khoảng thời gian lấy dữ liệu kể từ end ngược về quá khứ.
- Ví dụ: '1M' (1 tháng), '3M' (3 tháng), '1Y' (1 năm), '2W' (2 tuần).
- Nếu dùng length, start và end sẽ được tự động tính toán.
interval (str): Khung thời gian.
- '1D' (Daily): Hỗ trợ bởi tất cả các nguồn (VCI, KBS, VND, MAS).
- '1m' (1 Minute): Hỗ trợ bởi tất cả các nguồn (dữ liệu ngắn hạn).
- '1H' (Hourly): Ổn định nhất trên VCI và MAS.
- Các khung khác tùy nguồn: '5m', '15m', '30m'.

Dữ liệu trả về (DataFrame):

Tất cả các nguồn dữ liệu đều được chuẩn hóa bao gồm: time, open, high, low, close, volume.

Ví dụ sử dụng

Python

from vnstock_data import Quote

quote = Quote(source='VCI')

# Cách 1: Sử dụng Start/End
df = quote.history(symbol='TCB', start='2023-12-01', end='2023-12-05', interval='1D')

# Cách 2: Sử dụng Length (tiện lợi)
# Lấy dữ liệu 3 tháng gần nhất, khung 1 giờ
df = quote.history(symbol='TCB', length='3M', interval='1H')

print(df.tail())

Kết quả mẫu:

        time   open   high    low  close   volume
0 2023-12-01  13.98  14.10  13.86  14.05  2696825
1 2023-12-04  14.08  14.41  14.08  14.27  4762393
2 2023-12-05  14.29  14.31  14.12  14.20  3094771

Hỗ trợ chỉ số thị trường

Ngoài mã cổ phiếu, bạn có thể truyền vào các mã chỉ số thị trường phổ biến. Các mã này được hỗ trợ trên tất cả các nguồn (VCI, KBS, VND, MAS):

Mã chỉ số	Mô tả
`VNINDEX`	Chỉ số VN-Index (HOSE)
`VN30`	Chỉ số VN30
`HNX`	Chỉ số HNX-Index
`UPCOM`	Chỉ số UPCoM-Index

Một số dạng chỉ số khác được hỗ trợ tuỳ nguồn ví dụ VND:

VN30, VN100, HNX30, VNSML, VNMID, VNALL

Chỉ Số Ngành:

VNREAL - Bất động sản
VNMAT - Nguyên vật liệu
VNIT - Công nghệ
VNHEAL - Chăm sóc sức khỏe
VNFINSELECT, VNFIN - Tài chính
VNENE - Năng lượng
VNCONS, VNCOND - Hàng tiêu dùng Ví dụ lấy lịch sử VNINDEX:

Python

df_index = quote.history(symbol='VNINDEX', start='2023-01-01', end='2023-01-31')

3. Khớp lệnh trong ngày (Intraday)

Truy xuất danh sách các lệnh đã khớp (order matching) trong phiên theo độ trễ của nguồn hoặc lịch sử của một mã chứng khoán.

Hàm: `intraday`

Python

def intraday(self, symbol=None, page_size=100)

Tham số:

symbol (str): Mã chứng khoán.
page_size (int): Số lượng bản ghi muốn lấy trong một lần gọi (paging).

Dữ liệu trả về:

Cấu trúc dữ liệu có sự khác biệt nhỏ giữa các nguồn:

Nguồn	Các cột trả về
VCI / KBS	`time`, `price`, `volume`, `match_type`, `id`
MAS	`time`, `price`, `volume`, `match_type` (không có `id`)
VND	Hiện tại chưa đẩy đủ các method như KBS và VCI, MAS

Ví dụ sử dụng

Python

from vnstock_data import Quote

# Sử dụng nguồn VCI cho dữ liệu Intraday chi tiết
quote = Quote(source='VCI')
df = quote.intraday(symbol='TCB', page_size=10)
print(df.head())

Kết quả mẫu (VCI Source):

                       time  price  volume match_type         id
0 2024-01-30 14:29:19+07:00  35.25     200       Sell  429964787
1 2024-01-30 14:29:23+07:00  35.25     100       Sell  429965133
2 2024-01-30 14:29:23+07:00  35.25    1800       Sell  429965132
3 2024-01-30 14:29:27+07:00  35.25     500        Buy  429965494
4 2024-01-30 14:29:42+07:00  35.25    1000        Buy  429967143

4. Độ sâu thị trường (Price Depth)

Truy xuất thông tin độ sâu thị trường, bao gồm các mức giá đặt mua (bid) và đặt bán (ask) tốt nhất cùng khối lượng tương ứng.

Hàm: `price_depth`

Python

def price_depth(self, symbol=None)

Tham số:

symbol (str): Mã chứng khoán.

Dữ liệu trả về (DataFrame):

Nguồn	Các cột trả về
VCI / MAS	`price` (Giá), `volume` (Tổng KL), `buy_volume` (KL Mua), `sell_volume` (KL Bán), `undefined_volume`
KBS	`price`, `buyVol` (KL Mua), `sellVol` (KL Bán), `unknownVol`, `totalVol` (Tổng KL)
VND	Chưa hỗ trợ

Ví dụ sử dụng

Python

from vnstock_data import Quote

quote = Quote(source='VCI')
df = quote.price_depth(symbol='TCB')
print(df.head())

Kết quả mẫu (VCI Source):

     price     volume  buy_volume  sell_volume  undefined_volume
0  35900.0  3424400.0         0.0          0.0         3424400.0
1  35300.0   328100.0    316900.0      11200.0               0.0

Tổng kết so sánh nguồn dữ liệu

Tính năng	VCI	KBS	VND	MAS
Lịch sử giá (History)	✅ Ổn định	✅ Ổn định	✅ Ổn định	✅ Ổn định
Intraday	✅ Chi tiết	✅ Chi tiết	❌ Không hỗ trợ	✅ Cơ bản
Price Depth	✅ Có	✅ Có	❌ Không hỗ trợ	✅ Có
Chỉ số thị trường	✅ Có	✅ Có	✅ Có	✅ Có

Khuyến nghị:

Sử dụng VCI, KBS hoặc MAS cho nhu cầu dữ liệu History và Intraday vì tính ổn định và chi tiết cao. Dùng VND để lấy dữ liệu history cho các mã chỉ số đa dạng. Không sử dụng nguồn VCI trên Google Colab hoặc dịch vụ liên quan Google Cloud do chính sách chặn IP từ nguồn dữ liệu này.

Phần II: Module Trading

Module Trading cung cấp các hàm để truy xuất dữ liệu giao dịch trong phiên (bảng giá), lịch sử giá, thống kê giao dịch khối ngoại (Foreign), tự doanh (Proprietary), và giao dịch nội bộ (Insider Dealing).

Điểm Nổi Bật & Lưu Ý Nguồn Dữ Liệu

Nguồn	Đặc Điểm	Độ Trễ / Tần Suất	Lưu Ý Quan Trọng
VCI	Nguồn dữ liệu phong phú nhất. Phân tách rõ ràng các hàm lấy dữ liệu Khối ngoại, Tự doanh, Summary.	Trong phiên (theo độ trễ của nguồn) cho bảng giá. T-1 cho lịch sử.	Dữ liệu lịch sử thường chốt vào cuối ngày giao dịch.
KBS	Hỗ trợ bảng giá trong phiên cập nhật nhanh (T). Gộp chung thông tin khối ngoại trong lịch sử giá/bảng giá.	Trong phiên (Cập nhật tại ngày giao dịch hiện tại).	Hàm `trade_history` là thuật ngữ chuẩn mới (thay thế `price_history`).
CafeF	Nguồn dữ liệu lịch sử lâu đời.	T-1 (thường cập nhật sau phiên).	Lưu ý: Dữ liệu đôi khi bị khuyết ngày không rõ lý do. Nên dùng đối chiếu hoặc dự phòng.

1. Khởi Tạo & Sử Dụng

Python

from vnstock_data import Trading

# Khởi tạo
tr_vci = Trading(symbol='TCB', source='VCI') 
tr_kbs = Trading(symbol='TCB', source='KBS')

# Lấy lịch sử giá
df_hist = tr_vci.price_history(start='2024-01-01', end='2024-01-31')

# Lấy bảng giá realtime
df_board = tr_kbs.price_board(['TCB', 'VNM'])

2. Chi Tiết Nguồn VCI (Vietcap)

Bảng Giá (Realtime)

price_board(symbols_list, board='stock'|'odd_lot'|'put_through')

Field	Type	Description
`listing_symbol`	`str`	Mã chứng khoán
`listing_exchange`	`str`	Sàn giao dịch
`match_price`	`float`	Giá khớp gần nhất
`match_vol`	`float`	Khối lượng khớp
`highest`	`float`	Giá cao nhất
`lowest`	`float`	Giá thấp nhất
`avg_match_price`	`float`	Giá khớp bình quân

Lịch Sử Giá

price_history(start, end, ...)

Field	Type	Description
`trading_date`	`datetime`	Ngày giao dịch
`open`	`float`	Giá mở cửa
`high`	`float`	Giá cao nhất
`low`	`float`	Giá thấp nhất
`close`	`float`	Giá đóng cửa
`matched_volume`	`float`	Khối lượng khớp lệnh
`price_change`	`float`	Thay đổi giá so với phiên trước
`percent_price_change`	`float`	% thay đổi giá

Summary (Thống kê tổng hợp)

summary(start, end, ...)

Field	Type	Description
`average_match_volume`	`float`	Khối lượng khớp lệnh trung bình
`average_deal_volume`	`float`	Khối lượng thỏa thuận trung bình
`total_match_volume`	`float`	Tổng khối lượng khớp lệnh trong kỳ
`total_deal_volume`	`float`	Tổng khối lượng thỏa thuận trong kỳ
`fr_net_volume_total`	`float`	Tổng khối lượng ròng khối ngoại

Foreign Trade (Khối ngoại)

foreign_trade(start, end)

Field	Type	Description
`trading_date`	`datetime`	Ngày giao dịch
`fr_buy_value_matched`	`float`	Giá trị mua khớp lệnh
`fr_sell_value_matched`	`float`	Giá trị bán khớp lệnh
`fr_net_value_total`	`float`	Giá trị ròng tổng quát
`fr_total_room`	`float`	Room khối ngoại tối đa
`fr_current_room`	`float`	Room khối ngoại hiện tại

Proprietary Trade (Tự doanh)

prop_trade(start, end)

Field	Type	Description
`trading_date`	`datetime`	Ngày giao dịch
`total_buy_trade_volume`	`float`	Tổng khối lượng mua tự doanh
`total_sell_trade_volume`	`float`	Tổng khối lượng bán tự doanh
`total_trade_net_value`	`float`	Giá trị ròng tự doanh
`percent_buy_trade_volume`	`float`	% Tỷ trọng mua tự doanh

Insider Deal (Giao dịch nội bộ)

insider_deal(limit, ...)

Field	Type	Description
`trader_name`	`str`	Người thực hiện giao dịch
`trader_position`	`str`	Chức vụ
`event_name`	`str`	Loại sự kiện (GD nội bộ...)
`action_type`	`str`	Loại hành động (Mua/Bán)
`start_date`	`datetime`	Ngày bắt đầu đăng ký
`end_date`	`datetime`	Ngày kết thúc đăng ký
`share_register`	`float`	Lượng đăng ký
`share_acquire`	`float`	Lượng thực hiện

3. Chi Tiết Nguồn KBS (KB Securities)

Price Board (Bảng giá)

price_board(symbols_list, board='stock'|'odd_lot'|'put_through')

Field	Type	Description
`symbol`	`str`	Mã chứng khoán
`time`	`int`	Timestamp cập nhật (ms)
`ceiling_price`	`int`	Giá trần
`floor_price`	`int`	Giá sàn
`bid_price_1`...`3`	`float`	Giá đặt mua
`ask_price_1`...`3`	`float`	Giá đặt bán
`foreign_buy_volume`	`int`	Khối lượng nước ngoài mua
`foreign_sell_volume`	`int`	Khối lượng nước ngoài bán

Matched By Price (Intraday)

matched_by_price()

Field	Type	Description
`price`	`int`	Mức giá khớp
`buyVol`	`int`	Khối lượng mua chủ động
`sellVol`	`int`	Khối lượng bán chủ động
`totalVol`	`int`	Tổng khối lượng khớp tại mức giá

Trade History

trade_history(): Dữ liệu lịch sử giao dịch (bao gồm cả OHLCV và Foreign). (Cấu trúc tương tự Price History nhưng có thêm cột Foreign)

4. Chi Tiết Nguồn CafeF

Thông tin cơ bản

price_history: open, high, low, close, matched_volume, change_pct.

Foreign Trade (Khối ngoại)

foreign_trade: fr_buy_volume, fr_sell_volume, fr_net_volume, fr_ownership (% sở hữu).

Proprietary Trade (Tự doanh)

prop_trade: prop_buy_volume, prop_sell_volume (đã chuẩn hóa prefix prop_).

Insider Deal

insider_deal

Field	Type	Description
`transaction_man`	`str`	Người giao dịch
`transaction_man_position`	`str`	Chức vụ
`plan_buy_volume`	`int`	Lượng mua đăng ký
`real_buy_volume`	`int`	Lượng mua thực tế
`transaction_note`	`str`	Ghi chú giao dịch

Order Stats (Thống kê lệnh)

order_stats

Field	Type	Description
`buy_orders`	`int`	Số lệnh mua
`sell_orders`	`int`	Số lệnh bán
`buy_volume`	`int`	Khối lượng đặt mua
`sell_volume`	`int`	Khối lượng đặt bán
`avg_buy_order_volume`	`int`	Trung bình lệnh mua

Dữ liệu giao dịch (Trading & Quote)

Mục lục

Phần I: Module Quote

Khởi tạo

2. Lịch sử giá (History)

Hàm: `history`

Ví dụ sử dụng

Hỗ trợ chỉ số thị trường

3. Khớp lệnh trong ngày (Intraday)

Hàm: `intraday`

Ví dụ sử dụng

4. Độ sâu thị trường (Price Depth)

Hàm: `price_depth`

Ví dụ sử dụng

Tổng kết so sánh nguồn dữ liệu

Phần II: Module Trading

Điểm Nổi Bật & Lưu Ý Nguồn Dữ Liệu

1. Khởi Tạo & Sử Dụng

2. Chi Tiết Nguồn VCI (Vietcap)

Bảng Giá (Realtime)

Lịch Sử Giá

Summary (Thống kê tổng hợp)

Foreign Trade (Khối ngoại)

Proprietary Trade (Tự doanh)

Insider Deal (Giao dịch nội bộ)

3. Chi Tiết Nguồn KBS (KB Securities)

Price Board (Bảng giá)

Matched By Price (Intraday)

Trade History

4. Chi Tiết Nguồn CafeF

Thông tin cơ bản

Foreign Trade (Khối ngoại)

Proprietary Trade (Tự doanh)

Insider Deal

Order Stats (Thống kê lệnh)

Thảo luận

Mục lục

Phần I: Module Quote

Khởi tạo

2. Lịch sử giá (History)

Hàm: history

Ví dụ sử dụng

Hỗ trợ chỉ số thị trường

3. Khớp lệnh trong ngày (Intraday)

Hàm: intraday

Ví dụ sử dụng

4. Độ sâu thị trường (Price Depth)

Hàm: price_depth

Ví dụ sử dụng

Tổng kết so sánh nguồn dữ liệu

Phần II: Module Trading

Điểm Nổi Bật & Lưu Ý Nguồn Dữ Liệu

1. Khởi Tạo & Sử Dụng

2. Chi Tiết Nguồn VCI (Vietcap)

Bảng Giá (Realtime)

Lịch Sử Giá

Summary (Thống kê tổng hợp)

Foreign Trade (Khối ngoại)

Proprietary Trade (Tự doanh)

Insider Deal (Giao dịch nội bộ)

3. Chi Tiết Nguồn KBS (KB Securities)

Price Board (Bảng giá)

Matched By Price (Intraday)

Trade History

4. Chi Tiết Nguồn CafeF

Thông tin cơ bản

Foreign Trade (Khối ngoại)

Proprietary Trade (Tự doanh)

Insider Deal

Order Stats (Thống kê lệnh)

Thảo luận

Hàm: `history`

Hàm: `intraday`

Hàm: `price_depth`