Dữ liệu trong phiên (intraday) cổ phiếu Việt Nam

Bốn phương thức cho dữ liệu trong phiên: thanh giá theo bước thời gian, từng lệnh đã khớp, dòng tiền mua/bán chủ động, và chênh lệch giữa hợp đồng tương lai với chỉ số cơ sở — của phiên đang chạy hoặc một phiên đã qua.

Trước khi viết dòng đầu tiên, có hai điểm khác hẳn dữ liệu cuối ngày. Bỏ qua chúng thì code vẫn chạy, không exception nào, chỉ là kết quả sai: cột thời gian ở đây mang múi giờ, và giá ở đây là giá thô.

Bốn phương thức có ở những namespace nào

Ô nào ghi "không có" thì gọi vào ném AttributeError ngay tại chỗ, không phải trả về một bảng rỗng. basis() chỉ có ở phái sinh vì nó cần một chỉ số cơ sở để trừ, và chỉ hợp đồng tương lai mới có thứ đó.

Ba namespace tách nhau vì ba loại tài sản khác đơn vị: cổ phiếu tính giá bằng nghìn VND và khối lượng bằng cổ phiếu, chỉ số tính bằng điểm chỉ số, phái sinh tính giá bằng điểm chỉ số và khối lượng bằng hợp đồng. Một lời gọi vì vậy không bao giờ trả về bảng trộn hai đơn vị.

df = client.intraday.index.ticks("VNINDEX", date="2026-08-03")
df["side"].isna().all()      # True
df["price"].notna().any()    # True

Cột time mang múi giờ, cột date của EOD thì không

Mọi bảng trong phiên đều có cột thời gian tên time, kiểu datetime64[ns, Asia/Ho_Chi_Minh], tức mang sẵn offset +07:00. Dữ liệu cuối ngày thì có cột date naive, không múi giờ.

Bất đối xứng này có chủ đích: một thanh trong phiên là một thời điểm, còn một phiên cuối ngày là một ngày. Một thời điểm mà không mang múi giờ thì pandas đoán là UTC, và 09:15 giờ Việt Nam bị đọc thành 16:15 — ra ngoài cả phiên giao dịch. Một ngày giao dịch thì ngược lại: gắn múi giờ vào nó là bịa ra một độ chính xác không có thật.

import finlens

client = finlens.client()

trong_phien = client.intraday.stock.ohlcv("HPG", start="2026-08-03")
trong_phien["time"].dt.tz            # <DstTzInfo 'Asia/Ho_Chi_Minh' ...>

cuoi_ngay = client.eod.stock.ohlcv("HPG", start="2026-08-03")
cuoi_ngay["date"].dt.tz              # None

Múi giờ của bảng cũng nằm ở df.attrs["finlens"]["tz"]. Nếu bạn cần so với dữ liệu nước ngoài, đổi múi giờ bằng .dt.tz_convert("UTC") — đừng gỡ múi giờ bằng .dt.tz_localize(None), đó là cách âm thầm lệch bảy tiếng.

Mốc thời gian là đầu bước: dòng 09:15 với interval="1min" gói các lệnh khớp từ 09:15:00 đến trước 09:16:00.

Giá trong phiên là giá thô, chưa điều chỉnh quyền

client.eod.stock.ohlcv() mặc định trả giá đã điều chỉnh quyền. client.intraday.*.ohlcv() thì luôn trả giá thô — đúng con số đã khớp trên bảng điện hôm đó, và không có tham số adjusted ở đây.

trong_phien.attrs["finlens"]["price_basis"]   # 'raw'
cuoi_ngay.attrs["finlens"]["price_basis"]     # 'adjusted'

cuoi_ngay_tho = client.eod.stock.ohlcv("HPG", adjusted=False)
cuoi_ngay_tho.attrs["finlens"]["price_basis"]   # 'raw'

ohlcv() — thanh giá theo bước thời gian

