Vnstock (thinh-vu/vnstock)

Vnstock

https://github.com/thinh-vu/vnstock
Admin
Vnstock is an open-source Python toolkit for stock market analysis, financial data access, and...

Tokens:24,137
Snippets:210
Trust Score:9.3
Update:1 month ago
Show doc for...
Context Summary (auto-generated)
Raw
# Vnstock

Vnstock là bộ công cụ mã nguồn mở toàn diện dành cho phân tích và tự động hóa đầu tư chứng khoán tại Việt Nam. Thư viện cung cấp các hàm Python thân thiện để truy xuất dữ liệu giá lịch sử, thông tin công ty, báo cáo tài chính, và nhiều loại dữ liệu thị trường khác từ các nguồn như KB Securities (KBS), VCI, và MSN.

Với sứ mệnh "Mang dữ liệu chứng khoán và công cụ đầu tư đến gần hơn với tất cả mọi người", Vnstock hỗ trợ đa dạng các loại tài sản bao gồm cổ phiếu, chứng quyền, chỉ số thị trường, hợp đồng tương lai, trái phiếu, ngoại hối, tiền điện tử và quỹ mở. Tất cả dữ liệu trả về đều là Pandas DataFrame, giúp dễ dàng phân tích và tích hợp với các hệ thống tự động hóa.

## Cài đặt thư viện

Cài đặt Vnstock thông qua pip để bắt đầu sử dụng các tính năng phân tích tài chính.

```python
# Cài đặt bản ổn định từ PyPI
pip install -U vnstock

# Hoặc cài đặt bản thử nghiệm từ GitHub
pip install git+https://github.com/thinh-vu/vnstock
```

## Đăng ký API Key

Đăng ký API key miễn phí để tăng giới hạn sử dụng từ 20 requests/phút (Guest) lên 60 requests/phút (Community).

```python
from vnstock import register_user

# Phương pháp 1: Đăng ký tương tác qua prompt
register_user()

# Phương pháp 2: Đăng ký trực tiếp với API key
register_user(api_key='vnstock_YOUR_API_KEY')

# Kiểm tra trạng thái đăng ký
from vnstock import check_status
check_status()
# Output:
# ✓ API key: vnst***_KEY
#   Tier: Community
#   Giới hạn: 60 requests/phút
```

## Vnstock Client - Giao diện làm việc chính

Lớp Vnstock là điểm truy cập chính thống nhất cho tất cả các loại dữ liệu tài chính bao gồm cổ phiếu, forex, crypto, chỉ số thế giới và quỹ mở.

```python
from vnstock import Vnstock

# Khởi tạo client với nguồn dữ liệu mặc định
stock = Vnstock(source='KBS')

# Truy cập dữ liệu cổ phiếu Việt Nam
acb = stock.stock(symbol='ACB', source='KBS')

# Lấy giá lịch sử
df_history = acb.quote.history(start='2024-01-01', end='2024-12-31')
print(df_history.head())
#         time   open   high    low  close   volume
# 0 2024-01-02  25.40  25.60  25.15  25.35  3245600
# 1 2024-01-03  25.40  25.80  25.35  25.70  4123500

# Truy xuất thông tin công ty
profile = acb.company.overview()

# Truy xuất báo cáo tài chính
balance = acb.finance.balance_sheet(period='year')
```

## Quote - Dữ liệu giá lịch sử và giao dịch

Lớp Quote cung cấp các phương thức truy xuất dữ liệu giá OHLCV lịch sử và dữ liệu khớp lệnh trong ngày với nhiều khung thời gian khác nhau.

