0
# VNStock
1

2
A beginner-friendly yet powerful Python toolkit for financial analysis and automation of Vietnamese stock market data. VNStock provides comprehensive access to real-time and historical financial data from Vietnamese stock exchanges, including stocks, indices, derivatives, bonds, forex, and cryptocurrency data with built-in visualization capabilities.
3

4
## Package Information
5

6
- **Package Name**: vnstock
7
- **Language**: Python
8
- **Installation**: `pip install vnstock`
9
- **Python Version**: >=3.10
10
- **License**: Custom (Personal, research, non-commercial use)
11

12
## Core Imports
13

14
```python
15
import vnstock
16
from vnstock import Vnstock, Quote, Company, Finance, Listing, Trading, Screener, Fund
17
```
18

19
For charts and visualization:
20

21
```python
22
from vnstock import chart_wrapper
23
```
24

25
## Basic Usage
26

27
```python
28
import vnstock
29
from vnstock import Vnstock
30

31
# Initialize the main VNStock client
32
stock = Vnstock()
33

34
# Get historical stock data
35
tcb_data = stock.stock(symbol="TCB", source="VCI")
36
price_history = tcb_data.quote.history(start="2023-01-01", end="2023-12-31")
37

38
# Get company information
39
company_info = tcb_data.company.overview()
40

41
# Get financial statements
42
financials = tcb_data.finance.balance_sheet(period="quarter")
43

44
# Create visualizations
45
chart = chart_wrapper(price_history)
46
chart.timeseries()
47
```
48

49
## Architecture
50

51
VNStock follows a modular adapter pattern with multiple data sources:
52

53
- **Main Class (Vnstock)**: Central orchestrator returning specialized component objects
54
- **API Adapters**: Quote, Company, Finance, Listing, Trading, Screener classes with dynamic method dispatch
55
- **Data Sources**: VCI, TCBS, MSN, FMARKET providers with automatic failover
56
- **Fund Explorer**: Specialized Fund class for mutual fund data
57
- **Visualization**: Integrated charting through vnstock_ezchart
58

59
The library supports multiple Vietnamese financial data providers and uses dynamic method resolution for source-specific functionality with built-in retry logic and caching.
60

61
## Capabilities
62

63
### Main Client Interface
64

65
Core VNStock client providing access to all stock market data types through a unified interface. Returns specialized component objects for different asset classes.
66

67
```python { .api }
68
class Vnstock:
69
    def __init__(self, symbol: str = None, source: str = "VCI", show_log: bool = True): ...
70
    def stock(self, symbol: Optional[str] = None, source: Optional[str] = None): ...
71
    def fx(self, symbol: Optional[str] = 'EURUSD', source: Optional[str] = "MSN"): ...
72
    def crypto(self, symbol: Optional[str] = 'BTC', source: Optional[str] = "MSN"): ...
73
    def world_index(self, symbol: Optional[str] = 'DJI', source: Optional[str] = "MSN"): ...
74
    def fund(self, source: Optional[str] = "FMARKET"): ...
75
```
76

77
[Main Client](./main-client.md)
78

79
### Quote Data Management
80

81
Historical and real-time price data including OHLC history, intraday trading data, and market depth information with support for multiple data sources.
82

83
```python { .api }
84
class Quote:
85
    def __init__(self, source: str = "vci", symbol: str = "", random_agent: bool = False, show_log: bool = False): ...
86
    def history(self, *args, **kwargs): ...
87
    def intraday(self, *args, **kwargs): ...
88
    def price_depth(self, *args, **kwargs): ...
89
```
90

91
[Quote Data](./quote-data.md)
92

93
### Company Information
94

95
Comprehensive company data including overview, shareholders, management, subsidiaries, affiliates, news, and corporate events.
96

97
```python { .api }
98
class Company:
99
    def __init__(self, source: str = "vci", symbol: str = None, random_agent: bool = False, show_log: bool = False): ...
100
    def overview(self, *args, **kwargs): ...
101
    def shareholders(self, *args, **kwargs): ...
102
    def officers(self, *args, **kwargs): ...
103
    def subsidiaries(self, *args, **kwargs): ...
104
    def affiliate(self, *args, **kwargs): ...
105
    def news(self, *args, **kwargs): ...
106
    def events(self, *args, **kwargs): ...
107
```
108

109
[Company Information](./company-info.md)
110

111
### Financial Statements
112

113
Financial reporting data including balance sheets, income statements, cash flow statements, and financial ratios with quarterly and annual reporting periods.
114

115
```python { .api }
116
class Finance:
117
    def __init__(self, source: str, symbol: str, period: str = "quarter", get_all: bool = True, show_log: bool = False): ...
118
    def balance_sheet(self, *args, **kwargs): ...
119
    def income_statement(self, *args, **kwargs): ...
120
    def cash_flow(self, *args, **kwargs): ...
121
    def ratio(self, *args, **kwargs): ...
122
```
123

124
[Financial Statements](./financial-statements.md)
125

126
### Market Listings
127

128
Securities listing data including symbol directories, industry classifications, exchange groupings, and various market segments.
129

