Lớp Market: hàm truy xuất dữ liệu giá và khớp lệnh

📌 Tổng Quan

Market Layer giúp bạn truy xuất dữ liệu trong phiên & lịch sử về giá, khối lượng, vốn hóa, thanh khoản từ các nguồn bên thứ ba. Đây là dữ liệu thay đổi liên tục, phục vụ phân tích kỹ thuật, nghiên cứu thị trường và theo dõi danh mục.

🏗️ Cấu Trúc Domain

Market()
├── .equity(symbol)        # Thị trường cổ phiếu
├── .index(symbol)         # Thị trường chỉ số
├── .futures(symbol)       # Thị trường hợp đồng tương lai
├── .warrant(symbol)       # Thị trường chứng quyền
├── .bond(symbol)          # Thị trường trái phiếu
├── .etf(symbol)           # Thị trường ETF
├── .crypto(symbol)        # Tiền mã hoá
├── .forex(symbol)         # Ngoại hối
├── .commodity(symbol)     # Hàng hoá quốc tế
└── .quote(symbols_list)   # Bảng giá nhiều mã

⚙️ Cấu Trúc Tham Số

Đa số các phương thức trong Market Layer đều tuân theo hệ thống tham số chuẩn hóa:

1. Dữ liệu Lịch sử (Historical Data)

Các hàm lấy chuỗi thời gian như ohlcv(), trade_history(), foreign_flow(), proprietary_flow()... hỗ trợ:

• start (str): Ngày bắt đầu lấy dữ liệu (VD: "2024-01-01").
• end (str): Ngày kết thúc (VD: "2024-12-31"). Nếu bỏ trống sẽ lấy đến hiện tại.
• interval (str, tuỳ chọn): Độ phân giải dữ liệu. Các giá trị hợp lệ:
  • Khung ngày/tuần/tháng: '1D', '1W', '1M' (Mặc định thường là '1D').
  • Khung phút (Intraday): '1m', '5m', '15m', '1H' (Chỉ khả dụng với tài khoản Premium/Pro tuỳ nguồn cung cấp).
• length (int | str, tuỳ chọn): Số lượng nến/kỳ cần lấy ngược về quá khứ tính từ end. Có thể dùng thay cho start (VD: 100 nến, hoặc chuỗi thời gian như "30D", "1Y").

2. Dữ liệu Chi tiết Giao dịch (Intraday / Trades)

Các hàm lấy thông tin từng lệnh (Time & Sales) như trades(), block_trades()... hỗ trợ:

• limit (int): Giới hạn số lượng lệnh trả về trên mỗi trang. Mặc định 1000.
• page (int): Số thứ tự trang cần truy xuất. Mặc định 1.
• get_all (bool): Nếu True, thư viện lần lượt lấy từng trang để có đủ lịch sử lệnh. Mỗi trang là một lượt gọi tới nguồn, nên chỉ bật khi thật sự cần, nhất là với mã thanh khoản lớn. Mặc định False.

3. Dữ liệu Tức thời & Thống kê (Snapshot / Stats)

Các hàm truy xuất trạng thái hiện tại như quote(), order_book(), session_stats(), summary(), volume_profile(), odd_lot(): Hầu hết không yêu cầu truyền tham số thời gian. Dữ liệu trả về mặc định là snapshot tại thời điểm truy vấn hoặc thống kê tổng hợp của ngày giao dịch hiện hành.

1. Cổ phiếu (Equity)

Nguồn chính: KBS (kbs), VCI
Nhóm lệnh: market.equity

Phương Thức

📝 Chi Tiết Các Phương Thức

1. Lịch sử Giá (ohlcv)

Lấy dữ liệu giá mở, cao, thấp, đóng và khối lượng theo chuỗi thời gian để vẽ biểu đồ kỹ thuật.

from vnstock_data import Market
mkt = Market()

df_ohlc = mkt.equity("VIC").ohlcv(
    start="2026-02-01", 
    end="2026-03-01",
    interval="1D"
)

2. Thống kê Giao dịch Lịch sử (trade_history)

