quant-agent: Thư viện Phân tích Dữ liệu Chứng khoán & Giao dịch Việt Nam

quant-agent (Python package: quant_agent) là thư viện Python mã nguồn mở cung cấp dữ liệu thị trường tài chính Việt Nam (cổ phiếu, chỉ số thị trường, phái sinh, quỹ mở) dưới dạng pandas.DataFrame đã được chuẩn hóa.

Thư viện được thiết kế theo triết lý Zero-Friction Market Data: toàn bộ các hàm đọc dữ liệu thị trường đều hoạt động ngay lập tức mà không cần đăng ký tài khoản hay API key trả phí. Ngoài ra, thư viện cung cấp phân hệ kết nối giao dịch tự động qua tài khoản chứng khoán DNSE.

---

📑 Mục lục

1. Tính năng nổi bật
2. Hiện trạng nguồn dữ liệu (Cập nhật 2026)
3. Cài đặt
4. Kiến trúc & Code Flow
5. Hướng dẫn sử dụng nhanh
   • 1. Danh sách mã niêm yết
   • 2. Dữ liệu giá lịch sử & Kỹ thuật (OHLC)
   • 3. Dữ liệu cơ bản doanh nghiệp
   • 4. Báo cáo tài chính & Chỉ số định giá
   • 5. Bảng giá, Sổ lệnh & Dữ liệu Intraday
   • 6. Dữ liệu Quỹ mở (Fmarket)
   • 7. Trực quan hóa dữ liệu (Plotly Charts)
   • 8. Xuất dữ liệu sang AmiBroker
   • 9. Giao dịch tự động qua Broker (DNSE)
6. Kiểm thử sức khỏe hệ thống (Smoke Test)
7. Tuyên bố miễn trừ trách nhiệm

---

🚀 Tính năng nổi bật

• Dữ liệu giá OHLC toàn diện: Hỗ trợ cổ phiếu, chứng quyền, chỉ số (VNINDEX, VN30, HNX, UPCOM) và phái sinh (VN30F1M, VN30F2M...) với các khung thời gian 1 ngày, 1 giờ, 30 phút, 15 phút, 1 phút.
• Dữ liệu tài chính doanh nghiệp chuyên sâu: Báo cáo tài chính (CĐKT, KQKD, LCTT) chuẩn hóa theo quý/năm; chỉ số P/E, P/B, ROE, ROA, EPS; hồ sơ doanh nghiệp, cơ cấu cổ đông, ban lãnh đạo, giao dịch nội bộ, sự kiện và tin tức.
• Sổ lệnh & Intraday thời gian thực: Xem bảng giá trực tiếp, độ sâu sổ lệnh (Top 3 mức giá Mua/Bán tốt nhất) và chi tiết từng lệnh khớp trong phiên.
• Quỹ mở Việt Nam: Danh mục tài sản, ngành nắm giữ, hiệu suất sinh lời và lịch sử biến động NAV của hơn 60 quỹ mở trên Fmarket.
• Biểu đồ trực quan chuẩn Quant: Tích hợp vẽ biểu đồ nến Candlestick kèm Volume, đường MA và Bollinger Bands tương tác qua Plotly.
• Xuất dữ liệu AmiBroker: Định dạng CSV tương thích ngay lập tức với phần mềm phân tích kỹ thuật AmiBroker.
• Đặt lệnh giao dịch thật qua Broker: Module broker.dnse hỗ trợ đăng nhập JWT, xác thực 2 lớp OTP/Smart OTP, kiểm tra sức mua (PPSE), đặt lệnh, tra cứu và hủy lệnh.

---

📡 Hiện trạng nguồn dữ liệu (Cập nhật 2026)

Hệ thống đã được tái cấu trúc và phân lập tầng nguồn dữ liệu (quant_agent/sources/):