```python
from vnstock import Quote

# Khởi tạo Quote với mã chứng khoán
quote = Quote(symbol='VNM', source='KBS')

# Lấy dữ liệu giá lịch sử theo khoảng thời gian
df = quote.history(
    start='2024-01-01',
    end='2024-06-30',
    interval='1D'  # Các giá trị: 1m, 5m, 15m, 30m, 1H, 1D, 1W, 1M
)
print(df)
#         time   open   high    low  close    volume
# 0 2024-01-02  78.50  79.20  78.00  78.80   1523400
# 1 2024-01-03  78.90  79.50  78.60  79.30   1845200

# Lấy dữ liệu theo số ngày gần nhất (length)
df_3m = quote.history(length='3M', interval='1D')  # 3 tháng gần nhất

# Lấy số lượng nến cụ thể
df_100 = quote.history(count_back=100, interval='1D')  # 100 nến gần nhất

# Lấy dữ liệu khớp lệnh trong ngày (intraday)
df_intraday = quote.intraday(page_size=1000, page=1)
print(df_intraday.head())
#                  time   price  volume match_type                        id
# 0 2024-06-30 14:45:23   79.50     500        buy  20240630_144523_79500_500
# 1 2024-06-30 14:45:20   79.45     300       sell  20240630_144520_79450_300
```

## Listing - Danh sách mã chứng khoán

Lớp Listing cung cấp danh sách các mã chứng khoán niêm yết, phân loại theo sàn giao dịch, ngành nghề và các nhóm đặc biệt.

```python
from vnstock import Listing

# Khởi tạo Listing
listing = Listing(source='KBS')

# Lấy danh sách tất cả mã cổ phiếu
all_stocks = listing.all_symbols()
print(all_stocks.head())
#   symbol                      name exchange
# 0    AAA       Nhựa An Phát Xanh      HOSE
# 1    AAM    Thủy Sản Mekong        HOSE

# Danh sách theo sàn giao dịch
by_exchange = listing.symbols_by_exchange()
print(by_exchange[by_exchange['exchange'] == 'HOSE'].head())

# Danh sách theo ngành ICB
by_industry = listing.symbols_by_industries()

# Danh sách phân loại ngành ICB
icb = listing.industries_icb()
print(icb.head())
#   icb_code               icb_name  level
# 0     8000           Tài chính      1
# 1     8300           Ngân hàng      2

# Danh sách theo nhóm đặc biệt (VN30, HNX30, ETF, CW...)
vn30 = listing.symbols_by_group(group='VN30')
print(vn30)
# ['ACB', 'BCM', 'BID', 'BVH', 'CTG', 'FPT', ...]

# Các phương thức tiện ích
futures = listing.all_future_indices()        # Hợp đồng tương lai
bonds = listing.all_government_bonds()        # Trái phiếu chính phủ
cw = listing.all_covered_warrant()            # Chứng quyền
```

## Company - Thông tin doanh nghiệp

Lớp Company cung cấp thông tin chi tiết về doanh nghiệp bao gồm tổng quan, cổ đông, ban lãnh đạo, công ty con và tin tức.

```python
from vnstock import Company

# Khởi tạo Company với mã chứng khoán
company = Company(symbol='FPT', source='KBS')

# Thông tin tổng quan công ty
overview = company.overview()
print(overview)
#                    field                                value
# 0          short_name                                  FPT
# 1           full_name      Công ty Cổ phần FPT
# 2            exchange                                 HOSE
# 3            industry                      Công nghệ thông tin
# 4         market_cap                    150000000000000

# Danh sách cổ đông lớn
shareholders = company.shareholders()
print(shareholders.head())
#                   name    shares  percentage
# 0  Trương Gia Bình    45000000       8.50%
# 1  Dragon Capital     35000000       6.60%

# Ban lãnh đạo công ty
officers = company.officers(filter_by='working')  # 'working', 'resigned', 'all'
print(officers.head())
#                name           position        start_date
# 0  Trương Gia Bình      Chủ tịch HĐQT        2000-01-01
# 1  Nguyễn Văn Khoa   Tổng Giám đốc        2019-03-15

# Công ty con và liên kết
subsidiaries = company.subsidiaries(filter_by='subsidiary')
affiliates = company.affiliate()

# Tin tức và sự kiện công ty
news = company.news()
events = company.events()
print(news.head())
#         date                                            title
# 0 2024-06-15  FPT công bố kết quả kinh doanh quý 2/2024
```

