quantvn 0.1.15

QuantVN API Library for Financial Data Analysis

QuantVN - Python Library for Vietnamese Financial Market Analysis

QuantVN là thư viện Python toàn diện cho phân tích định lượng và truy xuất dữ liệu tài chính, được tối ưu hóa đặc biệt cho thị trường tài chính Việt Nam và cryptocurrency.

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

🆓 Hoàn toàn miễn phí & mã nguồn mở: Dễ dàng truy cập và sử dụng cho cá nhân, nhà phân tích định lượng, và cộng đồng nghiên cứu.

🐍 Giải pháp Python toàn diện: API đơn giản, dễ tích hợp vào hệ thống giao dịch tự động.

📊 Dữ liệu đa thị trường:

• Cổ phiếu Việt Nam (HOSE, HNX, UPCOM)
• Phái sinh VN30
• Cryptocurrency (Binance)
• Dữ liệu quốc tế

📈 Công cụ phân tích mạnh mẽ: Tích hợp sẵn các chỉ số hiệu suất, backtesting, và đánh giá rủi ro.

📦 Cài đặt

Từ PyPI (khuyến nghị)

pip install quantvn

Từ mã nguồn

git clone https://github.com/your-repo/quantvn.git
cd quantvn
pip install -e .

Yêu cầu hệ thống

• Python >= 3.9
• pandas
• requests
• matplotlib
• tqdm

🚀 Bắt đầu nhanh

Khởi tạo API Client

from quantvn.vn.data.utils import client

# Khởi tạo với API key (nếu có)
client(apikey="your_api_key_here")

Lưu ý: Một số chức năng có thể hoạt động mà không cần API key, nhưng khuyến nghị có API key để truy cập đầy đủ.

---

📚 Tài liệu API

1. Dữ liệu Cổ phiếu Việt Nam

Module: quantvn.vn.data

1.1. Danh sách cổ phiếu thanh khoản cao

from quantvn.vn.data import list_liquid_asset

# Lấy danh sách cổ phiếu có thanh khoản cao
liquid_stocks = list_liquid_asset()
print(liquid_stocks.head())

Output mẫu:

  symbol      liquidity
0    VCB   5.234567e+10
1    HPG   4.123456e+10
2    VIC   3.876543e+10

1.2. Dữ liệu lịch sử cổ phiếu

from quantvn.vn.data import get_stock_hist

# Lấy dữ liệu 1H (ví dụ sử dụng khung giờ 1H)
vic_hour = get_stock_hist("VIC", resolution="1H")
print(vic_hour.head())

Tham số:

• symbol (str): Mã cổ phiếu (VD: "VIC", "HPG", "VCB")
• resolution (str): Khung thời gian, hiện chỉ hỗ trợ "1H" (bắt buộc).

Output:

        Date      time   Open   High    Low  Close      volume
0 2024-01-02  09:00:00  42.50  42.80  42.30  42.60  1234567.0
1 2024-01-02  10:00:00  42.60  42.90  42.50  42.75  2345678.0

1.3. Thông tin chi tiết công ty

from quantvn.vn.data import Company

company = Company("VIC")

# Thông tin tổng quan
overview = company.overview()
print(overview[["symbol", "id", "issue_share", "icb_name2", "icb_name4"]])

# Hồ sơ công ty
profile = company.profile()
print(profile.get("companyProfile"))

# Danh sách cổ đông
shareholders = company.shareholders()
print(shareholders.head())

# Ban lãnh đạo
officers = company.officers()
print(officers.head())

# Công ty con
subsidiaries = company.subsidiaries()
print(subsidiaries.head())

# Sự kiện quan trọng
events = company.events()
print(events.head())

# Tin tức
news = company.news()
print(news.head())

# Tỷ số tài chính tổng hợp
ratios = company.ratio_summary()
print(ratios[["pe", "pb", "roe", "roa"]])

1.4. Tỷ số tài chính

from quantvn.vn.data import Finance

# Khởi tạo Finance (dùng BACKEND mặc định)
finance = Finance("HPG")