130
```python { .api }
131
class Listing:
132
    def __init__(self, source: str = "vci", random_agent: bool = False, show_log: bool = False): ...
133
    def all_symbols(self, *args, **kwargs): ...
134
    def symbols_by_industries(self, *args, **kwargs): ...
135
    def symbols_by_exchange(self, *args, **kwargs): ...
136
    def industries_icb(self, *args, **kwargs): ...
137
    def symbols_by_group(self, *args, **kwargs): ...
138
    def all_future_indices(self, **kwargs): ...
139
    def all_government_bonds(self, **kwargs): ...
140
    def all_covered_warrant(self, **kwargs): ...
141
    def all_bonds(self, **kwargs): ...
142
```
143

144
[Market Listings](./market-listings.md)
145

146
### Trading Analytics
147

148
Market trading statistics, order book data, foreign and proprietary trading flows, insider transactions, and various trading-related metrics.
149

150
```python { .api }
151
class Trading:
152
    def __init__(self, source: str = "vci", symbol: str = "", random_agent: bool = False, show_log: bool = False): ...
153
    def trading_stats(self, *args, **kwargs): ...
154
    def side_stats(self, *args, **kwargs): ...
155
    def price_board(self, *args, **kwargs): ...
156
    def price_history(self, *args, **kwargs): ...
157
    def foreign_trade(self, *args, **kwargs): ...
158
    def prop_trade(self, *args, **kwargs): ...
159
    def insider_deal(self, *args, **kwargs): ...
160
    def order_stats(self, *args, **kwargs): ...
161
```
162

163
[Trading Analytics](./trading-analytics.md)
164

165
### Stock Screening
166

167
Advanced stock filtering and screening capabilities using TCBS data source with customizable parameters and criteria.
168

169
```python { .api }
170
class Screener:
171
    def __init__(self, source: str = "tcbs", random_agent: bool = False, show_log: bool = False): ...
172
    def stock(self, params: dict = None, limit: int = 50, id: str = None, lang: str = "vi"): ...
173
```
174

175
[Stock Screening](./stock-screening.md)
176

177
### Mutual Funds
178

179
Comprehensive mutual fund data including fund listings, portfolio holdings, NAV history, and asset allocation analysis.
180

181
```python { .api }
182
class Fund:
183
    def __init__(self, random_agent: bool = False) -> None: ...
184
    def listing(self, fund_type: str = ""): ...
185
    def filter(self, symbol: str = ""): ...
186
    def top_holding(self, fundId: int = 23): ...
187
    def industry_holding(self, fundId: int = 23): ...
188
    def nav_report(self, fundId: int = 23): ...
189
    def asset_holding(self, fundId: int = 23): ...
190
    
191
    # Instance attributes
192
    fund_list: list
193
    details: FundDetails
194
```
195

196
[Mutual Funds](./mutual-funds.md)
197

198
### Data Visualization
199

200
Integrated charting and visualization capabilities supporting multiple chart types with pandas DataFrame integration.
201

202
```python { .api }
203
# chart_wrapper is an alias for the Chart class
204
chart_wrapper = Chart
205

206
class Chart:
207
    def __init__(self, data: Union[pd.DataFrame, pd.Series]): ...
208
    def help(self, func_name: str): ...
209
    def bar(self, **kwargs): ...
210
    def hist(self, **kwargs): ...
211
    def pie(self, labels=None, values=None, **kwargs): ...
212
    def timeseries(self, **kwargs): ...
213
    def heatmap(self, **kwargs): ...
214
    def scatter(self, x: str, y: str, **kwargs): ...
215
    def treemap(self, values, labels, **kwargs): ...
216
    def boxplot(self, **kwargs): ...
217
    def pairplot(self, **kwargs): ...
218
    def wordcloud(self, show_log=False, **kwargs): ...
219
    def table(self, **kwargs): ...
220
    def combo(self, bar_data, line_data, **kwargs): ...
221
```
222

223
[Data Visualization](./data-visualization.md)
224

225
## Types
226

227
### Common Data Types
228

229
```python { .api }
230
from typing import Optional, Union, Any, Dict, List
231
import pandas as pd
232

233
# Main component return types
234
StockComponents = object  # Contains quote, company, finance components
235
MSNComponents = object    # Contains MSN-specific data components
236
```
237

238
### Data Source Constants
239

240
```python { .api }
241
# Supported data sources by component
242
VNSTOCK_SOURCES = ["VCI", "TCBS", "MSN"]
243
QUOTE_SOURCES = ["VCI", "TCBS", "MSN"] 
244
COMPANY_SOURCES = ["VCI", "TCBS"]
245
FINANCE_SOURCES = ["VCI", "TCBS"]
246
LISTING_SOURCES = ["VCI", "MSN"]
247
TRADING_SOURCES = ["VCI", "TCBS"]
248
SCREENER_SOURCES = ["TCBS"]
249
FUND_SOURCES = ["FMARKET"]
250

251
# MSN symbol mappings
252
CURRENCY_PAIRS = ["USDVND", "EURUSD", "GBPUSD", ...]  # 38+ currency pairs
253
CRYPTO_SYMBOLS = ["BTC", "ETH", "BNB", ...]           # 10 crypto symbols  
254
GLOBAL_INDICES = ["DJI", "SPX", "IXIC", ...]          # 19 global indices
255
```
256

257
### Configuration
258

259
```python { .api }
260
# Retry and timeout configuration
261
RETRIES = 3
262
REQUEST_TIMEOUT = 30
263
CACHE_SIZE = 128
264
```