## Finance - Báo cáo tài chính

Lớp Finance cung cấp các báo cáo tài chính chi tiết bao gồm bảng cân đối kế toán, kết quả kinh doanh, lưu chuyển tiền tệ và các chỉ số tài chính.

```python
from vnstock import Finance

# Khởi tạo Finance với mã chứng khoán
finance = Finance(symbol='VCI', source='KBS')

# Bảng cân đối kế toán (Balance Sheet)
balance = finance.balance_sheet(
    period='year',          # 'year' hoặc 'quarter'
    display_mode='std'      # 'std', 'all', 'vi', 'en'
)
print(balance.head())
#                                    item      item_id      2023      2022      2021
# 0                     Tài sản ngắn hạn  current_assets  5000000  4500000  4000000
# 1         Tiền và tương đương tiền         cash       1500000  1200000  1000000

# Báo cáo kết quả kinh doanh (Income Statement)
income = finance.income_statement(period='quarter')
print(income.head())
#                              item                 item_id  2024-Q1  2023-Q4  2023-Q3
# 0            Doanh thu thuần         net_revenue  2500000  2800000  2600000
# 1     Lợi nhuận gộp            gross_profit   800000   900000   850000

# Báo cáo lưu chuyển tiền tệ (Cash Flow Statement)
cashflow = finance.cash_flow(period='year')
print(cashflow.head())
#                                         item                          item_id      2023
# 0  Lưu chuyển tiền từ hoạt động kinh doanh  cash_from_operating_activities  1200000
# 1  Lợi nhuận trước thuế                           profit_before_tax   500000

# Các chỉ số tài chính (Financial Ratios)
ratios = finance.ratio(period='year')
print(ratios.head())
#                           item           item_id      2023      2022
# 0                  P/E              pe_ratio     15.20     14.80
# 1                  P/B              pb_ratio      2.50      2.30
# 2                  ROE                   roe     18.50     17.20
# 3                  ROA                   roa     10.20      9.80
```

## Trading - Dữ liệu giao dịch thị trường

Lớp Trading cung cấp bảng giá realtime và thống kê giao dịch cho danh sách mã chứng khoán.

```python
from vnstock import Trading

# Khởi tạo Trading
trading = Trading(source='KBS')

# Bảng giá realtime cho danh sách mã
price_board = trading.price_board(
    symbols_list=['VCB', 'ACB', 'TCB', 'BID', 'CTG'],
    exchange='HOSE',
    get_all=False  # True để lấy tất cả cột
)
print(price_board)
#   symbol  ref_price  ceiling  floor  open   high    low  close   volume  exchange
# 0    VCB      92.50    98.90  86.10  92.80  93.50  92.20  93.00  2345600      HOSE
# 1    ACB      25.35    27.10  23.60  25.50  25.80  25.20  25.60  4123500      HOSE

# Lấy tất cả các cột dữ liệu
price_board_full = trading.price_board(
    symbols_list=['VCB', 'ACB'],
    get_all=True
)

# Thống kê giao dịch
from vnstock import Trading
trading = Trading(source='KBS', symbol='VCB')
stats = trading.trading_stats(start='2024-01-01', end='2024-06-30')
```

## Dữ liệu thị trường quốc tế - Forex, Crypto, Index

Vnstock hỗ trợ truy xuất dữ liệu thị trường quốc tế bao gồm tỷ giá ngoại tệ, tiền điện tử và các chỉ số thế giới thông qua nguồn MSN.