client.intraday.stock.ohlcv(
    symbols,
    *,
    start=None,
    end=None,
    interval="1min",
    refresh=False,
    on_error="warn",
) -> DataFrame

Chỉ symbols là tham số vị trí; mọi tham số còn lại là keyword-only.

Việc gộp nhóm chạy ở máy chủ: interval="5min" trả về thanh 5 phút đã gộp sẵn, không phải thanh 1 phút để bạn tự gộp. Nhiều mã cũng đi trong một lời gọi chứ không phải nhiều lời gọi tuần tự.

Độ dài khoảng thời gian được phép lấy một lần do máy chủ quyết định, đọc bằng client.limits()["max_intraday_days"].

Cột trả về

Bảng luôn có đủ bảy cột đúng dtype kể cả khi không có dòng nào, nên bạn không cần bọc if not df.empty quanh mỗi lời gọi. volume là float64 chứ không phải int64 vì cột này nullable: một bước không có lệnh nào phải ra NaN, không phải 0.

import finlens

client = finlens.client()

df = client.intraday.stock.ohlcv("HPG", start="2026-08-03")
df.attrs["finlens"]["units"]["close"]     # 'kVND'

# Thanh 5 phút, gộp ở máy chủ
df = client.intraday.stock.ohlcv(["HPG", "VCB"], interval="5min")

# Chỉ số và phái sinh nằm ở namespace riêng vì chúng khác đơn vị
vni = client.intraday.index.ohlcv("VNINDEX")
f1m = client.intraday.derivative.ohlcv("VN30F1M")

Vũ trụ mã chỉ số: VNINDEX, VN30, VNXALL, HNXINDEX, HNX30, UPINDEX.

ticks() — từng lệnh đã khớp

client.intraday.stock.ticks(
    symbol,
    *,
    date=None,
    refresh=False,
    on_error="warn",
) -> DataFrame

Mỗi dòng là một lệnh đã khớp: không gộp, không resample. Muốn thanh giá theo phút thì gọi ohlcv(); muốn dòng tiền chủ động đã cộng dồn thì gọi net_active_value().

khung = [client.intraday.stock.ticks(ma, date="2026-08-03")
         for ma in ("HPG", "VCB")]

Bỏ trống date thì máy chủ chọn phiên mặc định. Nhận cả chuỗi lẫn datetime.date:

from datetime import date

client.intraday.stock.ticks("HPG", date="2026-08-03")
client.intraday.stock.ticks("HPG", date=date(2026, 8, 3))

Cột trả về

Một frame chỉ chứa một mã. Sáu cột luôn có mặt kể cả khi không có dòng nào.

Cột side có ba giá trị, không phải hai

lien_tuc = df[df["side"] != "auction"]

Với chỉ số, cả side và value đều null: dữ liệu tick chỉ số không ghi chiều lệnh chủ động và cũng không có giá trị tiền. Hai cột vẫn có mặt với toàn null thay vì biến mất, để một frame chỉ số vẫn concat được với một frame cổ phiếu.

Một dòng tick mang hai họ đơn vị

Đây là chỗ dễ sai nhất của cả trang, vì nó nằm ngay trong cùng một dòng:

• price là giá — nghìn VND với cổ phiếu, điểm chỉ số với chỉ số và phái sinh.
• value là tiền — luôn VND thô, không phụ thuộc loại tài sản.

df = client.intraday.stock.ticks("HPG", date="2026-08-03")

df.attrs["finlens"]["units"]["price"]    # 'kVND'
df.attrs["finlens"]["units"]["value"]    # 'VND'

value do máy chủ tính, không phải phép nhân price × volume bạn tự làm được: nó đã nhân sẵn hệ số quy đổi của loại tài sản. Nhân tay rồi so với value mà quên đổi đơn vị sẽ lệch 1.000 lần với cổ phiếu và 100.000 lần với phái sinh — hai con số này không có exception nào chặn được, chỉ có units chặn được.