# Tỷ số tài chính theo quý
ratios_q = finance.ratio(period="Q")
print("Tỷ số tài chính theo quý:")
if not ratios_q.empty:
    print(ratios_q[["year", "quarter", "revenue", "netProfit", "roe", "pe", "pb"]].head())

# Tỷ số tài chính theo năm
ratios_y = finance.ratio(period="Y")
print("\nTỷ số tài chính theo năm:")
if not ratios_y.empty:
    print(ratios_y[["year", "revenue", "netProfit", "roe", "pe", "pb"]].head())

Tham số:

• period (str): "Q" (quý) hoặc "Y" (năm)
• dropna (bool): Loại bỏ các giá trị null (mặc định: False)

1.5. Dữ liệu Quote realtime

from quantvn.vn.data import Quote

quote = Quote("ACB")

# Lấy dữ liệu lịch sử trong khoảng thời gian
history = quote.history(
    start="2024-01-01",
    end="2024-03-31",
    interval="1D"
)
print(history.head())

# Dữ liệu tick intraday
intraday = quote.intraday(page_size=200)
print(intraday.head())

# Độ sâu thị trường (price depth)
depth = quote.price_depth()
print(depth.head())

1.6. Thông tin giao dịch

from quantvn.vn.data import Trading

# Bảng giá nhiều mã cùng lúc
price_board = Trading.price_board(["VCB", "ACB", "TCB"])
print(price_board)

1.7. Quỹ mở

from quantvn.vn.data import Fund

fund = Fund()

# Danh sách tất cả quỹ
all_funds = fund.listing()
print(all_funds.head())

# Lọc theo loại quỹ
stock_funds = fund.listing(fund_type="STOCK")    # Quỹ cổ phiếu
bond_funds = fund.listing(fund_type="BOND")      # Quỹ trái phiếu
balanced_funds = fund.listing(fund_type="BALANCED")  # Quỹ cân bằng

print("Quỹ cổ phiếu:")
print(stock_funds[["name", "code", "nav"]].head())

# Tìm kiếm quỹ theo tên
search_result = fund.filter("RVPIF")
print(search_result)

1.8. Danh sách mã chứng khoán

from quantvn.vn.data import Listing

listing = Listing()

# Lấy danh sách mã theo sàn
symbols = listing.symbols_by_exchange()
print(f"HOSE: {len(symbols['HOSE'])} symbols")
print(f"HNX: {len(symbols['HNX'])} symbols")
print(f"UPCOM: {len(symbols['UPCOM'])} symbols")

---

2. Phái sinh VN30

from quantvn.vn.data import get_derivatives_hist

# Dữ liệu VN30F1M theo phút
vn30_1m = get_derivatives_hist("VN30F1M", resolution="1m")
print(vn30_1m.head())

# Dữ liệu VN30F1M theo 5 phút
vn30_5m = get_derivatives_hist("VN30F1M", resolution="5m")
print(vn30_5m.head())

# Dữ liệu VN30F1M theo 15 phút
vn30_15m = get_derivatives_hist("VN30F1M", resolution="15m")
print(vn30_15m.head())

# Các resolution hỗ trợ: "1m", "5m", "15m"

Output:

        Date      time    Open    High     Low   Close   volume
0 2024-01-02  09:01:00  1250.0  1252.0  1249.5  1251.0    450.0
1 2024-01-02  09:02:00  1251.0  1253.5  1250.5  1252.5    380.0

---

3. Dữ liệu Cryptocurrency

Module: quantvn.crypto.data

from quantvn.crypto.data import get_crypto_hist

# Lấy dữ liệu BTCUSDT theo phút (từ Binance)
btc_1m = get_crypto_hist(
    symbol="BTCUSDT",
    interval="1m",
    cache_dir="./cache"  # Thư mục cache (tùy chọn)
)
print(btc_1m.head())

# Các interval hỗ trợ
btc_5m = get_crypto_hist("BTCUSDT", interval="5m")
btc_1h = get_crypto_hist("BTCUSDT", interval="1h")
btc_1d = get_crypto_hist("BTCUSDT", interval="1d")

# Các symbol phổ biến: BTCUSDT, ETHUSDT, BNBUSDT, etc.
eth_1h = get_crypto_hist("ETHUSDT", interval="1h")