Phân hệ / Dữ liệu	Nguồn upstream	Trạng thái	Ghi chú kỹ thuật
Dữ liệu OHLC ngắn hạn / Intraday	DNSE (Entrade Gateway)	🟢 Hoạt động tốt	Hỗ trợ nến 1D, 1h, 30m, 15m, 1m (khung < 1D giới hạn 90 ngày gần nhất)
Dữ liệu OHLC dài hạn	VCI (VietCap Securities)	🟢 Hoạt động tốt	Tự động phân trang, trả tối đa 1000 nến/request
Danh sách mã chứng khoán	Wifeed API / Local CSV	🟢 Hoạt động tốt	SSI API thường bị chặn bởi Cloudflare bot-detection
Hồ sơ & Quản trị doanh nghiệp	VCI (VietCap Securities)	🟢 Hoạt động tốt	Tổng quan, mô tả KD, cổ đông lớn, ban lãnh đạo, công ty con, tin tức, sự kiện
Báo cáo & Chỉ số tài chính	VCI (VietCap Securities)	🟢 Hoạt động tốt	BCTC, chuỗi tài chính, P/E, P/B, ROE, ROA (tự động handshake session cookie)
Sổ lệnh độ sâu (Order Book)	VPS (banggia.vps.com.vn)	🟢 Hoạt động tốt	Top 3 bước giá Mua / Bán, bước khối lượng, room nước ngoài
Bảng giá & Khớp lệnh Intraday	VCI (trading.vietcap.com.vn)	🟢 Hoạt động tốt	Bảng giá trực tiếp, từng lệnh khớp lệnh mua/bán chủ động
Dữ liệu Quỹ mở	Fmarket (api.fmarket.vn)	🟢 Hoạt động tốt	Toàn bộ danh sách quỹ, NAV history, top holding cổ phiếu/trái phiếu
Giao dịch Broker DNSE	Entrade Order Service	🟢 Hoạt động tốt	Yêu cầu tài khoản giao dịch thực tế

---

📦 Cài đặt

Yêu cầu môi trường

• Python >= 3.10
• Kết nối Internet ổn định

1. Cài đặt trực tiếp từ PyPI (Khuyến nghị)

Bạn có thể cài đặt trực tiếp bản phát hành chính thức thông qua pip:

pip install quant-agent

Để nâng cấp lên phiên bản mới nhất bất kỳ lúc nào:

pip install -U quant-agent

2. Cài đặt từ mã nguồn (Dành cho nhà phát triển / Đóng góp mã nguồn)

Clone repository và cài đặt ở chế độ editable:

# Clone repository
git clone https://github.com/tomtranai/quant-agent.git
cd quant-agent

# Cài đặt các gói phụ thuộc & editable mode
pip install -e .

---

🏗 Kiến trúc & Code Flow

1. Sơ đồ kiến trúc phân tầng (Layered Architecture)

graph TD
    User["Lập trình viên / Quant Trader / Jupyter Notebook"]
    
    subgraph "Tầng Public API (quant_agent/__init__.py)"
        API["Public Functions (stock_historical_data, company_overview, price_board, ...)"]
    end
    
    subgraph "Tầng Domain Logic (Core Modules)"
        TECH["technical.py<br>(OHLC, Intraday)"]
        FUND["fundamental.py<br>(Profiles, Financials)"]
        TRADE["trading.py<br>(Orderbook, Price Board)"]
        FUNDS["funds.py<br>(Mutual Funds)"]
        CHART["chart.py<br>(Plotly Visuals)"]
        INTEG["integration.py<br>(AmiBroker Export)"]
        BROKER["broker/dnse.py<br>(Authenticated Trading)"]
    end
    
    subgraph "Tầng HTTP Plumbing & Fail-Safe"
        CLIENT["sources/http_client.py<br>(fetch, fetch_json)"]
        COOKIE["sources/vci.py<br>(vci_session_cookies Handshake)"]
    end
    
    subgraph "Tầng Nguồn dữ liệu ngoài (Upstream Data Providers)"
        VCI_API["VCI VietCap API<br>(Trading / IQ Service)"]
        DNSE_API["DNSE / Entrade API<br>(Chart / User / Order)"]
        VPS_API["VPS Banggia API<br>(Order Book)"]
        FM_API["Fmarket API<br>(Mutual Funds)"]
        WF_API["Wifeed API<br>(Stock List)"]
    end

    User --> API
    API --> TECH
    API --> FUND
    API --> TRADE
    API --> FUNDS
    API --> CHART
    API --> INTEG
    API --> BROKER
    
    TECH --> CLIENT
    FUND --> CLIENT
    FUND --> COOKIE
    TRADE --> CLIENT
    FUNDS --> CLIENT
    BROKER --> CLIENT
    
    CLIENT --> VCI_API
    CLIENT --> DNSE_API
    CLIENT --> VPS_API
    CLIENT --> FM_API
    CLIENT --> WF_API