Trả về dữ liệu thống kê tổng hợp cuối ngày về giá trị, khối lượng khớp lệnh và thỏa thuận.

history_stats = mkt.equity("VIC").trade_history(
    start="2026-02-01", 
    end="2026-03-01"
)

3. Khớp Lệnh Intraday (trades)

Truy xuất danh sách các lệnh khớp chi tiết trong phiên (Time & Sales) để phân tích hành vi dòng tiền.

df_trades = mkt.equity("TCB").trades(limit=100)

4. Sổ Lệnh (order_book)

Xem thông tin các mức giá chờ mua/bán tốt nhất trên sổ lệnh (thường là 3-10 mức).

df_orderbook = mkt.equity("VNM").order_book()

5. Bảng Giá (quote)

Lấy trạng thái giá và các chỉ số giao dịch mới nhất trong phiên (snapshot), cập nhật theo độ trễ của nguồn.

quote = mkt.equity("HPG").quote()

6. Thống kê Phiên (session_stats)

Tổng hợp các chỉ số thanh khoản, trung bình lệnh, tỷ lệ mua/bán chủ động trong ngày.

session = mkt.equity("VIC").session_stats()

7. Tổng Hợp Cổ Phiếu (summary)

Các chỉ số định giá cơ bản (PE, PB), biên độ 52 tuần, số lượng cổ phiếu lưu hành, vốn hoá.

summary_info = mkt.equity("VIC").summary()

8. Dòng Tiền Nước Ngoài (foreign_flow)

Lịch sử thống kê khối lượng và giá trị mua/bán ròng của nhà đầu tư nước ngoài.

foreign = mkt.equity("VIC").foreign_flow()

9. Dòng Tiền Tự Doanh (proprietary_flow)

Lịch sử thống kê giao dịch của khối Tự doanh các Công ty Chứng khoán.

proprietary = mkt.equity("VIC").proprietary_flow()

10. Giao Dịch Thỏa Thuận (block_trades)

Thông tin các lệnh thỏa thuận khối lượng lớn được thực hiện ngoài sàn khớp lệnh liên tục.

blocks = mkt.equity("VIC").block_trades(limit=50)

11. Giao Dịch Lô Lẻ (odd_lot)

Thông tin các lệnh giao dịch có khối lượng dưới tiêu chuẩn lô chẵn (thường < 100 cổ phiếu).

odds = mkt.equity("VIC").odd_lot()

12. Phân Bố Khối Lượng (volume_profile)

Tổng hợp khối lượng giao dịch đã khớp tại từng mức giá cụ thể trong phiên.

vol_profile = mkt.equity("VJC").volume_profile()

2. Chỉ số (Index)

Nguồn: KBS (kbs)
Nhóm lệnh: market.index

Phương Thức

📝 Chi Tiết Các Phương Thức

1. Điểm Chỉ Số Lịch Sử (ohlcv)

Lấy lịch sử biến động điểm số (mở, cao, thấp, đóng) của Index theo thời gian.

from vnstock_data import Market
mkt = Market()

df_vnindex = mkt.index("VNINDEX").ohlcv(
    start="2026-01-01",
    end="2026-03-01"
)

2. Điểm Hiện Tại (quote)

Truy xuất điểm số trong phiên hoặc điểm chốt phiên gần nhất của chỉ số.

quote_index = mkt.index("VNINDEX").quote()

3. Tổng Hợp Chỉ Số (summary)

Thống kê tổng quan trạng thái chỉ số (khối lượng, giá trị giao dịch toàn rổ, số mã tăng/giảm).

summary_index = mkt.index("VNINDEX").summary()

4. Thống kê Giao dịch Lịch sử (trade_history)

Trả về thống kê giao dịch theo thời gian.

hist_trades = mkt.index("VNINDEX").trade_history(start="2026-02-01", end="2026-03-01")

3. Hợp đồng tương lai (Futures)

Nguồn: KBS (kbs)
Nhóm lệnh: market.futures

Phương Thức

📝 Chi Tiết Các Phương Thức

1. Lịch sử Hợp đồng (ohlcv)