Với phái sinh, value cũng có thể là null: quy đổi ra VND cần hệ số hợp đồng, và máy chủ chỉ phát số cho mã đã có hệ số xác nhận. null ở đây nghĩa là chưa biết, không phải bằng không — sai một hệ số là sai 100.000 lần, nên null tốt hơn một con số đoán. Cột volume vẫn trả bình thường.

net_active_value() — dòng tiền mua/bán chủ động

client.intraday.stock.net_active_value(
    symbols,
    *,
    start=None,
    end=None,
    interval="1min",
    refresh=False,
    on_error="warn",
) -> DataFrame

Cùng bộ tham số với ohlcv(), và cùng nhận nhiều mã trong một lời gọi. Có ở client.intraday.stock và client.intraday.derivative; không có ở client.intraday.index.

Giá trị và khối lượng khớp lệnh chủ động theo từng bước thời gian, tách làm ba nhóm: mua chủ động, bán chủ động, và khớp lệnh định kỳ.

Cột trả về

Mười cột luôn có mặt kể cả khi không có dòng nào. Khối lượng tính bằng cổ phiếu với cổ phiếu, bằng hợp đồng với phái sinh — đọc df.attrs["finlens"]["units"]["buy_volume"].

Ba nhóm, hai công thức, một chỗ rất dễ hiểu nhầm

• net_value = buy_value - sell_value — một hiệu.
• buy_value + sell_value + auction_value — một tổng, chính là toàn bộ giá trị khớp của bước đó.

Đừng cộng auction_value vào net_value. Một bên là hiệu, một bên là tổng, và ATO/ATC không có chiều để mà cộng vào.

Ba nhóm khối lượng cộng lại đúng bằng khối lượng phiên của dữ liệu cuối ngày, nên đây là phép đối chiếu bạn tự chạy được:

trong_phien = client.intraday.stock.net_active_value("HPG", start="2026-08-03")
tong_kl = trong_phien[["buy_volume", "sell_volume", "auction_volume"]].sum().sum()

cuoi_ngay = client.eod.stock.ohlcv("HPG", start="2026-08-03", end="2026-08-03")
tong_kl == cuoi_ngay["volume"].iloc[0]

df.attrs["finlens"]["units"]["net_value"]    # 'VND'

Với phái sinh, các cột *_value có thể trả null khi mã chưa có hệ số hợp đồng xác nhận; các cột *_volume vẫn trả bình thường. Kiểm bằng .isna(), đừng đọc null thành 0.

# Gộp về thanh 15 phút — giá trị được CỘNG trong bước
df = client.intraday.stock.net_active_value("HPG", interval="15min")

# Nhiều mã trong một lời gọi
df = client.intraday.stock.net_active_value(["HPG", "VCB"], interval="1h")

# Phái sinh: cùng chữ ký, khác đơn vị khối lượng
df = client.intraday.derivative.net_active_value("VN30F1M")
df.attrs["finlens"]["units"]["buy_volume"]   # hợp đồng, không phải cổ phiếu

basis() — chênh lệch phái sinh và chỉ số cơ sở, bước 1 phút

client.intraday.derivative.basis(
    symbols,
    *,
    start=None,
    end=None,
    refresh=False,
    on_error="warn",
) -> DataFrame

Chỉ có ở client.intraday.derivative, và chỉ phục vụ các mã VN30F*.

Cùng đại lượng và cùng công thức với client.eod.derivative.basis(); chỉ cột thời gian khác — ở đây là time mang múi giờ, ở kia là date naive.

Cột trả về

Bảy cột luôn có mặt kể cả khi không có dòng nào.

basis     = future_close - spot_close     # điểm chỉ số
basis_pct = basis / spot_close * 100      # phần trăm, thang 0–100