Tham số:

• symbol (str): Cặp giao dịch trên Binance (VD: "BTCUSDT", "ETHUSDT")
• interval (str): Khung thời gian ("1m", "5m", "15m", "30m", "1h", "4h", "1d")
• cache_dir (str|Path): Thư mục lưu cache (mặc định: ~/.cache/quantvn)

Output:

              Datetime        Date      time      Open      High       Low     Close        volume
0 2024-01-02 00:00:00  2024-01-02  00:00:00  42150.50  42200.00  42100.25  42180.75  1234.567890

Lưu ý:

• Dữ liệu được cache cục bộ, lần tải sau sẽ nhanh hơn
• Dữ liệu lấy từ Binance Public Data (miễn phí)
• Thời gian được chuyển sang UTC+7 (Vietnam timezone)

---

4. Thị trường quốc tế

from quantvn.vn.data import Global

global_market = Global()

# Forex - Tỷ giá ngoại tệ
usdvnd = global_market.fx("USDVND").quote.history(
    start="2024-01-01",
    end="2024-12-31"
)
print(usdvnd.head())

eurusd = global_market.fx("EURUSD").quote.history(
    start="2024-01-01",
    end="2024-03-31"
)

# Cryptocurrency
btc = global_market.crypto("BTCUSD").quote.history(
    start="2024-01-01",
    end="2024-12-31"
)
print(btc.head())

# Chỉ số thế giới
sp500 = global_market.world_index("SPX").quote.history(
    start="2024-01-01",
    end="2024-12-31"
)

dow = global_market.world_index("DJI").quote.history(
    start="2024-01-01",
    end="2024-12-31"
)

nikkei = global_market.world_index("N225").quote.history(
    start="2024-01-01",
    end="2024-12-31"
)

---

5. Technical Analysis & Fundamental Features

5.1. Thêm chỉ báo kỹ thuật

from quantvn.vn.data import add_all_ta_features, get_stock_hist

# Lấy dữ liệu
df = get_stock_hist("VIC", resolution="1H")

# Thêm tất cả chỉ báo kỹ thuật
df_with_ta = add_all_ta_features(df)

# DataFrame sẽ có thêm các cột: RSI, MACD, Bollinger Bands, etc.
print(df_with_ta.columns)

5.2. Thêm chỉ số tài chính cơ bản

from quantvn.vn.data import add_all_fund_features, get_stock_hist

# Lấy dữ liệu
df = get_stock_hist("HPG", resolution="1H")

# Thêm các chỉ số tài chính (PE, PB, ROE, ROA, etc.)
df_with_fund = add_all_fund_features(df, symbol="HPG")

print(df_with_fund.columns)

5.3. Lấy từng chỉ số cụ thể

from quantvn.vn.data import fund_feature

# Lấy ROE
roe_data = fund_feature("roe", "VCB")
print(roe_data.head())

# Lấy EPS
eps_data = fund_feature("earningPerShare", "HPG")
print(eps_data.head())

# Lấy P/E ratio
pe_data = fund_feature("priceToEarning", "VIC")
print(pe_data.head())

Các chỉ số khả dụng:

• earningPerShare (EPS)
• bookValuePerShare (BVPS)
• roe (Return on Equity)
• roa (Return on Assets)
• priceToEarning (P/E)
• priceToBook (P/B)
• Và nhiều chỉ số khác...

---

6. Backtesting & Performance Analysis

6.1. Backtest cho phái sinh

from quantvn.vn.metrics import Backtest_Derivates
from quantvn.vn.data import get_derivatives_hist
import pandas as pd

# Lấy dữ liệu
df = get_derivatives_hist("VN30F1M", resolution="5m")

# Tạo tín hiệu giao dịch đơn giản (ví dụ: MA crossover)
df["ma_short"] = df["Close"].rolling(20).mean()
df["ma_long"] = df["Close"].rolling(50).mean()

# Position: 1 (long), -1 (short), 0 (no position)
df["position"] = 0
df.loc[df["ma_short"] > df["ma_long"], "position"] = 1
df.loc[df["ma_short"] < df["ma_long"], "position"] = -1