2. Nguyên lý Code Flow

1. Top-Level Re-export Hub (quant_agent/__init__.py):

   • Tất cả các hàm nghiệp vụ được re-export ra root namespace. Người dùng chỉ cần import quant_agent as qa và gọi qa.stock_historical_data(), qa.company_overview(), v.v. mà không cần quan tâm cấu trúc file bên dưới.

2. Cơ chế Fail-Safe & Fallback (sources/http_client.py):

   • Mọi request HTTP đều đi qua fetch_json().
   • Nếu xảy ra lỗi mạng, timeout hoặc mã trạng thái HTTP khác 200, hàm sẽ in thông báo cảnh báo tường minh và trả về None thay vì quăng Exception làm crash chương trình.

3. Cơ chế Handshake Cookie Tự động (VCI Integration):

   • Các endpoint thống kê tài chính chuyên sâu của VCI yêu cầu session cookie hợp lệ từ trang bảng giá.
   • quant_agent tự động thực hiện handshake nhẹ qua vci_session_cookies() và đính kèm vào header request mà người dùng không cần can thiệp thủ công.

4. Luồng giao dịch bảo mật 2 lớp (broker/dnse.py):

   • Tách biệt hoàn toàn khỏi các hàm đọc dữ liệu thị trường (Read-Only).
   • Yêu cầu quy trình 2 bước: Đăng nhập nhận JWT Token -> Xác thực OTP nhận Trading Token -> Ký lệnh gửi lên sàn.

---

📖 Hướng dẫn sử dụng nhanh

import quant_agent as qa

# Kiểm tra phiên bản
print(qa.__version__)  # 0.3.1

1. Danh sách mã niêm yết

# Lấy danh sách toàn bộ cổ phiếu niêm yết (nguồn Wifeed - khuyến nghị)
df_symbols = qa.listing_companies(live=True, source='Wifeed')
print(df_symbols.head())

# Hoặc đọc từ file CSV offline do bạn tự quản lý
df_offline = qa.listing_companies(live=False, path='path/to/my_symbols.csv')

2. Dữ liệu giá lịch sử & Kỹ thuật (OHLC)

# Lấy dữ liệu OHLC hàng ngày (mặc định nguồn DNSE)
df_daily = qa.stock_historical_data(
    symbol='TCB', 
    start_date='2026-01-01', 
    end_date='2026-08-30', 
    resolution='1D', 
    type='stock', 
    beautify=True, # Đổi giá sang đơn vị VNĐ
    decor=True     # Đặt 'Time' làm Index, đổi tên cột dạng Title Case (hỗ trợ TA-Lib)
)
print(df_daily.head())

# Lấy dữ liệu nến intraday (15 phút, 1 giờ...) - Giới hạn 90 ngày gần nhất
df_intraday = qa.stock_historical_data(
    symbol='FPT', 
    start_date='2026-08-01', 
    end_date='2026-08-30', 
    resolution='15' # '1', '15', '30', '1H'
)

# Lấy nến chỉ số thị trường hoặc phái sinh
df_vnindex = qa.stock_historical_data(symbol='VNINDEX', type='index')
df_vn30f1m = qa.stock_historical_data(symbol='VN30F1M', type='derivative')

# Lấy dữ liệu OHLC dài hạn (nguồn VCI - VietCap, hỗ trợ tối đa 1000 nến/lần gọi)
df_longterm = qa.stock_historical_data(
    symbol='TCB', 
    start_date='2022-01-01', 
    end_date='2026-08-30', 
    resolution='1D', 
    source='VCI'
)

# Hoặc gọi hàm chuyên biệt:
# df_longterm = qa.longterm_ohlc_data('TCB', start_date='2022-01-01', end_date='2026-08-30')

3. Dữ liệu cơ bản doanh nghiệp

symbol = 'TCB'

# 1. Tổng quan doanh nghiệp
df_overview = qa.company_overview(symbol)

# 2. Hồ sơ mô tả hoạt động kinh doanh (đã làm sạch thẻ HTML)
df_profile = qa.company_profile(symbol)

# 3. Danh sách cổ đông lớn
df_shareholders = qa.company_large_shareholders(symbol)

# 4. Ban lãnh đạo & Cán bộ chủ chốt
df_officers = qa.company_officers(symbol)