Lấy dữ liệu nến lịch sử của hợp đồng phái sinh.

from vnstock_data import Market
mkt = Market()

df_vn30f = mkt.futures("VN30F2503").ohlcv(
    start="2026-02-01",
    end="2026-03-01"
)

2. Giá Hiện Tại (quote)

Lấy giá khớp gần nhất, khối lượng mở (OI) và độ lệch (Basis) của hợp đồng trong phiên.

quote_vn30f = mkt.futures("VN30F2503").quote()

3. Khớp Lệnh Intraday (trades)

Danh sách chi tiết các lệnh khớp phái sinh trong phiên.

trades_vn30f = mkt.futures("VN30F2503").trades(limit=100)

4. Sổ Lệnh (order_book)

Bảng giá các mức chờ mua/bán tốt nhất của hợp đồng.

orderbook_vn30f = mkt.futures("VN30F2503").order_book()

5. Thông tin Hợp đồng (summary)

Trả về thông tin tổng quan, ngày đáo hạn, số lượng hợp đồng mở (OI).

summary_vn30f = mkt.futures("VN30F2503").summary()

4. Chứng quyền (Warrant)

Nguồn: KBS (kbs)
Nhóm lệnh: market.warrant

Phương Thức

📝 Chi Tiết Các Phương Thức

1. Lịch sử Giá Chứng Quyền (ohlcv)

Lấy dữ liệu nến lịch sử của mã chứng quyền.

from vnstock_data import Market
mkt = Market()

df_warrant = mkt.warrant("CACB2511").ohlcv(
    start="2026-02-01",
    end="2026-03-01"
)

2. Giá Hiện Tại (quote)

Lấy thông tin giá khớp lệnh hiện tại và các thông số thanh khoản của chứng quyền.

quote_warrant = mkt.warrant("CACB2511").quote()

3. Khớp Lệnh Intraday (trades)

Truy xuất danh sách các lệnh khớp chi tiết trong phiên của chứng quyền.

trades_warrant = mkt.warrant("CACB2511").trades(limit=100)

4. Sổ Lệnh (order_book)

Xem thông tin các mức giá chờ mua/bán tốt nhất.

orderbook_warrant = mkt.warrant("CACB2511").order_book()

5. Tổng hợp Chứng Quyền (summary)

Các chỉ số cơ bản của chứng quyền (ngày đáo hạn, tỷ lệ chuyển đổi, giá thực hiện, tổ chức phát hành).

summary_warrant = mkt.warrant("CACB2511").summary()

5. Trái phiếu (Bond)

Nguồn: KBS (kbs)
Nhóm lệnh: market.bond

Phương Thức

📝 Chi Tiết Các Phương Thức

1. Lịch sử Giá Trái Phiếu (ohlcv)

Lấy dữ liệu biến động giá trị giao dịch trái phiếu lịch sử.

from vnstock_data import Market
mkt = Market()

df_bond = mkt.bond("TD2444161").ohlcv(
    start="2026-02-01",
    end="2026-03-01"
)

2. Giá Hiện Tại (quote)

Trạng thái giá khớp và thanh khoản trong phiên của trái phiếu.

quote_bond = mkt.bond("TD2444161").quote()

(Các phương thức khác như trades(), order_book(), summary() được sử dụng hoàn toàn tương tự như Equity Market)

6. Chứng chỉ quỹ (ETF)

Nguồn: KBS (kbs), VCI
Nhóm lệnh: market.etf

Phương Thức

Giống Equity Market (đầy đủ): ohlcv(), trades(), order_book(), quote(), session_stats(), foreign_flow(), proprietary_flow(), block_trades(), odd_lot(), volume_profile(), summary().

📝 Chi Tiết Các Phương Thức

1. Lịch sử Giá ETF (ohlcv)

Lấy dữ liệu giá trị của chứng chỉ quỹ ETF trên sàn theo thời gian.

from vnstock_data import Market
mkt = Market()

df_etf = mkt.etf("E1VFVN30").ohlcv(
    start="2026-02-01",
    end="2026-03-01"
)