# Chạy backtest (PnL sau phí)
backtest = Backtest_Derivates(df, pnl_type="after_fees")

# Xem PnL tích lũy
pnl = backtest.PNL()
print(f"Final PnL: {pnl.iloc[-1]:,.2f} VND")

# PnL theo ngày
daily_pnl = backtest.daily_PNL()
print(daily_pnl.tail())

# Ước tính vốn tối thiểu
min_capital = backtest.estimate_minimum_capital()
print(f"Minimum capital needed: {min_capital:,.0f} VND")

# Vẽ biểu đồ PnL
backtest.plot_PNL("VN30F1M - MA Crossover Strategy")

Tham số:

• pnl_type (str):
  • "raw": PnL thô (chưa trừ phí)
  • "after_fees": PnL sau khi trừ phí giao dịch

6.2. Backtest cho cổ phiếu

from quantvn.vn.metrics import Backtest_Stock
from quantvn.vn.data import get_stock_hist

# Lấy dữ liệu
df = get_stock_hist("VIC", resolution="1H")

# Tạo chiến lược đơn giản
df["ma20"] = df["Close"].rolling(20).mean()
df["ma50"] = df["Close"].rolling(50).mean()

# Position: số lượng cổ phiếu (ví dụ: 100 cổ)
df["position"] = 0
df.loc[df["ma20"] > df["ma50"], "position"] = 100

# Backtest
backtest = Backtest_Stock(df, pnl_type="after_fees")

# Vẽ PnL
backtest.plot_PNL("VIC - MA(20/50) Strategy")

6.3. Metrics - Đánh giá hiệu suất

from quantvn.vn.metrics import Metrics, Backtest_Derivates
from quantvn.vn.data import get_derivatives_hist

# Giả sử đã có backtest
df = get_derivatives_hist("VN30F1M", resolution="5m")
# ... tạo position ...
df["position"] = 1  # Ví dụ đơn giản: long cả ngày

backtest = Backtest_Derivates(df, pnl_type="after_fees")
metrics = Metrics(backtest)

# Các chỉ số hiệu suất
print(f"Sharpe Ratio: {metrics.sharpe():.3f}")
print(f"Sortino Ratio: {metrics.sortino():.3f}")
print(f"Calmar Ratio: {metrics.calmar():.3f}")
print(f"Max Drawdown: {metrics.max_drawdown()*100:.2f}%")
print(f"Win Rate: {metrics.win_rate()*100:.2f}%")
print(f"Profit Factor: {metrics.profit_factor():.3f}")
print(f"Average Win: {metrics.avg_win():,.0f} VND")
print(f"Average Loss: {metrics.avg_loss():,.0f} VND")
print(f"Risk of Ruin: {metrics.risk_of_ruin():.4f}")

# Value at Risk (95% confidence)
var_95 = metrics.value_at_risk(confidence_level=0.95)
print(f"VaR (95%): {var_95:,.0f} VND")

Các metrics có sẵn:

• sharpe(): Sharpe Ratio
• sortino(): Sortino Ratio
• calmar(): Calmar Ratio
• max_drawdown(): Drawdown tối đa
• win_rate(): Tỷ lệ thắng
• profit_factor(): Tỷ số lợi nhuận
• avg_win(): Lãi trung bình
• avg_loss(): Lỗ trung bình
• avg_return(): Return trung bình
• volatility(): Độ biến động
• value_at_risk(confidence_level): Value at Risk
• risk_of_ruin(): Xác suất phá sản

6.4. Advanced Backtesting với Take Profit/Stop Loss

from quantvn.metrics import TradingBacktest
from quantvn.vn.data import get_derivatives_hist
import pandas as pd

# Lấy dữ liệu
df = get_derivatives_hist("VN30F1M", resolution="5m")

# Chuẩn hóa tên cột (lowercase)
df.columns = df.columns.str.lower()

# Tạo chiến lược
df["position"] = 1  # Long position

# Khởi tạo backtester
backtester = TradingBacktest(df, pnl_type="raw")