```python
from vnstock import Vnstock

stock = Vnstock()

# Dữ liệu Forex (Tỷ giá ngoại tệ)
fx = stock.fx(symbol='EURUSD', source='MSN')
df_fx = fx.quote.history(
    start='2024-01-01',
    end='2024-06-30',
    interval='1D'
)
print(df_fx.head())
#         time    open    high     low   close
# 0 2024-01-02  1.1045  1.1080  1.1020  1.1065
# 1 2024-01-03  1.1068  1.1095  1.1040  1.1050

# Dữ liệu Crypto (Tiền điện tử)
btc = stock.crypto(symbol='BTC', source='MSN')
df_btc = btc.quote.history(
    start='2024-01-01',
    end='2024-06-30',
    interval='1D'
)
print(df_btc.head())
#         time      open      high       low     close
# 0 2024-01-02  42500.00  43200.00  42100.00  42800.00

# Dữ liệu chỉ số thế giới
djia = stock.world_index(symbol='DJI', source='MSN')  # Dow Jones
sp500 = stock.world_index(symbol='SPX', source='MSN')  # S&P 500
nasdaq = stock.world_index(symbol='IXIC', source='MSN')  # NASDAQ

df_djia = djia.quote.history(start='2024-01-01', end='2024-06-30')
print(df_djia.head())

# Các cặp tiền tệ phổ biến: EURUSD, GBPUSD, USDJPY, JPYVND
fx_jpy = stock.fx(symbol='JPYVND', source='MSN')
df_jpyvnd = fx_jpy.quote.history(start='2024-01-01', end='2024-03-31')
```

## Fund - Dữ liệu quỹ mở

Lớp Fund cung cấp thông tin về các quỹ mở đang giao dịch trên Fmarket, bao gồm danh sách quỹ, NAV, top holdings và phân bổ tài sản.

```python
from vnstock.explorer.fmarket.fund import Fund

# Khởi tạo Fund
fund = Fund()

# Danh sách tất cả quỹ mở
all_funds = fund.listing()
print(all_funds.head())
#   short_name                            name fund_type     nav_1m    nav_3m
# 0     SSISCA        Quỹ đầu tư cổ phiếu SSI     STOCK      2.50%     8.30%
# 1     VCBFBC   Quỹ đầu tư cân bằng VCB  BALANCED      1.20%     4.50%

# Lọc theo loại quỹ: 'STOCK', 'BOND', 'BALANCED'
stock_funds = fund.listing(fund_type='STOCK')
bond_funds = fund.listing(fund_type='BOND')

# Tìm kiếm quỹ theo tên viết tắt
result = fund.filter(symbol='SSISCA')
print(result)
#    id  shortName
# 0  23     SSISCA

# Chi tiết quỹ - Top holdings (cổ phiếu nắm giữ hàng đầu)
top_holding = fund.details.top_holding(symbol='SSISCA')
print(top_holding)
#   stock_code       industry  net_asset_percent type_asset   update_at  short_name
# 0        FPT  Công nghệ TT             8.50%      STOCK  2024-06-15      SSISCA
# 1        VNM     Thực phẩm             6.20%      STOCK  2024-06-15      SSISCA

# Phân bổ theo ngành
industry_holding = fund.details.industry_holding(symbol='SSISCA')
print(industry_holding)
#              industry  net_asset_percent
# 0     Công nghệ TT             25.50%
# 1         Ngân hàng             20.30%

# Lịch sử NAV
nav_history = fund.details.nav_report(symbol='SSISCA')
print(nav_history.head())
#         date  nav_per_unit
# 0 2024-06-15        25,450
# 1 2024-06-14        25,380

# Phân bổ tài sản
asset_holding = fund.details.asset_holding(symbol='SSISCA')
print(asset_holding)
#   asset_percent    asset_type
# 0         85.00%      Cổ phiếu
# 1         10.00%   Tiền mặt
# 2          5.00%    Trái phiếu
```

## Tỷ giá và Giá vàng

Các hàm tiện ích để truy xuất tỷ giá ngoại tệ từ Vietcombank và giá vàng SJC.