# 5. Danh sách công ty con & liên kết
df_subsidiaries = qa.company_subsidiaries_listing(symbol)

# 6. Lịch sử giao dịch nội bộ / cổ đông lớn
df_insiders = qa.company_insider_deals(symbol)

# 7. Sự kiện doanh nghiệp (cổ tức, chia tách, ĐHCĐ, M&A)
df_events = qa.company_events(symbol)

# 8. Tin tức doanh nghiệp mới nhất
df_news = qa.company_news(symbol)

# 9. Lịch sử chi trả cổ tức
df_div = qa.dividend_history(symbol)

# 10. Biên độ giá & Room ngoại
df_volatility = qa.ticker_price_volatility(symbol)

4. Báo cáo tài chính & Chỉ số định giá

symbol = 'HPG'

# Lấy Báo cáo tài chính theo năm hoặc quý (BalanceSheet, IncomeStatement, CashFlow)
df_bs = qa.financial_report(symbol, report_type='BalanceSheet', frequency='Quarterly')
df_is = qa.financial_report(symbol, report_type='IncomeStatement', frequency='Yearly')
df_cf = qa.financial_report(symbol, report_type='CashFlow', frequency='Yearly')

# Chuỗi thời gian chỉ tiêu tài chính
df_flow = qa.financial_flow(symbol, report_type='incomestatement', report_range='quarterly')

# Chỉ số tài chính chuyên sâu (P/E, P/B, ROE, ROA, EPS, Biên lợi nhuận...)
df_ratios_yearly = qa.financial_ratio(symbol, report_range='yearly', is_all=True)
df_ratios_quarterly = qa.financial_ratio(symbol, report_range='quarterly')

# So sánh chỉ số tài chính nhiều cổ phiếu cùng kỳ
df_compare = qa.financial_ratio_compare(symbol_ls=['HPG', 'NKG', 'HSG'], frequency='Quarterly')
print(df_compare)

# Lịch sử biến động P/E và P/B theo từng quý
df_pe_pb = qa.stock_evaluation(symbol)

5. Bảng giá, Sổ lệnh & Dữ liệu Intraday

# Bảng giá thời gian thực (Top 3 mức giá mua/bán, giá khớp lệnh)
df_board = qa.price_board(['TCB', 'SSI', 'FPT'])

# Sổ lệnh độ sâu (VPS Order Book)
df_depth = qa.price_depth('TCB,SSI,VND')

# Từng giao dịch khớp lệnh trong phiên (Tick-by-tick intraday trades)
df_trades = qa.stock_intraday_data('ACB', page_size=100)

6. Dữ liệu Quỹ mở (Fmarket)

import quant_agent.funds as qa_funds

# Lấy danh sách các quỹ mở (Lọc theo fund_type: "", "STOCK", "BOND", "BALANCED")
df_funds = qa_funds.funds_listing(fund_type="STOCK")

# Lấy thông tin top danh mục nắm giữ của quỹ (Ví dụ mã quỹ 'VESAF' hoặc fundId=23)
df_top_holdings = qa_funds.fund_details(symbol='VESAF', type='top_holding_list')

# Lấy tỷ trọng phân bổ tài sản theo ngành
df_industry = qa_funds.fund_industry_holding(fundId=23)

# Lịch sử NAV/CCQ hàng ngày của quỹ
df_nav = qa_funds.fund_nav_report(fundId='23')

7. Trực quan hóa dữ liệu (Plotly Charts)

import quant_agent.chart as qa_chart

# Lấy dữ liệu OHLC
df = qa.stock_historical_data('TCB', start_date='2026-01-01', end_date='2026-08-30')

# 1. Vẽ biểu đồ nến Candlestick + Volume + các đường MA
fig_candle = qa_chart.candlestick_chart(
    df, 
    title='TCB - Candlestick Chart', 
    ma_periods=[10, 20, 50], 
    reference_period=90
)
fig_candle.show()

# 2. Tính toán và vẽ Bollinger Bands
df_bb = qa_chart.bollinger_bands(df, window=20, num_std_dev=2)
fig_bb = qa_chart.bollinger_bands_chart(df_bb, title='TCB - Bollinger Bands')
fig_bb.show()

8. Xuất dữ liệu sang AmiBroker