# Áp dụng Take Profit/Stop Loss
# TP: 2%, SL: 1%
df_with_tpsl = backtester.apply_tp_sl(
    df,
    tp_percentage=2.0,
    sl_percentage=1.0
)

# Áp dụng Trailing Stop Loss
df_with_trailing = backtester.apply_tp_sl_trailing(
    df,
    tp_percentage=2.0,
    sl_percentage=1.0
)

print("Original strategy positions:", df["position"].sum())
print("With TP/SL positions:", df_with_tpsl["position"].sum())
print("With Trailing SL positions:", df_with_trailing["position"].sum())

---

📊 Ví dụ thực tế

Ví dụ 1: Phân tích cổ phiếu VIC

from quantvn.vn.data.utils import client
from quantvn.vn.data import get_stock_hist, Company, Finance
import matplotlib.pyplot as plt

# Khởi tạo
client(apikey="your_api_key")

# Lấy dữ liệu giá
vic_data = get_stock_hist("VIC", resolution="1H")

# Thông tin công ty
company = Company("VIC")
overview = company.overview()
print("Công ty:", overview["symbol"].iloc[0])
print("ICB2:", overview["icb_name2"].iloc[0])
print("ICB4:", overview["icb_name4"].iloc[0])

# Tỷ số tài chính
finance = Finance("VIC")
ratios = finance.ratio(period="Y")
print("\nTỷ số tài chính 3 năm gần nhất:")
if not ratios.empty:
    print(ratios[["year", "revenue", "netProfit", "roe", "pe", "pb"]].head(3))

# Vẽ biểu đồ giá
plt.figure(figsize=(12, 6))
plt.plot(vic_data.index, vic_data["Close"])
plt.title("VIC Stock Price")
plt.xlabel("Date")
plt.ylabel("Price (VND)")
plt.grid(True)
plt.show()

Ví dụ 2: Chiến lược RSI cho VN30F1M

from quantvn.vn.data import get_derivatives_hist
from quantvn.vn.metrics import Backtest_Derivates, Metrics
import numpy as np

# Lấy dữ liệu
df = get_derivatives_hist("VN30F1M", resolution="5m")

# Tính RSI
def calculate_rsi(prices, period=14):
    delta = prices.diff()
    gain = (delta.where(delta > 0, 0)).rolling(window=period).mean()
    loss = (-delta.where(delta < 0, 0)).rolling(window=period).mean()
    rs = gain / loss
    rsi = 100 - (100 / (1 + rs))
    return rsi

df["rsi"] = calculate_rsi(df["Close"])

# Tín hiệu giao dịch
# Long khi RSI < 30, Short khi RSI > 70
df["position"] = 0
df.loc[df["rsi"] < 30, "position"] = 1   # Long
df.loc[df["rsi"] > 70, "position"] = -1  # Short

# Backtest
backtest = Backtest_Derivates(df, pnl_type="after_fees")
metrics = Metrics(backtest)

# Kết quả
print("=" * 50)
print("RSI STRATEGY - VN30F1M (5min)")
print("=" * 50)
print(f"Final PnL: {backtest.PNL().iloc[-1]:,.0f} VND")
print(f"Sharpe Ratio: {metrics.sharpe():.3f}")
print(f"Win Rate: {metrics.win_rate()*100:.2f}%")
print(f"Max Drawdown: {metrics.max_drawdown()*100:.2f}%")
print(f"Profit Factor: {metrics.profit_factor():.3f}")

# Vẽ biểu đồ
backtest.plot_PNL("VN30F1M - RSI Strategy")

Ví dụ 3: So sánh hiệu suất quỹ cổ phiếu

from quantvn.vn.data import Fund
import pandas as pd

# Lấy danh sách quỹ cổ phiếu
fund = Fund()
stock_funds = fund.listing(fund_type="STOCK")

# Lọc và sắp xếp theo hiệu suất
top_funds = stock_funds.nlargest(10, "nav")

print("TOP 10 QUỸ CỔ PHIẾU THEO NAV:")
print("=" * 80)
for idx, row in top_funds.iterrows():
    print(f"{row['name'][:50]:50s} | NAV: {row['nav']:>12,.2f}")

Ví dụ 4: Tải dữ liệu crypto và phân tích

