Tiền mã hoá, ngoại hối, hàng hoá và chỉ số thế giới
Mục lục
Giá lịch sử (ohlcv) của cả bốn nhóm tài sản và tra cứu mã quốc tế mở cho mọi cấp: Khách, Cộng đồng và Tài trợ. Các hàm khác của tiền mã hoá (khớp lệnh, sổ lệnh, thống kê 24 giờ…) và khớp lệnh của ngoại hối, hàng hoá, chỉ số thế giới chỉ dành cho cấp Tài trợ. Khách và Cộng đồng gọi các hàm này thì nhận EntitlementError mã VNSTOCK_TIER_ROUTE, và thư viện không gửi truy vấn nào đi.
Trang này hướng dẫn bạn truy xuất giá của tài sản ngoài thị trường Việt Nam: cặp tiền mã hoá,
cặp ngoại tệ, hàng hoá thế giới (vàng, dầu…) và chỉ số chứng khoán thế giới. Mọi hàm nằm trong
Market(), trừ tra cứu mã nằm trong Reference().search.
| Hàm | Làm gì | Cấp |
|---|---|---|
Market().crypto(s).ohlcv() | Nến giá lịch sử của cặp tiền mã hoá | Mọi cấp |
Market().crypto(s).trades() | Các lệnh khớp gần nhất | Tài trợ |
Market().crypto(s).order_book() | Sổ lệnh, 10 bước giá mỗi bên | Tài trợ |
Market().crypto(s).quote() | Giá mở cửa, cao, thấp trong 24 giờ | Tài trợ |
Market().crypto(s).daily_stats() | Thống kê trong ngày (theo giờ UTC) | Tài trợ |
Market().crypto(s).rolling_stats() | Thống kê theo cửa sổ trượt | Tài trợ |
Market().crypto(s).last_price() | Giá khớp gần nhất | Tài trợ |
Market().crypto(s).reference_price() | Giá tham chiếu của sàn | Tài trợ |
Market().crypto(s).vwap() | Giá bình quân theo khối lượng | Tài trợ |
Market().forex(s).ohlcv() | Nến giá lịch sử của cặp ngoại tệ | Mọi cấp |
Market().commodity(s).ohlcv() | Nến giá lịch sử của hàng hoá | Mọi cấp |
Market().index(s, scope="global").ohlcv() | Nến giá lịch sử của chỉ số thế giới | Mọi cấp |
Reference().search.symbol(), .info() | Tìm mã quốc tế theo tên hoặc ký hiệu | Mọi cấp |
1. Thời gian theo UTC
Mọi cột thời gian trên trang này trả theo giờ UTC, kiểu datetime64[ns, UTC], có ghi múi giờ
trong cột. Nến ngày 2026-10-09 00:00:00+00:00 là phiên tính từ 0 giờ UTC, tức 7 giờ sáng giờ Việt
Nam. Muốn xem theo giờ Việt Nam, bạn tự đổi:
df["time"] = df["time"].dt.tz_convert("Asia/Ho_Chi_Minh")Bản cũ có tham số timezone= để chọn múi giờ. Thế hệ 5 không đổi múi giờ hộ bạn. Với ngoại hối,
hàng hoá và chỉ số thế giới, truyền timezone= khác "UTC" thì nhận UnsupportedError mã
VNSTOCK_FEATURE_REMOVED, kèm đúng câu lệnh đổi giờ ở trên:
Market().forex("EURUSD", timezone="Asia/Ho_Chi_Minh")
# UnsupportedError: `Market().forex(...).ohlcv(timezone=...)` đã ngừng hỗ trợ từ vnstock 5
# và không còn trả dữ liệu. Thời gian luôn trả theo UTC, có ghi múi giờ trong cột.
# Đổi sang giờ Việt Nam: df['time'].dt.tz_convert('Asia/Ho_Chi_Minh').timezone="UTC" vẫn được nhận và không làm gì.
2. Tìm mã — Reference().search
Mã của ngoại hối, hàng hoá và chỉ số thế giới theo cách đặt tên của nguồn, không theo bản 4.x.
Ví dụ USDVND, GOLD của bản 4.x không còn dùng được: nguồn trả HTTP 400 và bạn nhận
ProviderError mã VNSTOCK_SOURCE_REJECTED. Khi không chắc mã, tra trước bằng search.
Reference().search.symbol(query, locale=None, limit=10)
Reference().search.info(query, locale=None, limit=10)| Tham số | Kiểu | Mặc định | Ý nghĩa |
|---|---|---|---|
query | str | bắt buộc | Chuỗi cần tìm, ví dụ "gold", "brent", "XAUUSD" |
locale | str | None | Giữ cho tương thích, nguồn hiện tại không dùng |
limit | int | 10 | Số kết quả tối đa |
Cấp: mọi cấp. Nguồn: dukascopy, không có tham số source. Hai hàm trả cùng bộ cột; symbol
tìm theo ký hiệu và tên, info khớp chặt hơn (tìm "EUR" bằng info trả bảng rỗng, tìm
"XAUUSD" trả đúng một dòng).
from vnstock import Reference
Reference().search.symbol("brent", limit=3)
Reference().search.info("XAUUSD")| Cột | Kiểu | Ý nghĩa |
|---|---|---|
symbol | string | Mã để truyền vào Market().forex(), .commodity(), .index(..., scope="global") |
name | string | Tên đầy đủ theo nguồn, ví dụ XAU/USD, BRENT.CMD/USD |
exchange | string | Nhóm tài sản theo nguồn, ví dụ FX_METAL, COM_SPOT, ETF, STK_CASH |
short_name | string | Tên ngắn, thường để trống |
description | string | Mô tả, ví dụ Gold vs US Dollar |
name_en | string | Tên tiếng Anh, thường để trống |
name_local | string | Mã quốc gia, ví dụ US |
symbol_id | string | Mã định danh đầy đủ của nguồn |
Dữ liệu mẫu (chạy ngày 10/10/2026):
| symbol | name | exchange | description | name_local |
|---|---|---|---|---|
XAUUSD | XAU/USD | FX_METAL | Gold vs US Dollar | US |
BRENT | BRENT.CMD/USD | COM_SPOT | Brent Crude Oil | |
GLD | GLD.US/USD | ETF | SPDR Gold Shares ETF | US |
Truyền cột symbol (ví dụ BRENT), không truyền cột name (BRENT.CMD/USD sẽ bị nguồn từ chối).
3. Tham số chung của ohlcv
Cả bốn nhóm tài sản dùng cùng chữ ký:
ohlcv(start=None, end=None, interval="1D", *, limit=None, source=None,
count_back=None, length=None, floating=2)| Tham số | Kiểu | Mặc định | Ý nghĩa |
|---|---|---|---|
start | str | None | Ngày bắt đầu, YYYY-MM-DD |
end | str | None | Ngày kết thúc, YYYY-MM-DD; để trống là hôm nay |
interval | str | "1D" | Khung nến: 1m, 1H, 1D, 1W, 1M |
limit | int | None | Số nến tối đa; dùng một mình (không start) thì lấy N nến mới nhất |
source | str | None | Nguồn; mỗi nhóm chỉ có một nguồn, xem từng mục |
count_back | int | None | Số nến mới nhất cần lấy |
length | int, str | None | Số nến (100) hoặc khoảng thời gian ("3M", "1Y") |
floating | int | 2 | Số chữ số thập phân của cột giá; None giữ nguyên số nguồn gửi |
Không truyền gì thì lấy 100 nến ngày mới nhất (riêng tiền mã hoá, xem lưu ý ở mục 4.1). Bảng trả về có cột time (UTC), open, high,
low, close, volume. Tên cũ history() vẫn dùng được, nhận cùng tham số. Tên tham số cũ của
bản 4.x resolution= (thay interval) và count= (thay count_back) vẫn được hiểu.
Mặc định floating=2 làm tròn giá về hai chữ số, như bản Mở rộng. Với cặp ngoại tệ, hai chữ số làm mất gần hết thông tin: EURUSD chỉ còn 1.13, 1.12. Khi lấy ngoại hối, truyền floating=None (giữ nguyên số của nguồn) hoặc floating=5.
Mỗi lần 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ữ phần mới nhất,
ghi df.attrs["request_cap_rows"] và cảnh báo. Cấp Khách và Cộng đồng còn bị giới hạn độ dài lịch
sử và số dòng, xem Cấp quyền và giới hạn.
4. Tiền mã hoá — Market().crypto(symbol)
Market().crypto(symbol, source=None)symbol là mã cặp trên sàn, ví dụ "BTCUSDT", "ETHUSDT". Giá tính theo đồng định giá của cặp
(USDT với BTCUSDT), không phải VND. Mã một đồng như "BTC" của bản 4.x không dùng được: nguồn
trả HTTP 400, bạn nhận ProviderError mã VNSTOCK_SOURCE_REJECTED.
Nguồn: chỉ binance, cũng là mặc định. Truyền nguồn khác, ví dụ source="msn" của bản 4.x, thì
nhận UnsupportedError:
Nguồn 'msn' không phục vụ tiền mã hoá ở vnstock 5. Dùng source='binance', hoặc bỏ source để dùng mặc định.4.1. Nến giá — ohlcv()
Cấp: mọi cấp. Tham số như mục 3. Với tiền mã hoá, start và end được tính theo ngày UTC.
from vnstock import Market
btc = Market().crypto("BTCUSDT")
btc.ohlcv(limit=3) # 3 nến ngày mới nhất
btc.ohlcv(start="2026-10-06", end="2026-10-08", interval="1H")| Cột | Kiểu | Ý nghĩa |
|---|---|---|
time | datetime64[ns, UTC] | Thời điểm mở nến |
open, high, low, close | float64 | Giá, theo đồng định giá của cặp |
volume | float64 | Khối lượng, tính bằng đồng cơ sở (BTC với BTCUSDT) |
Dữ liệu mẫu, ohlcv(limit=3) chạy ngày 10/10/2026 (nến cuối là phiên đang chạy):
| time | open | high | low | close | volume |
|---|---|---|---|---|---|
| 2026-10-08 00:00:00+00:00 | 83321.81 | 83521.15 | 80393.56 | 81754.45 | 21676.96164 |
| 2026-10-09 00:00:00+00:00 | 81754.46 | 83528.98 | 81603.52 | 82635.55 | 12301.61263 |
| 2026-10-10 00:00:00+00:00 | 82635.56 | 82937.49 | 82545.82 | 82870.01 | 3153.73559 |
4.2. Khớp lệnh — trades()
trades(limit=500, mode="raw")Cấp: Tài trợ. limit là số lệnh khớp tối đa, mặc định 500. mode giữ cho tương thích, không
có tác dụng. Tên cũ: trade_history(limit=None) (để trống là 500), intraday(page_size=100).
| Cột | Kiểu | Ý nghĩa |
|---|---|---|
time | datetime64[ns, UTC] | Thời điểm khớp, đến mili giây |
price | float64 | Giá khớp |
volume | float64 | Khối lượng khớp, theo đồng cơ sở |
side | string | Chiều bên chủ động: buy, sell |
match_type | string | Loại lệnh khớp, ví dụ Normal |
id | string | Mã lệnh khớp của sàn |
Dữ liệu mẫu, trades(limit=5) chạy ngày 10/10/2026:
| time | price | volume | side | match_type | id |
|---|---|---|---|---|---|
| 2026-10-10 09:07:42.237+00:00 | 82861.26 | 0.00049 | sell | Normal | 6752102878 |
| 2026-10-10 09:07:42.840+00:00 | 82861.26 | 0.00235 | sell | Normal | 6752102879 |
| 2026-10-10 09:07:42.994+00:00 | 82861.27 | 0.00018 | buy | Normal | 6752102880 |
4.3. Sổ lệnh — order_book()
order_book(limit=None, *, source=None)Cấp: Tài trợ. Trả một dòng, 40 cột: bid_price_1 … bid_price_10, bid_vol_1 … bid_vol_10
(bên mua) và ask_price_1 … ask_vol_10 (bên bán). limit là số bước giá mỗi bên; bước không có
thì để NaN. Tên cũ: price_depth().
btc.order_book(limit=5)Dữ liệu mẫu, order_book(limit=5) chạy ngày 10/10/2026 (trích bốn cột):
| bid_price_1 | bid_vol_1 | ask_price_1 | ask_vol_1 |
|---|---|---|---|
| 82861.26 | 8.52604 | 82861.27 | 0.87512 |
4.4. Giá tóm tắt — quote()
Cấp: Tài trợ. Với tiền mã hoá, quote() chỉ có bốn cột: symbol, open_price, high_price,
low_price (giá mở, cao, thấp trong 24 giờ trượt). Cần đủ số liệu thì dùng rolling_stats().
Tên cũ: price_board().
4.5. Thống kê — daily_stats() và rolling_stats()
daily_stats()
rolling_stats(window_size=None)Cấp: Tài trợ. Hai hàm trả cùng bộ 15 cột, một dòng:
daily_stats()tính từ 0 giờ UTC của ngày hiện tại. Tên cũ:summary().rolling_stats()tính trên cửa sổ trượt kết thúc lúc gọi. Để trốngwindow_sizethì cửa sổ là 24 giờ; truyền theo cách viết của sàn, ví dụ"4h".
| Cột | Kiểu | Ý nghĩa |
|---|---|---|
symbol | string | Mã cặp |
price_change, price_change_percent | float64 | Thay đổi giá và phần trăm (0.273 là 0,273%) |
weighted_avg_price | float64 | Giá bình quân gia quyền |
open_price, high_price, low_price, last_price | float64 | Giá mở, cao, thấp, gần nhất |
volume | float64 | Khối lượng theo đồng cơ sở |
quote_volume | float64 | Giá trị theo đồng định giá |
open_time, close_time | datetime64[ns, UTC] | Đầu và cuối cửa sổ |
first_id, last_id | int64 | Mã lệnh khớp đầu và cuối trong cửa sổ |
count | float64 | Số lệnh khớp |
Dữ liệu mẫu, daily_stats() chạy ngày 10/10/2026 (trích):
| symbol | price_change_percent | open_price | high_price | low_price | last_price | volume | open_time |
|---|---|---|---|---|---|---|---|
| BTCUSDT | 0.273 | 82635.56 | 82937.49 | 82545.82 | 82861.27 | 3152.28623 | 2026-10-10 00:00:00+00:00 |
4.6. Giá đơn lẻ — last_price(), reference_price(), vwap()
Cấp: Tài trợ. Mỗi hàm trả một dòng.
| Hàm | Cột | Ý nghĩa |
|---|---|---|
last_price() | symbol, price | Giá khớp gần nhất |
reference_price(mode="price") | symbol, reference_price, timestamp (UTC) | Giá tham chiếu sàn công bố; mode giữ cho tương thích, không có tác dụng |
vwap() | mins, price, close_time (UTC) | Giá bình quân theo khối lượng; mins là độ dài cửa sổ tính bằng phút |
Dữ liệu mẫu chạy ngày 10/10/2026: last_price() trả BTCUSDT 82861.27; vwap() trả
mins=5.0, price=82859.21139.
session_stats() (tên cũ trading_stats()) không có cho tiền mã hoá: gọi thì nhận InputError
mã VNSTOCK_INPUT_OPERATION. Dùng daily_stats() thay.
5. Ngoại hối — Market().forex(symbol)
Market().forex(symbol)symbol là mã cặp theo nguồn, ví dụ "EURUSD", "USDJPY". Cặp với VND như "USDVND" không có;
tỷ giá VND niêm yết tại ngân hàng xem ở Tỷ giá ngân hàng.
Cấp của ohlcv(): mọi cấp. Nguồn: dukascopy, cũng là mặc định. Tham số như mục 3; nhớ truyền
floating=None hoặc floating=5.
from vnstock import Market
eur = Market().forex("EURUSD")
eur.ohlcv(limit=3, floating=None)
Market().forex("USDJPY").ohlcv(start="2026-10-01", end="2026-10-09", floating=3)Cột: time (UTC), open, high, low, close, volume, đều float64 trừ time.
Dữ liệu mẫu, forex("EURUSD").ohlcv(length=3, floating=None) chạy ngày 10/10/2026 (thứ Bảy,
nên nến cuối là thứ Sáu 09/10):
| time | open | high | low | close | volume |
|---|---|---|---|---|---|
| 2026-10-07 00:00:00+00:00 | 1.12526 | 1.12547 | 1.11647 | 1.12000 | 147735.36 |
| 2026-10-08 00:00:00+00:00 | 1.11999 | 1.12268 | 1.11718 | 1.12126 | 167403.84 |
| 2026-10-09 00:00:00+00:00 | 1.12127 | 1.12427 | 1.11874 | 1.11998 | 127815.68 |
6. Hàng hoá — Market().commodity(symbol)
Market().commodity(symbol)symbol là mã theo nguồn, ví dụ "XAUUSD" (vàng theo USD), "BRENT" (dầu Brent). Tên chung như
"GOLD" của bản 4.x không dùng được. Tra mã bằng Reference().search.symbol("oil").
Cấp của ohlcv(): mọi cấp. Nguồn: dukascopy, cũng là mặc định. Tham số và cột như mục 3.
gold = Market().commodity("XAUUSD")
gold.ohlcv(start="2026-10-05", end="2026-10-09")
Market().commodity("BRENT").ohlcv(limit=2)Dữ liệu mẫu, commodity("XAUUSD").ohlcv(length=5) chạy ngày 10/10/2026 (trích 3 dòng đầu):
| time | open | high | low | close | volume |
|---|---|---|---|---|---|
| 2026-10-05 00:00:00+00:00 | 4142.06 | 4170.14 | 4122.96 | 4134.02 | 28.83541 |
| 2026-10-06 00:00:00+00:00 | 4134.27 | 4184.14 | 4103.80 | 4165.70 | 25.05434 |
| 2026-10-07 00:00:00+00:00 | 4165.70 | 4169.42 | 4065.54 | 4108.00 | 29.55513 |
7. Chỉ số thế giới — Market().index(symbol, scope="global")
Market().index(symbol, scope="global")symbol là mã theo nguồn, ví dụ "USA30" (Dow Jones), "JPN225" (Nikkei 225). Bỏ
scope="global" thì Market().index() hiểu là chỉ số Việt Nam (VNINDEX, VN30…), xem
Dữ liệu thị trường.
Cấp của ohlcv(): mọi cấp. Nguồn: dukascopy, cũng là mặc định. Tham số và cột như mục 3.
Market().index("USA30", scope="global").ohlcv(limit=5)
Market().index("JPN225", scope="global").ohlcv(start="2026-10-06", end="2026-10-09")Dữ liệu mẫu, index("JPN225", scope="global").ohlcv(start="2026-10-06", end="2026-10-09") chạy
ngày 10/10/2026 (trích 3 dòng):
| time | open | high | low | close | volume |
|---|---|---|---|---|---|
| 2026-10-06 00:00:00+00:00 | 70008.37 | 71333.42 | 69793.32 | 70698.52 | 715.554 |
| 2026-10-07 00:00:00+00:00 | 70626.52 | 70798.52 | 69020.37 | 69840.37 | 812.304 |
| 2026-10-08 00:00:00+00:00 | 69838.37 | 69953.52 | 67827.37 | 68469.32 | 1165.149 |
Các báo cáo chỉ có ở chỉ số Việt Nam, trade_history() và stock_influence(), gọi trên chỉ số thế
giới thì nhận UnsupportedError nói rõ chỉ số thế giới chỉ có ohlcv() và trades().
8. Khớp lệnh ngoại hối, hàng hoá, chỉ số thế giới — trades()
Market().forex(s).trades(), Market().commodity(s).trades() và
Market().index(s, scope="global").trades() dành cho cấp Tài trợ, nguồn dukascopy, thời gian
UTC.
9. Khác bản 4.x
| Điểm | Bản 4.x | Thế hệ 5 |
|---|---|---|
| Nguồn tiền mã hoá | MSN | binance, nguồn duy nhất |
| Nguồn ngoại hối, hàng hoá, chỉ số thế giới, tra cứu mã | MSN | dukascopy |
| Mã | BTC, USDVND, GOLD | BTCUSDT, EURUSD, XAUUSD; tra bằng Reference().search |
| Giá tiền mã hoá | Theo VND | Theo đồng định giá của cặp, ví dụ USDT |
| Múi giờ | Đổi được bằng timezone= | Luôn UTC; timezone= khác UTC báo lỗi kèm cách đổi |
| Hàm của tiền mã hoá | Chỉ ohlcv() | Thêm khớp lệnh, sổ lệnh, thống kê, giá tham chiếu, VWAP (cấp Tài trợ) |
Chi tiết chuyển mã từ bản 4.x ở Chuyển đổi từ vnstock 4.x. Nguồn mặc định của mọi hàm ở Nguồn dữ liệu.