0
# Main Client Interface
1

2
The Vnstock class is the primary entry point for accessing Vietnamese financial market data. It provides a unified interface to create specialized component objects for different asset types and data sources.
3

4
## Capabilities
5

6
### Vnstock Class
7

8
Central orchestrator that returns specialized component objects for accessing different types of financial data. Supports multiple data sources with automatic provider selection and validation.
9

10
```python { .api }
11
class Vnstock:
12
    """
13
    Main VNStock client for accessing Vietnamese financial market data.
14
    
15
    Attributes:
16
        SUPPORTED_SOURCES (list): Available data sources ["VCI", "TCBS", "MSN"]
17
        msn_symbol_map (dict): Symbol mappings for MSN data source
18
    """
19
    
20
    def __init__(self, symbol: str = None, source: str = "VCI", show_log: bool = True):
21
        """
22
        Initialize VNStock client.
23
        
24
        Args:
25
            symbol (str, optional): Default symbol for operations
26
            source (str): Default data source, defaults to "VCI"
27
            show_log (bool): Enable logging, defaults to True
28
        """
29
```
30

31
### Stock Market Data
32

33
Access Vietnamese stock market data including individual stocks and market indices.
34

35
```python { .api }
36
def stock(self, symbol: Optional[str] = None, source: Optional[str] = None) -> StockComponents:
37
    """
38
    Get stock market data components.
39
    
40
    Args:
41
        symbol (str, optional): Stock symbol (e.g., "TCB", "VCB")
42
        source (str, optional): Data source ("VCI", "TCBS", "MSN")
43
        
44
    Returns:
45
        StockComponents: Object containing quote, company, finance components
46
    """
47
```
48

49
#### Usage Example
50

51
```python
52
import vnstock
53
from vnstock import Vnstock
54

55
# Initialize client
56
stock = Vnstock()
57

58
# Get stock components for TCB
59
tcb = stock.stock(symbol="TCB", source="VCI")
60

61
# Access different data types
62
price_data = tcb.quote.history(start="2023-01-01", end="2023-12-31")
63
company_info = tcb.company.overview()
64
financials = tcb.finance.balance_sheet(period="quarter")
65
```
66

67
### Foreign Exchange Data
68

69
Access global foreign exchange data through MSN data source.
70

71
```python { .api }
72
def fx(self, symbol: Optional[str] = 'EURUSD', source: Optional[str] = "MSN") -> MSNComponents:
73
    """
74
    Get foreign exchange data components.
75
    
76
    Args:
77
        symbol (str): Currency pair symbol, defaults to "EURUSD"
78
        source (str): Data source, defaults to "MSN"
79
        
80
    Returns:
81
        MSNComponents: Object containing FX data components
82
    """
83
```
84

85
#### Supported Currency Pairs
86

87
- Major pairs: EURUSD, GBPUSD, USDJPY, USDCHF, USDCAD, AUDUSD, NZDUSD
88
- Vietnamese Dong: USDVND, EURVND, GBPVND, JPYVND
89
- Asian currencies: USDKRW, USDSGD, USDTHB, USDMYR, USDIDR
90
- And 25+ additional currency pairs
91

92
#### Usage Example
93

94
```python
95
# Get EUR/USD data
96
eurusd = stock.fx(symbol="EURUSD")
97
fx_history = eurusd.quote.history(start="2023-01-01", end="2023-12-31")
98

99
# Get USD/VND data  
100
usdvnd = stock.fx(symbol="USDVND")
101
vnd_data = usdvnd.quote.history()
102
```
103

104
### Cryptocurrency Data
105

106
Access cryptocurrency data through MSN data source.
107

108
```python { .api }
109
def crypto(self, symbol: Optional[str] = 'BTC', source: Optional[str] = "MSN") -> MSNComponents:
110
    """
111
    Get cryptocurrency data components.
112
    
113
    Args:
114
        symbol (str): Crypto symbol, defaults to "BTC"
115
        source (str): Data source, defaults to "MSN"
116
        
117
    Returns:
118
        MSNComponents: Object containing crypto data components
119
    """
120
```
121