```python
from vnstock.explorer.misc import vcb_exchange_rate, sjc_gold_price

# Tỷ giá ngoại tệ Vietcombank
exchange_rate = vcb_exchange_rate(date='2024-06-15')
print(exchange_rate)
#   currency_code  currency_name  buy_cash  buy_transfer     sell        date
# 0           USD     Đô la Mỹ    24,950        24,980    25,320  2024-06-15
# 1           EUR         Euro    26,800        26,850    28,050  2024-06-15
# 2           GBP   Bảng Anh    31,200        31,280    32,650  2024-06-15

# Tỷ giá ngày hiện tại
today_rate = vcb_exchange_rate(date='')

# Giá vàng SJC
gold_price = sjc_gold_price(date='2024-06-15')
print(gold_price)
#                    name     branch  buy_price  sell_price        date
# 0  Vàng miếng SJC 1L-10L    TP.HCM   79,500.0    81,500.0  2024-06-15
# 1  Vàng miếng SJC 1L-10L    Hà Nội   79,500.0    81,500.0  2024-06-15

# Giá vàng ngày hiện tại
today_gold = sjc_gold_price()

# Giá vàng Bảo Tín Minh Châu
from vnstock.explorer.misc.gold_price import btmc_goldprice
btmc = btmc_goldprice()
print(btmc.head())
#                  name  karat  gold_content  buy_price  sell_price         time
# 0     Vàng SJC 9999     24        99.99%    79,500     81,500  2024-06-15
```

## Chart - Trực quan hóa dữ liệu

Module Chart cung cấp các phương thức vẽ biểu đồ trực tiếp từ DataFrame với nhiều loại biểu đồ khác nhau.

```python
from vnstock import Quote
from vnstock.common.viz import Chart, get_chart

# Lấy dữ liệu giá
quote = Quote(symbol='VNM', source='KBS')
df = quote.history(start='2024-01-01', end='2024-06-30', interval='1D')

# Cách 1: Sử dụng extension .viz trên DataFrame
df.viz.candle()           # Biểu đồ nến (candlestick)
df.viz.line()             # Biểu đồ đường
df.viz.bar()              # Biểu đồ cột

# Cách 2: Sử dụng lớp Chart
chart = Chart(df)
chart.candle()            # Biểu đồ nến OHLC
chart.line()              # Biểu đồ đường
chart.bar()               # Biểu đồ cột

# Cách 3: Sử dụng hàm get_chart
chart = get_chart(df, backend='vnstock_chart')
chart.candle()

# Scatter plot (biểu đồ phân tán)
df_scatter = df[['open', 'close']]
df_scatter.viz.scatter(x='open', y='close')

# Heatmap (bản đồ nhiệt) cho ma trận tương quan
correlation = df[['open', 'high', 'low', 'close', 'volume']].corr()
correlation.viz.heatmap()

# Boxplot cho phân tích phân phối
df['close'].viz.boxplot()

# Histogram phân phối volume
df['volume'].viz.hist()

# Pie chart cho phân bổ danh mục
portfolio = pd.Series({'VNM': 30, 'FPT': 25, 'VCB': 20, 'ACB': 15, 'HPG': 10})
portfolio.viz.pie()
```

## Messenger - Gửi thông báo đa nền tảng

Lớp Messenger hỗ trợ gửi tin nhắn và file đính kèm đến các nền tảng Slack, Telegram, Discord và Lark cho mục đích tự động hóa bot giao dịch.