⚠️ Mẫu số của basis_pct là spot_close, không phải future_close, và kết quả đã nhân 100. Hai mẫu số chỉ lệch nhau khoảng 0,3% nên chọn nhầm gần như không nhìn ra được trên một biểu đồ — đó chính là lý do công thức được viết thẳng ra đây. Giải thích đầy đủ, kể cả vì sao index_symbol là một cột thật chứ không phải một chi tiết trong df.attrs, nằm ở trang cuối ngày.

df = client.intraday.derivative.basis("VN30F1M", start="2026-08-05")

df.attrs["finlens"]["units"]["basis"]       # 'index_point'
df.attrs["finlens"]["units"]["basis_pct"]   # 'pct'

Chuỗi bắt đầu từ 09:15, và khoảng trước đó vắng mặt có chủ đích

Bar đầu tiên của một phiên là 09:15, không phải 09:00 và cũng không phải 09:01. Hai lý do rời nhau, cùng dẫn tới một mốc:

1. Trước 09:15, chỉ số chưa được tính theo từng phút. Hợp đồng phái sinh mở cửa sớm hơn cổ phiếu nên nó có bar liên tục suốt khoảng 09:01–09:14, nhưng vế spot_close thì không tồn tại ở đó. Đo trên 3/3 phiên kiểm: chỉ số có đúng một bar lúc 09:00 rồi không có bar nào cho tới 09:15. Ghép hai vế ở khoảng đó sẽ cho ra spot_close là null, tức basis cũng null — một cột toàn ô trống suốt mười bốn phút đầu phiên.

2. Bar 09:00 có đủ hai vế, nhưng nó là một cơ chế hình thành giá khác hẳn. 09:00 là kết quả khớp lệnh định kỳ ATO: toàn bộ lệnh khớp tại một mức giá duy nhất, không có bên chủ động nào, không có chuỗi giá liên tục dẫn tới nó. Một chênh lệch tính trên hai giá đấu giá định kỳ không so sánh được với chênh lệch tính trên các bar khớp lệnh liên tục phía sau — đặt chung một chuỗi là trộn hai đại lượng.

Mốc 09:15 vì vậy loại cả hai: khoảng không có vế spot lẫn bar đấu giá định kỳ. Kết quả là một chuỗi không có ô trống nào ngay từ bar đầu.

df = client.intraday.derivative.basis("VN30F1M", start="2026-08-05")

df["time"].min().strftime("%H:%M")   # '09:15'
df["basis"].isna().sum()             # 0

Mã phái sinh không có chuỗi chỉ số cơ sở trong dữ liệu đi vào phần lỗi theo từng mã với mã FL_DATA_NO_UNDERLYING (finlens.NoDataError), chứ không làm hỏng cả lời gọi — hành vi và ví dụ giống hệt bản cuối ngày.

Đơn vị trong phiên, tra nhanh

Riêng basis() nằm ngoài bảng này vì cả hai vế của nó đều là điểm chỉ số theo định nghĩa: future_close, spot_close và basis là 'index_point', còn basis_pct là 'pct' trên thang 0–100.

Bảng trên để bạn ước lượng nhanh. Câu trả lời đáng tin duy nhất là units của chính bảng bạn vừa nhận, tra theo tên cột:

df.attrs["finlens"]["units"]
# {'symbol': None, 'time': None, 'price': 'kVND', 'volume': 'share',
#  'side': None, 'value': 'VND'}

⚠️ DataFrame.attrs không sống sót qua pd.concat hay merge của pandas. Đọc đơn vị ra biến trước khi ghép bảng. Chi tiết ở Kiểu dữ liệu.

Bản async

Mọi phương thức trên đều có bản bất đồng bộ với cùng chữ ký:

import asyncio
import finlens

async def main():
    async with finlens.AsyncClient() as client:
        df = await client.intraday.stock.ticks("HPG", date="2026-08-03")

asyncio.run(main())

Xem thêm