# Xuất dữ liệu ra file CSV chuẩn tương thích AmiBroker
qa.amibroker_ohlc_export(
    path='./data_export', 
    symbol='TCB', 
    start_date='2026-01-01', 
    end_date='2026-08-30', 
    resolution='1D'
)

9. Giao dịch tự động qua Broker (DNSE)

⚠️ CẢNH BÁO QUAN TRỌNG: Phân hệ broker thực hiện đặt lệnh thật trên tài khoản chứng khoán thực tế với tiền thật. Hãy kiểm tra kỹ tham số trước khi gọi các hàm đặt lệnh.

from quant_agent.broker import DNSEClient

client = DNSEClient()

# 1. Đăng nhập lấy JWT Token
client.login(user_name="064CXXXXXX", password="YOUR_PASSWORD")

# 2. Xem thông tin tài khoản & danh sách tiểu khoản
profile = client.account()
sub_accs = client.sub_accounts()
sub_id = "064CXXXXXX1"

# 3. Tra cứu số dư và sức mua
balance = client.account_balance(sub_id)
capacity = client.trade_capacities(symbol="TCB", price=34000, sub_account=sub_id)

# 4. Xác thực 2 bước lấy Trading Token (cần thiết trước khi đặt lệnh)
# client.email_otp() # Nếu dùng Email OTP
client.get_trading_token(otp="123456", smart_otp=True)

# 5. Đặt lệnh mua/bán (THẬT)
order = client.place_order(
    sub_account=sub_id,
    symbol="TCB",
    side="buy",       # 'buy' hoặc 'sell'
    quantity=100,
    price=34000,
    order_type="LO",
    loan_package_id=None,
    asset_type="stock"
)

# 6. Tra cứu sổ lệnh và hủy lệnh
orders = client.order_list(sub_account=sub_id)
# client.cancel_order(order_id="...", sub_account=sub_id)

---

🩺 Kiểm thử sức khỏe hệ thống (Smoke Test)

Do quant_agent kết nối trực tiếp tới các cổng API tài chính không chính thức của các bên thứ ba, bạn có thể chạy bộ kiểm thử smoke test bất cứ lúc nào để kiểm tra tính sẵn sàng của từng endpoint:

python tests/test_smoke.py

Kết quả kiểm thử thực tế:

Feature                                                    Status   Detail
------------------------------------------------------------------------------------------------------------------------
config.today                                               PASS     2026-09-06
fundamental.listing_companies(live=True, Wifeed)           PASS     shape=(1820, 6)
fundamental.company_overview [VCI]                         PASS     shape=(1, 8)
fundamental.company_large_shareholders [VCI]               PASS     shape=(56, 7)
fundamental.financial_ratio(yearly) [VCI]                  PASS     shape=(53, 5)
fundamental.financial_report(BalanceSheet) [VCI]           PASS     shape=(8, 338)
technical.stock_historical_data(DNSE)                      PASS     shape=(33, 7)
technical.stock_historical_data(VCI)                       PASS     shape=(32, 7)
technical.longterm_ohlc_data [VCI]                         PASS     shape=(151, 7)
trading.price_board [VCI]                                  PASS     shape=(2, 16)
trading.price_depth [VPS]                                  PASS     shape=(2, 22)
trading.stock_intraday_data [VCI]                          PASS     shape=(20, 5)
funds.funds_listing                                        PASS     shape=(68, 11)
chart.candlestick_chart                                    PASS     Figure(...)
integration.amibroker_ohlc_export [DNSE]                   PASS     wrote CSV, shape=(33, 7)
...
45/48 PASS, 3 EMPTY (expected: SSI Cloudflare), 0 CRASH

---

⚖️ Tuyên bố miễn trừ trách nhiệm (Disclaimer)

1. quant-agent (Python package: quant_agent) là dự án mã nguồn mở phục vụ mục đích nghiên cứu, học tập và phân tích dữ liệu cá nhân.
2. Thư viện kết nối tới các dịch vụ API công cộng/không chính thức của các tổ chức tài chính. Tác giả không sở hữu, không đảm bảo tính sẵn sàng liên tục, tính toàn vẹn hoặc độ trễ thấp nhất của dữ liệu.
3. Người dùng tự chịu hoàn toàn trách nhiệm pháp lý và tài chính khi sử dụng module đặt lệnh (broker) trên tài khoản giao dịch thực tế của mình.