2. Giá Hiện Tại (quote)

Trạng thái giá khớp và thanh khoản trong phiên của ETF.

quote_etf = mkt.etf("E1VFVN30").quote()

(Các phương thức khác như trades(), order_book(), summary(), session_stats(), v.v. được sử dụng hoàn toàn tương tự như Equity Market)

7. Bảng giá nhiều mã

Nguồn: KBS (kbs)

Phương Thức

Ví Dụ

from vnstock_data import Market

mkt = Market()

df_quotes = mkt.quote(["VIC", "TCB", "HPG", "VNM"])
print(df_quotes)

df_odds = mkt.odd_lot(["VIC", "TCB"])
df_pts = mkt.put_through(["VIC", "TCB"])

8. Thị trường Quốc tế

Crypto Market (Thị Trường Tiền Mã Hóa)

Nguồn chính: Binance (thị trường giao ngay)
Nhóm lệnh: market.crypto

Dữ liệu Crypto Market được truy xuất từ nguồn Binance (thị trường giao ngay). Hỗ trợ truy xuất OHLCV theo khung thời gian (interval) tuỳ chỉnh, sổ lệnh chuẩn hoá đa cấp độ (L1-L10), lịch sử khớp lệnh trong phiên (có phân biệt bên chủ động mua/bán) và báo giá tổng hợp 24h.

Ví dụ Truy xuất Crypto

from vnstock_data import Market

mkt = Market()
crypto = mkt.crypto("BTCUSDT")

df_quote = crypto.quote()

df_ohlcv = crypto.ohlcv(interval="1d", limit=500)

df_orderbook = crypto.order_book(limit=10)

df_trades = crypto.trades()

df_vwap = crypto.vwap()

Forex, Commodity & Global Index (Thị Trường Cầu & Hàng hóa)

Nguồn chính: Dukascopy
Nhóm lệnh: market.forex, market.commodity, market.index

Các domain Forex, Commodity, Index (Chỉ số Quốc Tế) giờ đây được hợp nhất kiến trúc, hỗ trợ dữ liệu theo tick/phút từ nguồn Dukascopy. Thư viện tự tổng hợp lại (resampling) ngay trên máy của bạn cho các khung cao (1h, 4h, 1d...).

Lưu ý: Dữ liệu khớp lệnh chi tiết (trades) không khả dụng trên nguồn FXSB cho Forex, Commodity và Global Index.

🌟 Tính năng Timezone Configuration Parameter:
Lịch sử giá Dukascopy và Quốc tế mặc định được tự động map về quy chuẩn giờ Hệ thống Việt Nam (Asia/Ho_Chi_Minh / GMT+7). Tuy nhiên, có thể tuỳ ý ghi đè múi giờ gốc (UTC) hoặc bất kỳ giờ khu vực nào qua tham số timezone.

Ví Dụ

mkt = Market()

df_eurusd = mkt.forex("EURUSD").ohlcv(interval="1h", length=15)

df_utc_eurusd = mkt.forex("EURUSD", timezone="UTC").ohlcv(interval="1h", length=15)

df_gold = mkt.commodity("XAUUSD").ohlcv(interval="1d", length=5)

df_djia = mkt.index("USA30", scope="global").ohlcv(interval="4h")

Tip: Có thể dùng Reference().search.symbol("tên_tài_sản") để tìm mã Symbol nếu không chắc chắn.

💡 Mẹo Sử Dụng

1. Lấy giá nhiều mã trong một lời gọi

Thay vì lặp gọi quote() cho từng mã, truyền cả danh sách vào mkt.quote() để giảm số lượt gọi tới nguồn.

mkt = Market()
for symbol in symbols:
    quote = mkt.equity(symbol).quote()

all_quotes = mkt.quote(symbols)

2. Xử lý lỗi

mkt = Market()

try:
    df = mkt.equity("INVALID").ohlcv(start="2026-02-01", end="2026-02-28")
except ValueError as e:
    print(f"Symbol không tồn tại: {e}")
except Exception as e:
    print(f"Lỗi: {e}")