122
#### Supported Cryptocurrencies
123

124
- BTC (Bitcoin), ETH (Ethereum), BNB (Binance Coin)
125
- ADA (Cardano), XRP (Ripple), SOL (Solana)
126
- DOT (Polkadot), AVAX (Avalanche), MATIC (Polygon)
127
- LINK (Chainlink)
128

129
#### Usage Example
130

131
```python
132
# Get Bitcoin data
133
btc = stock.crypto(symbol="BTC")
134
btc_history = btc.quote.history(start="2023-01-01", end="2023-12-31")
135

136
# Get Ethereum data
137
eth = stock.crypto(symbol="ETH")
138
eth_data = eth.quote.history()
139
```
140

141
### Global Stock Indices
142

143
Access global stock market indices through MSN data source.
144

145
```python { .api }
146
def world_index(self, symbol: Optional[str] = 'DJI', source: Optional[str] = "MSN") -> MSNComponents:
147
    """
148
    Get global stock index data components.
149
    
150
    Args:
151
        symbol (str): Index symbol, defaults to "DJI" (Dow Jones)
152
        source (str): Data source, defaults to "MSN"
153
        
154
    Returns:
155
        MSNComponents: Object containing index data components  
156
    """
157
```
158

159
#### Supported Global Indices
160

161
- US Indices: DJI (Dow Jones), SPX (S&P 500), IXIC (NASDAQ), RUT (Russell 2000)
162
- European: UKX (FTSE 100), DAX (DAX), CAC (CAC 40), AEX (AEX)
163
- Asian: N225 (Nikkei 225), HSI (Hang Seng), SHCOMP (Shanghai Composite)
164
- Others: IBOV (Bovespa), MXX (IPC Mexico), SENSEX (BSE Sensex)
165
- And additional regional indices
166

167
#### Usage Example
168

169
```python
170
# Get S&P 500 data
171
sp500 = stock.world_index(symbol="SPX")
172
sp500_history = sp500.quote.history(start="2023-01-01", end="2023-12-31")
173

174
# Get Nikkei 225 data
175
nikkei = stock.world_index(symbol="N225")
176
nikkei_data = nikkei.quote.history()
177
```
178

179
### Mutual Fund Data
180

181
Access Vietnamese mutual fund data through specialized Fund component.
182

183
```python { .api }
184
def fund(self, source: Optional[str] = "FMARKET") -> Fund:
185
    """
186
    Get mutual fund data components.
187
    
188
    Args:
189
        source (str): Data source, defaults to "FMARKET"
190
        
191
    Returns:
192
        Fund: Fund data component with listing and analysis capabilities
193
    """
194
```
195

196
#### Usage Example
197

198
```python
199
# Get fund component
200
funds = stock.fund()
201

202
# List all available funds
203
all_funds = funds.listing()
204

205
# Get specific fund details
206
fund_holdings = funds.top_holding(fundId=23)
207
fund_nav = funds.nav_report(fundId=23)
208
```
209

210
## Data Source Information
211

212
### VCI (Vietnam Capital Securities)
213
- **Coverage**: Vietnamese stocks, derivatives, bonds
214
- **Data Types**: Quote, company, finance, listing, trading
215
- **Update Frequency**: Real-time and end-of-day
216

217
### TCBS (Techcombank Securities)  
218
- **Coverage**: Vietnamese stocks, screening
219
- **Data Types**: Quote, company, finance, trading, screener
220
- **Update Frequency**: Real-time and end-of-day
221

222
### MSN (Microsoft Network)
223
- **Coverage**: Global financial data
224
- **Data Types**: Forex, cryptocurrency, global indices
225
- **Update Frequency**: Real-time
226

227
### FMARKET
228
- **Coverage**: Vietnamese mutual funds
229
- **Data Types**: Fund listings, NAV, holdings, performance
230
- **Update Frequency**: Daily