```python
from vnstock.bot.notify import Messenger

# Gửi thông báo qua Slack
slack = Messenger(
    platform='slack',
    channel='#trading-alerts',
    token_key='xoxb-your-slack-bot-token'
)
slack.send_message('Cảnh báo: Giá VNM đã tăng 5%!')
slack.send_message(
    'Báo cáo giao dịch ngày',
    file_path='report.pdf',
    title='Daily_Report'
)

# Gửi thông báo qua Telegram
telegram = Messenger(
    platform='telegram',
    channel='-1001234567890',  # Group/Channel ID
    token_key='your-telegram-bot-token'
)
telegram.send_message('VNM: Giá hiện tại 79,500 VND')
telegram.send_message(
    'Biểu đồ giá ngày',
    file_path='chart.png'  # Hỗ trợ jpg, jpeg, png, webp
)

# Gửi thông báo qua Discord
discord = Messenger(
    platform='discord',
    webhook_url='https://discord.com/api/webhooks/your-webhook-url'
)
discord.send_message('Bot đang hoạt động!')
discord.send_message(
    'Kết quả backtest',
    file_path='backtest_result.xlsx'
)

# Gửi thông báo qua Lark
lark = Messenger(
    platform='lark',
    token_key='your-lark-webhook-token'
)
lark.send_message('Đã hoàn thành phân tích danh mục')
```

## Xuất dữ liệu

Tất cả dữ liệu trả về từ Vnstock đều là Pandas DataFrame, cho phép xuất dễ dàng sang các định dạng phổ biến như Excel, CSV và JSON.

```python
from vnstock import Quote, Finance

# Lấy dữ liệu
quote = Quote(symbol='VNM', source='KBS')
df_price = quote.history(start='2024-01-01', end='2024-06-30')

finance = Finance(symbol='VNM', source='KBS')
df_ratio = finance.ratio(period='year')

# Xuất ra Excel
df_price.to_excel('vnm_price_2024.xlsx', index=False)
df_ratio.to_excel('vnm_financial_ratios.xlsx', index=False)

# Xuất ra CSV
df_price.to_csv('vnm_price_2024.csv', index=False)

# Xuất ra JSON
df_price.to_json('vnm_price_2024.json', orient='records', indent=2)

# Xuất nhiều sheet vào một file Excel
with pd.ExcelWriter('vnm_analysis.xlsx') as writer:
    df_price.to_excel(writer, sheet_name='Price', index=False)
    df_ratio.to_excel(writer, sheet_name='Ratios', index=False)
```

## Cấu hình Proxy

Vnstock hỗ trợ cấu hình proxy để vượt qua các hạn chế mạng hoặc tăng tốc độ truy xuất dữ liệu.

```python
from vnstock import Quote
from vnstock.core.utils.client import ProxyConfig

# Cách 1: Cấu hình proxy trực tiếp
quote = Quote(
    symbol='VNM',
    source='KBS',
    proxy_list=['http://proxy1:8080', 'http://proxy2:8080'],
    proxy_mode='rotate'  # 'try', 'rotate', 'random', 'single'
)
df = quote.history(start='2024-01-01', end='2024-06-30')

# Cách 2: Sử dụng ProxyConfig object
proxy_config = ProxyConfig(
    proxy_mode='rotate',
    proxy_list=['http://user:pass@proxy1:8080', 'http://user:pass@proxy2:8080'],
    request_mode='proxy'
)

quote = Quote(
    symbol='VNM',
    source='KBS',
    proxy_config=proxy_config
)
df = quote.history(start='2024-01-01', end='2024-06-30')
```

## Tổng kết

Vnstock là giải pháp toàn diện cho các nhà đầu tư, nhà phân tích và nhà phát triển muốn xây dựng hệ thống phân tích và tự động hóa giao dịch chứng khoán. Thư viện hỗ trợ đa dạng nguồn dữ liệu (KBS, VCI, MSN, Fmarket), nhiều loại tài sản (cổ phiếu, phái sinh, forex, crypto, quỹ mở), và tích hợp sẵn các công cụ trực quan hóa cùng thông báo đa nền tảng.

Với thiết kế hướng đến người dùng Python, Vnstock giúp rút ngắn thời gian từ ý tưởng đến triển khai. Người dùng có thể dễ dàng tích hợp Vnstock vào các hệ thống bot giao dịch tự động, dashboard phân tích, hoặc các công cụ nghiên cứu tài chính cá nhân. Tất cả dữ liệu trả về đều là Pandas DataFrame, đảm bảo tương thích với hệ sinh thái phân tích dữ liệu Python và các thư viện machine learning.