from quantvn.crypto.data import get_crypto_hist
import matplotlib.pyplot as plt

# Tải dữ liệu Bitcoin
btc = get_crypto_hist("BTCUSDT", interval="1h")

# Tính MA
btc["ma_20"] = btc["Close"].rolling(20).mean()
btc["ma_50"] = btc["Close"].rolling(50).mean()

# Vẽ biểu đồ
plt.figure(figsize=(14, 7))
plt.plot(btc["Datetime"], btc["Close"], label="BTC Price", alpha=0.7)
plt.plot(btc["Datetime"], btc["ma_20"], label="MA 20", alpha=0.8)
plt.plot(btc["Datetime"], btc["ma_50"], label="MA 50", alpha=0.8)
plt.title("Bitcoin Price with Moving Averages")
plt.xlabel("Date")
plt.ylabel("Price (USDT)")
plt.legend()
plt.grid(True)
plt.show()

---

🧪 Testing

Chạy tests:

# Cài đặt dependencies cho dev
pip install -e ".[dev]"

# Chạy tests
pytest tests/

# Chạy với coverage
pytest --cov=quantvn tests/

---

🤝 Đóng góp

Chúng tôi hoan nghênh mọi đóng góp! Để đóng góp:

1. Fork repository
2. Tạo branch mới (git checkout -b feature/AmazingFeature)
3. Commit changes (git commit -m 'Add some AmazingFeature')
4. Push to branch (git push origin feature/AmazingFeature)
5. Mở Pull Request

Vui lòng đọc CONTRIBUTING.md để biết thêm chi tiết.

---

⚠️ Tuyên bố miễn trách nhiệm

QuantVN được phát triển nhằm phục vụ mục đích nghiên cứu và học tập.

• Dữ liệu cung cấp có thể không đầy đủ hoặc không chính xác 100%
• Không khuyến nghị sử dụng cho giao dịch thực tế mà không kiểm chứng kỹ lưỡng
• Tác giả không chịu trách nhiệm về bất kỳ tổn thất tài chính nào phát sinh từ việc sử dụng thư viện này

Lưu ý quan trọng:

• Luôn kiểm tra và xác thực dữ liệu trước khi sử dụng
• Backtesting không đảm bảo kết quả trong tương lai
• Quản lý rủi ro là trách nhiệm của người dùng

---

📄 Giấy phép

Dự án này được phát hành theo giấy phép MIT License. Xem file LICENSE để biết thêm chi tiết.

---

📝 Changelog

Version 0.1.5

• Thêm hỗ trợ cryptocurrency data từ Binance
• Cải thiện performance cho get_stock_hist()
• Sửa lỗi timezone cho dữ liệu phái sinh
• Thêm các metrics mới: Risk of Ruin, VaR

Version 0.1.4

• Thêm module backtesting cho cổ phiếu
• Hỗ trợ Take Profit/Stop Loss
• Cải thiện documentation

---

🔧 Troubleshooting

Lỗi kết nối API

# Kiểm tra API key
from quantvn.vn.data.utils import Config
print(Config.get_api_key())

# Reset API key
client(apikey="new_api_key")

Lỗi timezone

# Dữ liệu mặc định ở timezone UTC+7 (Vietnam)
# Nếu cần chuyển đổi:
import pandas as pd
df["Datetime"] = pd.to_datetime(df["Date"] + " " + df["time"])
df["Datetime"] = df["Datetime"].dt.tz_localize("Asia/Ho_Chi_Minh")

Cache cryptocurrency data

from pathlib import Path

# Xóa cache cũ
cache_dir = Path.home() / ".cache/quantvn"
if cache_dir.exists():
    import shutil
    shutil.rmtree(cache_dir)

# Tải lại dữ liệu mới
from quantvn.crypto.data import get_crypto_hist
btc = get_crypto_hist("BTCUSDT", interval="1h")

---

📞 Hỗ trợ

• GitHub Issues: https://github.com/your-repo/quantvn/issues
• Documentation: Đang phát triển

---

QuantVN - Công cụ phân tích tài chính mạnh mẽ cho thị trường Việt Nam 🇻🇳