quantvn 0.1.24__tar.gz → 0.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (53) hide show
  1. {quantvn-0.1.24/quantvn.egg-info → quantvn-0.2.0}/PKG-INFO +1047 -926
  2. {quantvn-0.1.24 → quantvn-0.2.0}/README.md +117 -0
  3. {quantvn-0.1.24 → quantvn-0.2.0}/quantvn/crypto/data/derivatives.py +85 -85
  4. {quantvn-0.1.24 → quantvn-0.2.0}/quantvn/crypto/metrics/backtest.py +12 -8
  5. quantvn-0.2.0/quantvn/metrics/_fills.py +66 -0
  6. {quantvn-0.1.24 → quantvn-0.2.0}/quantvn/metrics/single_asset.py +6 -3
  7. {quantvn-0.1.24 → quantvn-0.2.0}/quantvn/metrics/st.py +568 -568
  8. quantvn-0.2.0/quantvn/paper/__init__.py +5 -0
  9. quantvn-0.2.0/quantvn/paper/client.py +103 -0
  10. quantvn-0.2.0/quantvn/paper/single_asset.py +110 -0
  11. quantvn-0.2.0/quantvn/strategy/__init__.py +21 -0
  12. quantvn-0.2.0/quantvn/strategy/frames.py +104 -0
  13. quantvn-0.2.0/quantvn/strategy/harness.py +170 -0
  14. quantvn-0.2.0/quantvn/strategy/script.py +140 -0
  15. {quantvn-0.1.24 → quantvn-0.2.0}/quantvn/us/__init__.py +1 -1
  16. {quantvn-0.1.24 → quantvn-0.2.0}/quantvn/us/data/__init__.py +5 -5
  17. {quantvn-0.1.24 → quantvn-0.2.0}/quantvn/us/data/stocks.py +60 -60
  18. {quantvn-0.1.24 → quantvn-0.2.0}/quantvn/us/metrics/__init__.py +3 -3
  19. {quantvn-0.1.24 → quantvn-0.2.0}/quantvn/us/metrics/backtest.py +254 -252
  20. {quantvn-0.1.24 → quantvn-0.2.0}/quantvn/vn/data/__init__.py +149 -149
  21. {quantvn-0.1.24 → quantvn-0.2.0}/quantvn/vn/data/core.py +1214 -1197
  22. {quantvn-0.1.24 → quantvn-0.2.0}/quantvn/vn/data/derivatives.py +1 -0
  23. {quantvn-0.1.24 → quantvn-0.2.0}/quantvn/vn/data/macro.py +413 -405
  24. {quantvn-0.1.24 → quantvn-0.2.0}/quantvn/vn/data/stocks.py +2413 -2358
  25. {quantvn-0.1.24 → quantvn-0.2.0}/quantvn/vn/data/utils.py +65 -65
  26. {quantvn-0.1.24 → quantvn-0.2.0}/quantvn/vn/metrics/backtest.py +31 -26
  27. {quantvn-0.1.24 → quantvn-0.2.0/quantvn.egg-info}/PKG-INFO +1047 -926
  28. {quantvn-0.1.24 → quantvn-0.2.0}/quantvn.egg-info/SOURCES.txt +10 -1
  29. {quantvn-0.1.24 → quantvn-0.2.0}/quantvn.egg-info/requires.txt +4 -0
  30. {quantvn-0.1.24 → quantvn-0.2.0}/setup.cfg +4 -4
  31. {quantvn-0.1.24 → quantvn-0.2.0}/setup.py +31 -29
  32. quantvn-0.2.0/tests/test_backtests.py +109 -0
  33. quantvn-0.2.0/tests/test_paper.py +91 -0
  34. quantvn-0.2.0/tests/test_strategy.py +131 -0
  35. quantvn-0.1.24/quantvn/paper/__init__.py +0 -0
  36. quantvn-0.1.24/quantvn/paper/single_asset.py +0 -0
  37. {quantvn-0.1.24 → quantvn-0.2.0}/LICENSE +0 -0
  38. {quantvn-0.1.24 → quantvn-0.2.0}/MANIFEST.in +0 -0
  39. {quantvn-0.1.24 → quantvn-0.2.0}/quantvn/__init__.py +0 -0
  40. {quantvn-0.1.24 → quantvn-0.2.0}/quantvn/crypto/__init__.py +0 -0
  41. {quantvn-0.1.24 → quantvn-0.2.0}/quantvn/crypto/data/__init__.py +0 -0
  42. {quantvn-0.1.24 → quantvn-0.2.0}/quantvn/crypto/data/download.py +0 -0
  43. {quantvn-0.1.24 → quantvn-0.2.0}/quantvn/crypto/metrics/__init__.py +0 -0
  44. {quantvn-0.1.24 → quantvn-0.2.0}/quantvn/crypto/metrics/metrics.py +0 -0
  45. {quantvn-0.1.24 → quantvn-0.2.0}/quantvn/metrics/__init__.py +0 -0
  46. {quantvn-0.1.24 → quantvn-0.2.0}/quantvn/metrics/portfolio.py +0 -0
  47. {quantvn-0.1.24 → quantvn-0.2.0}/quantvn/paper/portfolio.py +0 -0
  48. {quantvn-0.1.24 → quantvn-0.2.0}/quantvn/vn/__init__.py +0 -0
  49. {quantvn-0.1.24 → quantvn-0.2.0}/quantvn/vn/data/const.py +0 -0
  50. {quantvn-0.1.24 → quantvn-0.2.0}/quantvn/vn/metrics/__init__.py +0 -0
  51. {quantvn-0.1.24 → quantvn-0.2.0}/quantvn/vn/metrics/metrics.py +0 -0
  52. {quantvn-0.1.24 → quantvn-0.2.0}/quantvn.egg-info/dependency_links.txt +0 -0
  53. {quantvn-0.1.24 → quantvn-0.2.0}/quantvn.egg-info/top_level.txt +0 -0
@@ -1,926 +1,1047 @@
1
- Metadata-Version: 2.4
2
- Name: quantvn
3
- Version: 0.1.24
4
- Summary: QuantVN API Library for Financial Data Analysis
5
- Author: quantvn
6
- Classifier: Development Status :: 3 - Alpha
7
- Classifier: Intended Audience :: Developers
8
- Classifier: Programming Language :: Python :: 3.9
9
- Classifier: Programming Language :: Python :: 3.10
10
- Classifier: Programming Language :: Python :: 3.11
11
- Classifier: Programming Language :: Python :: 3.12
12
- Classifier: Programming Language :: Python :: 3.13
13
- Requires-Python: >=3.9
14
- Description-Content-Type: text/markdown
15
- License-File: LICENSE
16
- Requires-Dist: requests
17
- Requires-Dist: pandas
18
- Requires-Dist: matplotlib
19
- Requires-Dist: tqdm
20
- Requires-Dist: ta
21
- Requires-Dist: pyarrow
22
- Dynamic: author
23
- Dynamic: classifier
24
- Dynamic: description
25
- Dynamic: description-content-type
26
- Dynamic: license-file
27
- Dynamic: requires-dist
28
- Dynamic: requires-python
29
- Dynamic: summary
30
-
31
- # QuantVN - Python Library for Vietnamese Financial Market Analysis
32
-
33
- **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.
34
-
35
- ## Tính năng nổi bật
36
-
37
- **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.
38
-
39
- **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.
40
-
41
- **Dữ liệu thị trường**:
42
-
43
- - Cổ phiếu Việt Nam (HOSE, HNX, UPCOM)
44
- - Phái sinh VN30
45
-
46
- **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.
47
-
48
- ## Quy trình QuantVN
49
-
50
- Để xây dựng một hệ thống giao dịch thành công, QuantVN vận hành theo một quy trình 4 bước khép kín và logic.
51
-
52
- ![image](https://res.cloudinary.com/dbn4eimis/image/upload/v1773975369/image_1_pxtcuk.png)
53
-
54
- ## Cài đặt
55
-
56
- ### Từ PyPI (khuyến nghị)
57
-
58
- ```bash
59
- pip install quantvn
60
- ```
61
-
62
- ### Từ mã nguồn
63
-
64
- ```bash
65
- git clone https://github.com/your-repo/quantvn.git
66
- cd quantvn
67
- pip install -e .
68
- ```
69
-
70
- ### Yêu cầu hệ thống
71
-
72
- - Python >= 3.9
73
- - pandas
74
- - requests
75
- - matplotlib
76
- - tqdm
77
-
78
- ## Bắt đầu nhanh
79
-
80
- ### Khởi tạo API Client
81
-
82
- Để sử dụng các tính năng của QuantVN , người dùng cần cung cấp API Key được cấp từ nền tảng **QuantVN** | https://quantvn.com/.
83
-
84
- ![image](https://res.cloudinary.com/dbn4eimis/image/upload/v1773975781/Gemini_Generated_Image_r5fls6r5fls6r5fl_ktk5hx.png)
85
-
86
- <p align="center">
87
- <a href="https://quantvn.com/">
88
- <img src="https://img.shields.io/badge/🌐 Visit Website-QuantVN-blue?style=for-the-badge" />
89
- </a>
90
- </p>
91
-
92
- API Key được sử dụng để xác thực các yêu cầu tới hệ thống dữ liệu của QuantVN, giúp kiểm soát truy cập, đảm bảo tính ổn định của dịch vụ và theo dõi mức sử dụng.
93
-
94
- ```python
95
- from quantvn.vn.data.utils import client
96
-
97
- # Khởi tạo với API key (nếu có)
98
- client(apikey="your_api_key_here")
99
- ```
100
-
101
- **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 đủ.
102
-
103
- ### Các bước để lấy API Key
104
-
105
- #### Bước 1: Truy cập website
106
-
107
- Truy cập vào website chính thức:
108
-
109
- https://quantvn.com/
110
-
111
- Tại trang chủ, nhấn vào nút **"Tham gia ngay"** để bắt đầu.
112
-
113
- ![image](https://res.cloudinary.com/dbn4eimis/image/upload/v1773988068/1_u0wfbq.png)
114
-
115
- #### Bước 2: Đăng nhập hoặc đăng ký tài khoản
116
-
117
- Nếu bạn đã có tài khoản:
118
-
119
- - Nhập thông tin đăng nhập để truy cập hệ thống.
120
- - Hoặc đăng nhập nhanh bằng Google
121
-
122
- Nếu bạn chưa có tài khoản:
123
-
124
- - Đăng ký tài khoản mới bằng email
125
- - Hoặc đăng ký nhanh bằng Google
126
-
127
- ![image](https://res.cloudinary.com/dbn4eimis/image/upload/v1773988068/2_jsniro.png)
128
-
129
- #### Bước 3: Truy cập mục Hồ sơ & API Keys
130
-
131
- Sau khi đăng nhập thành công:
132
-
133
- - Nhấn vào **hình đại diện hồ sơ** ở góc trên cùng bên trái
134
- - Một menu sẽ hiển thị
135
- - Chọn mục **"Hồ sơ & API keys"**
136
-
137
- ![image](https://res.cloudinary.com/dbn4eimis/image/upload/v1773989364/hihi_kwft6d.jpg)
138
-
139
- #### Bước 4: Lấy API Key
140
-
141
- Trong trang Hồ sơ & API Keys:
142
-
143
- - Nhấn vào mục **"Cài đặt"**
144
- - Tại đây bạn sẽ thấy API Key của mình
145
-
146
- Bạn có thể:
147
-
148
- - Nhấn **"Xem Key"** để hiển thị API Key và copy để sử dụng
149
- - Hoặc nhấn **"Tạo API Key mới"** để tạo key mới
150
-
151
- ![image](https://res.cloudinary.com/dbn4eimis/image/upload/v1773990774/hihhihihihii_qnbnrk.jpg)
152
-
153
- #### Lưu ý
154
-
155
- - Không chia sẻ API Key với người khác
156
- - API Key được sử dụng để xác thực khi sử dụng thư viện QuantVN
157
-
158
- ---
159
-
160
- ## Tài liệu API
161
-
162
- ### 1. Dữ liệu Cổ phiếu Việt Nam
163
-
164
- Module: `quantvn.vn.data`
165
-
166
- #### 1.1. Danh sách cổ phiếu thanh khoản cao
167
-
168
- ```python
169
- from quantvn import client
170
- client(apikey="your_api_key_here")
171
-
172
- from quantvn.vn.data import list_liquid_asset
173
-
174
- # Lấy danh sách cổ phiếu có thanh khoản cao
175
- liquid_stocks = list_liquid_asset()
176
- print(liquid_stocks.head())
177
- ```
178
-
179
- **Output:**
180
-
181
- ```python
182
- symbol liquidity
183
- 0 VCB 5.234567e+10
184
- 1 HPG 4.123456e+10
185
- 2 VIC 3.876543e+10
186
- ```
187
-
188
- #### 1.2. Dữ liệu lịch sử cổ phiếu
189
-
190
- ```python
191
- from quantvn.vn.data import get_stock_hist
192
-
193
- # Lấy dữ liệu 1H (ví dụ sử dụng khung giờ 1H)
194
- vic_hour = get_stock_hist("VIC", resolution="1H")
195
- print(vic_hour.head())
196
- ```
197
-
198
- **Tham số:**
199
-
200
- - `symbol` (str): Mã cổ phiếu (VD: "VIC", "HPG", "VCB")
201
- - `resolution` (str): Khung thời gian, hiện chỉ hỗ trợ `"1H"` (bắt buộc).
202
-
203
- **Output:**
204
-
205
- ```python
206
- Date time Open High Low Close volume
207
- 0 2024-01-02 09:00:00 42.50 42.80 42.30 42.60 1234567.0
208
- 1 2024-01-02 10:00:00 42.60 42.90 42.50 42.75 2345678.0
209
- ```
210
-
211
- #### 1.3. Thông tin chi tiết công ty
212
-
213
- ```python
214
- from quantvn import client
215
- client(apikey="your_api_key_here")
216
-
217
- from quantvn.vn.data import Company
218
-
219
- company = Company("VIC")
220
-
221
- # Thông tin tổng quan
222
- overview = company.overview()
223
- print("Thông tin tổng quan")
224
- print(overview[["symbol", "id", "issue_share", "icb_name2", "icb_name4"]])
225
-
226
- # Danh sách cổ đông
227
- shareholders = company.shareholders()
228
- print("Danh sách cổ đông")
229
- print(shareholders.head())
230
-
231
- # Ban lãnh đạo
232
- officers = company.officers()
233
- print("Ban lãnh đạo")
234
- print(officers.head())
235
-
236
- # Công ty con
237
- subsidiaries = company.subsidiaries()
238
- print("Công ty con")
239
- print(subsidiaries.head())
240
-
241
- # Sự kiện quan trọng
242
- events = company.events()
243
- print("Sự kiện quan trọng")
244
- print(events.head())
245
-
246
- # Tin tức
247
- news = company.news()
248
- print("Tin tức")
249
- print(news.head())
250
-
251
- # Tỷ số tài chính tổng hợp
252
- ratios = company.ratio_summary()
253
- print("Tỷ số tài chính tổng hợp")
254
- print(ratios[["pe", "pb", "roe", "roa"]])
255
- ```
256
-
257
- **Output:**
258
-
259
- ```python
260
- Thông tin tổng quan
261
- symbol id issue_share icb_name2 icb_name4
262
- 0 VIC 76055 7706031024 Bất động sản Bất động sản
263
-
264
- Danh sách cổ đông
265
- id ticker ... updateDate __typename
266
- 0 100950872 VIC ... 1770048564380 OrganizationShareHolders
267
- 1 100950031 VIC ... 1767201363047 OrganizationShareHolders
268
- 2 100971726 VIC ... 1767201489503 OrganizationShareHolders
269
- 3 100972520 VIC ... 1770048733047 OrganizationShareHolders
270
- 4 100950463 VIC ... 1770048609397 OrganizationShareHolders
271
-
272
- Ban lãnh đạo
273
- id ticker fullName ... percentage quantity __typename
274
- 0 19 VIC Phạm Nhật Vượng ... 0.091010 703848781 OrganizationManager
275
- 1 5 VIC Phạm Thu Hương ... 0.044280 341221050 OrganizationManager
276
- 2 6 VIC Phạm Thúy Hằng ... 0.029630 228326892 OrganizationManager
277
- 3 4 VIC Phạm Văn Khương ... 0.000600 2267587 OrganizationManager
278
- 4 18 VIC Nguyễn Diệu Linh ... 0.000242 1865418 OrganizationManager
279
-
280
- Công ty con
281
- id organCode subOrganCode percentage subOrListingInfo __typename
282
- 0 28590324 VIC 0110006565 0.6142 {'enOrganName': 'VS Development Investment Joi... Subsidiary
283
- 1 28590325 VIC 0110009975 NaN {'enOrganName': 'Vincom Retail Investment Join... Subsidiary
284
- 2 28590326 VIC 0110537975 0.6581 {'enOrganName': 'SV Tay Hanoi Real Estate Join... Subsidiary
285
- 3 28590327 VIC 0110873550 0.7339 {'enOrganName': 'Vinhomes Ha Tinh Industrial Z... Subsidiary
286
- 4 28590328 VIC 0110873568 0.7305 {'enOrganName': 'Vinhomes Hai Phong Industrial... Subsidiary
287
-
288
- Sự kiện quan trọng
289
- id organCode ticker eventTitle ... exrightDate eventListName en_EventListName __typename
290
- 0 34642 VIC VIC Niêm yết thêm ... -6847804800000 Niêm yết thêm Additional Listing OrganizationEvent
291
- 1 34686 VIC VIC Niêm yết thêm ... -6847804800000 Niêm yết thêm Additional Listing OrganizationEvent
292
- 2 34687 VIC VIC Niêm yết thêm ... -6847804800000 Niêm yết thêm Additional Listing OrganizationEvent
293
- 3 34702 VIC VIC VIC-Niêm yết bổ sung 484.473.162 cổ phiếu ... -6847804800000 Niêm yết thêm Additional Listing OrganizationEvent
294
- 4 34657 VIC VIC Niêm yết thêm ... -6847804800000 Niêm yết thêm Additional Listing OrganizationEvent
295
-
296
- Tin tức
297
- id organCode ticker newsTitle newsSubTitle ... referencePrice floorPrice ceilingPrice percentPriceChange __typename
298
- 0 9588803 VIC VIC VIC: Nghị quyết HĐQT về việc niêm yết trái phi... ... 145000.0 134900.0 155100.0 -0.002759 News
299
- 1 9559000 VIC VIC VIC: Thông báo giao dịch cổ phiếu của tổ chức ... ... 141800.0 131900.0 151700.0 0.029619 News
300
- 2 9515973 VIC VIC VIC: Thông báo về ngày đăng ký cuối cùng để th... ... 164800.0 153300.0 176300.0 -0.050364 News
301
- 3 9479016 VIC VIC VIC: Quyết định về việc chốt danh sách người s... ... 168900.0 157100.0 180700.0 0.018354 News
302
- 4 9469700 VIC VIC VIC: CBTT phát hành trái phiếu quốc tế ... 168900.0 157100.0 180700.0 0.018354 News
303
-
304
- Tỷ số tài chính tổng hợp
305
- pe pb roe roa
306
- 0 83.96933 7.596341 0.09402 0.013734
307
- ```
308
-
309
- #### 1.4. Tỷ số tài chính
310
-
311
- ```python
312
- from quantvn import client
313
- client(apikey="your-apikey-here")
314
-
315
- from quantvn.vn.data import Finance
316
-
317
- # Khởi tạo Finance (dùng BACKEND mặc định)
318
- finance = Finance("HPG")
319
-
320
- # Tỷ số tài chính theo quý
321
- ratios_q = finance.ratio(period="Q")
322
- print("Tỷ số tài chính theo quý:")
323
- if not ratios_q.empty:
324
- print(ratios_q[["year", "quarter", "revenue", "netProfit", "roe", "pe", "pb"]].head())
325
-
326
- # Tỷ số tài chính theo năm
327
- ratios_y = finance.ratio(period="Y")
328
- print("\nTỷ số tài chính theo năm:")
329
- if not ratios_y.empty:
330
- print(ratios_y[["year", "revenue", "netProfit", "roe", "pe", "pb"]].head())
331
- ```
332
-
333
- **Output:**
334
-
335
- ```python
336
- Tỷ số tài chính theo quý:
337
- year year quarter quarter revenue netProfit roe pe pb
338
- 0 2025 2025 4 4 47301623136340 3860994446656 0.126882 13.314004 1.592397
339
- 1 2025 2025 3 3 36793873449413 3988318474539 0.120224 14.527037 1.667413
340
- 2 2025 2025 2 2 36286185846409 4256487211764 0.115502 16.199640 1.790441
341
- 3 2025 2025 1 1 37950635502050 3344284694388 0.110522 15.817610 1.679199
342
- 4 2024 2024 4 4 35232197602514 2808645369171 0.110732 13.754011 1.445857
343
-
344
- Tỷ số tài chính theo năm:
345
- year year revenue netProfit roe pe pb
346
- 0 2025 2025 158332317934212 15450084827347 0.126882 13.314004 1.592397
347
- 1 2024 2024 140561387448572 12021443836074 0.110732 14.344970 1.476620
348
- 2 2023 2023 120355231616139 6835064334356 0.068771 23.858738 1.507863
349
- 3 2022 2022 142770810676858 8483510554031 0.090911 19.253321 1.692821
350
- 4 2021 2021 150865359967200 34478143197460 0.459707 2.407519 0.888407
351
- ```
352
-
353
- **Tham số:**
354
-
355
- - `period` (str): `"Q"` (quý) hoặc `"Y"` (năm)
356
- - `dropna` (bool): Loại bỏ các giá trị null (mặc định: `False`)
357
-
358
- #### 1.5. Dữ liệu Quote realtime
359
-
360
- ```python
361
- from quantvn.vn.data import Quote
362
-
363
- quote = Quote("ACB")
364
-
365
- # Lấy dữ liệu lịch sử trong khoảng thời gian
366
- history = quote.history(
367
- start="2024-01-01",
368
- end="2024-03-31",
369
- interval="1D"
370
- )
371
- print("Dữ liệu lịch sử trong khoảng thời gian")
372
- print(history.head())
373
-
374
- # Dữ liệu tick intraday
375
- intraday = quote.intraday(page_size=200)
376
- print("Dữ liệu tick intraday")
377
- print(intraday.head())
378
-
379
- # Độ sâu thị trường (price depth)
380
- depth = quote.price_depth()
381
- print("Độ sâu thị trường (price depth)")
382
- print(depth.head())
383
- ```
384
-
385
- **Output:**
386
-
387
- ```python
388
- Dữ liệu lịch sử trong khoảng thời gian
389
- time open high low close volume
390
- 0 2024-01-02 16808.59 17370.04 16808.59 17159.50 13896933
391
- 1 2024-01-03 17194.59 17545.50 17019.13 17545.50 9817807
392
- 2 2024-01-04 17685.86 18001.68 17615.68 17756.05 23605373
393
- 3 2024-01-05 17756.05 17861.32 17580.59 17861.32 9282598
394
- 4 2024-01-08 18036.77 18071.87 17685.86 17791.14 12398885
395
-
396
- Dữ liệu tick intraday
397
- time price volume match_type id
398
- 0 2026-03-19 06:26:22 23300.0 1300.0 s 452011243
399
- 1 2026-03-19 06:26:22 23300.0 200.0 s 452011242
400
- 2 2026-03-19 06:26:22 23300.0 100.0 s 452011241
401
- 3 2026-03-19 06:26:22 23300.0 400.0 s 452011240
402
- 4 2026-03-19 06:26:21 23350.0 100.0 b 452011220
403
-
404
- Độ sâu thị trường (price depth)
405
- price acc_volume acc_buy_volume acc_sell_volume acc_undefined_volume
406
- 0 23550.0 32800.0 21300.0 11500.0 0.0
407
- 1 23500.0 627100.0 357900.0 7400.0 261800.0
408
- 2 23450.0 2006100.0 1413700.0 592400.0 0.0
409
- 3 23400.0 1724200.0 655300.0 1068900.0 0.0
410
- 4 23350.0 1214700.0 569600.0 645100.0 0.0
411
- ```
412
-
413
- #### 1.6. Thông tin giao dịch
414
-
415
- ```python
416
- from quantvn.vn.data import Trading
417
-
418
- # Bảng giá nhiều mã cùng lúc
419
- price_board = Trading.price_board(["VCB", "ACB", "TCB"])
420
- print(price_board)
421
- ```
422
-
423
- **Output:**
424
-
425
- ```python
426
- symbol open ceiling floor ref_price high low price_change price_change_pct foreign_volume foreign_room foreign_holding_room avg_match_volume_2w
427
- 0 VCB None None None 60500.0 None None -1400.0 -2.314050 None None None None
428
- 1 ACB None None None 23750.0 None None -450.0 -1.894737 None None None None
429
- 2 TCB None None None 30300.0 None None -350.0 -1.155116 None None None None
430
- ```
431
-
432
- #### 1.7. Quỹ mở
433
-
434
- ```python
435
- from quantvn.vn.data import Fund
436
-
437
- fund = Fund()
438
-
439
- # Danh sách tất cả quỹ
440
- all_funds = fund.listing()
441
- print("Danh sách tất cả quỹ")
442
- print(all_funds.head())
443
-
444
- # Lọc theo loại quỹ
445
- stock_funds = fund.listing(fund_type="STOCK") # Quỹ cổ phiếu
446
- bond_funds = fund.listing(fund_type="BOND") # Quỹ trái phiếu
447
- balanced_funds = fund.listing(fund_type="BALANCED") # Quỹ cân bằng
448
-
449
- print("Quỹ cổ phiếu:")
450
- print(stock_funds[["name", "code", "nav"]].head())
451
-
452
- # Tìm kiếm quỹ theo tên
453
- search_result = fund.filter("RVPIF")
454
- print("Tìm kiếm quỹ theo tên")
455
- print(search_result)
456
- ```
457
-
458
- **Output:**
459
-
460
- ```python
461
- Danh sách tất cả quỹ
462
- id name shortName code ... productNavChange.updateAt extra.lastNAVDate extra.lastNAV extra.currentNAV
463
- 0 38 QUỸ ĐẦU TƯ CHỦ ĐỘNG VND VNDAF VNDAF ... 1773901367003 1773853200000 19974.77 19974.77
464
- 1 80 QUỸ ĐẦU TƯ CỔ PHIẾU CỔ TỨC NĂNG ĐỘNG VINACAPITAL VDEF VDEF ... 1773894131379 1773766800000 12475.45 12475.45
465
- 2 21 QUỸ ĐẦU TƯ TRÁI PHIẾU BẢO THỊNH VINACAPITAL VFF VFF ... 1773894123666 1773680400000 25857.51 25857.51
466
- 3 37 QUỸ ĐẦU TƯ TRÁI PHIẾU VND VNDBF VNDBF ... 1773894901858 1773853200000 15770.78 15770.78
467
- 4 41 QUỸ ĐẦU TƯ CỔ PHIẾU TĂNG TRƯỞNG BALLAD VIỆT NAM TBLF TBLF ... 1773894127776 1773680400000 11281.69 11281.69
468
-
469
- Quỹ cổ phiếu:
470
- name code nav
471
- 0 QUỸ ĐẦU TƯ CHỦ ĐỘNG VND VNDAF 19974.77
472
- 1 QUỸ ĐẦU TƯ CỔ PHIẾU CỔ TỨC NĂNG ĐỘNG VINACAPITAL VDEF 12475.45
473
- 2 QUỸ ĐẦU TƯ CỔ PHIẾU TĂNG TRƯỞNG BALLAD VIỆT NAM TBLF 11281.69
474
- 3 QUỸ ĐẦU TƯ CỔ PHIẾU TĂNG TRƯỞNG MIRAE ASSET VI... MAGEF 21768.81
475
- 4 QUỸ ĐẦU TƯ THU NHẬP CHỦ ĐỘNG VCBF VCBFAIF 11613.50
476
-
477
- Tìm kiếm quỹ theo tên
478
- id name shortName code ... productNavChange.updateAt extra.lastNAVDate extra.lastNAV extra.currentNAV
479
- 55 83 QUỸ ĐẦU TƯ THỊNH VƯỢNG RỒNG VIỆT RVPIF RVPF24 ... 1773894120943 1773766800000 10881.64 10881.64
480
- ```
481
-
482
- #### 1.8. Danh sách mã chứng khoán
483
-
484
- ```python
485
- from quantvn.vn.data import Listing
486
-
487
- listing = Listing()
488
-
489
- # Lấy danh sách mã theo sàn
490
- symbols = listing.symbols_by_exchange()
491
- print(f"HOSE: {len(symbols['HOSE'])} symbols")
492
- print(f"HNX: {len(symbols['HNX'])} symbols")
493
- print(f"UPCOM: {len(symbols['UPCOM'])} symbols")
494
- ```
495
-
496
- **Output:**
497
-
498
- ```python
499
- HOSE: 3 symbols
500
- HNX: 0 symbols
501
- UPCOM: 0 symbols
502
- ```
503
-
504
- ---
505
-
506
- ### 2. Phái sinh VN30
507
-
508
- ```python
509
- from quantvn import client
510
- client(apikey="your-apikey-here")
511
-
512
- from quantvn.vn.data import get_derivatives_hist
513
-
514
- # Dữ liệu VN30F1M theo phút
515
- vn30_1m = get_derivatives_hist("VN30F1M", "1m")
516
- print("Dữ liệu VN30F1M theo phút")
517
- print(vn30_1m.head())
518
-
519
- # Dữ liệu VN30F1M theo 5 phút
520
- vn30_5m = get_derivatives_hist("VN30F1M", "5m")
521
- print("Dữ liệu VN30F1M theo 5 phút")
522
- print(vn30_5m.head())
523
-
524
- # Dữ liệu VN30F1M theo 15 phút
525
- vn30_15m = get_derivatives_hist("VN30F1M", "15m")
526
- print("Dữ liệu VN30F1M theo 15 phút")
527
- print(vn30_15m.head())
528
-
529
- # Các resolution hỗ trợ: "1m", "5m", "15m"
530
- ```
531
-
532
- **Output:**
533
-
534
- ```python
535
- Dữ liệu VN30F1M theo phút
536
- Date time Open High Low Close volume Datetime
537
- 0 2018-08-13 09:01:00 943.0 943.1 942.9 943.1 220.0 2018-08-13 09:01:00
538
- 1 2018-08-13 09:02:00 943.0 943.6 943.0 943.5 121.0 2018-08-13 09:02:00
539
- 2 2018-08-13 09:03:00 943.3 943.4 943.3 943.4 135.0 2018-08-13 09:03:00
540
- 3 2018-08-13 09:04:00 943.2 943.2 943.0 943.1 361.0 2018-08-13 09:04:00
541
- 4 2018-08-13 09:05:00 943.1 943.1 942.9 943.0 343.0 2018-08-13 09:05:00
542
-
543
- Dữ liệu VN30F1M theo 5 phút
544
- Date time Open High Low Close volume Datetime
545
- 0 2018-08-13 09:00:00 943.5 943.6 942.9 943.1 1812.0 2018-08-13 09:00:00
546
- 1 2018-08-13 09:05:00 943.1 943.5 942.9 943.3 1323.0 2018-08-13 09:05:00
547
- 2 2018-08-13 09:10:00 943.2 943.3 942.6 943.1 1207.0 2018-08-13 09:10:00
548
- 3 2018-08-13 09:15:00 943.1 943.1 942.3 942.6 1196.0 2018-08-13 09:15:00
549
- 4 2018-08-13 09:20:00 942.6 943.7 942.4 943.7 1765.0 2018-08-13 09:20:00
550
-
551
- Dữ liệu VN30F1M theo 15 phút
552
- Date time Open High Low Close volume Datetime
553
- 0 2018-08-13 09:00:00 943.5 943.6 942.6 943.1 4342.0 2018-08-13 09:00:00
554
- 1 2018-08-13 09:15:00 943.1 945.9 942.3 945.3 5430.0 2018-08-13 09:15:00
555
- 2 2018-08-13 09:30:00 945.2 945.5 943.3 944.5 4933.0 2018-08-13 09:30:00
556
- 3 2018-08-13 09:45:00 944.5 946.4 944.3 946.0 4254.0 2018-08-13 09:45:00
557
- 4 2018-08-13 10:00:00 945.9 946.3 944.5 945.2 4336.0 2018-08-13 10:00:00
558
- ```
559
-
560
- ---
561
-
562
- ---
563
-
564
- ### 3. Technical Analysis & Fundamental Features
565
-
566
- #### 3.1. Thêm chỉ báo kỹ thuật
567
-
568
- ```python
569
- from quantvn.vn.data import add_all_ta_features, get_stock_hist
570
-
571
- # Lấy dữ liệu
572
- df = get_stock_hist("VIC", resolution="1H")
573
-
574
- # Thêm tất cả chỉ báo kỹ thuật
575
- df_with_ta = add_all_ta_features(df)
576
-
577
- # DataFrame sẽ có thêm các cột: RSI, MACD, Bollinger Bands, etc.
578
- print(df_with_ta.columns)
579
- print(df_with_ta.head())
580
- ```
581
-
582
- **Output:**
583
-
584
- ```python
585
- ['Date', 'time', 'Open', 'High', 'Low', 'Close', 'volume', 'volume_adi', 'volume_obv', 'volume_cmf',...'sma_fast', 'sma_slow', 'ema_fast',
586
- 'ema_slow', 'bb_middle', 'bb_high','bb_low', 'bb_width', 'bb_percent', 'atr']
587
-
588
- Date time Open High Low Close volume ... ema_slow bb_middle bb_high bb_low bb_width bb_percent atr
589
- 0 2023-03-20 09:00:00 26.50 26.60 26.20 26.30 188600.0 ... 26.300000 26.3000 26.300000 26.300000 0.000000 0.000000 0.0
590
- 1 2023-03-20 10:00:00 26.25 26.40 26.00 26.10 319300.0 ... 26.285185 26.2000 26.400000 26.000000 1.526718 0.250000 0.0
591
- 2 2023-03-20 11:00:00 26.05 26.10 25.85 25.90 294700.0 ... 26.256653 26.1000 26.426599 25.773401 2.502672 0.193814 0.0
592
- 3 2023-03-20 13:00:00 25.90 25.95 25.70 25.75 928800.0 ... 26.219123 26.0125 26.427078 25.597922 3.187530 0.183413 0.0
593
- 4 2023-03-20 14:00:00 25.80 26.40 25.70 26.40 1630900.0 ... 26.232521 26.0900 26.573322 25.606678 3.705035 0.820697 0.0
594
- ```
595
-
596
- #### 3.2. Thêm chỉ số tài chính cơ bản
597
-
598
- ```python
599
- from quantvn.vn.data import add_all_fund_features, get_stock_hist
600
-
601
- # Lấy dữ liệu
602
- df = get_stock_hist("HPG", resolution="1H")
603
-
604
- # Thêm các chỉ số tài chính (PE, PB, ROE, ROA, etc.)
605
- df_with_fund = add_all_fund_features(df, symbol="HPG")
606
-
607
- print(df_with_fund.columns)
608
- print(df_with_fund.head())
609
- ```
610
-
611
- **Output:**
612
-
613
- ```python
614
- ['Date', 'time', 'Open', 'High', 'Low', 'Close', 'volume', 'ticker','year', 'quarter']
615
-
616
- Date time Open High Low Close volume ticker year quarter
617
- 0 2023-03-20 09:00:00 15.46 15.61 15.37 15.57 3598400.0 HPG 2023 1
618
- 1 2023-03-20 10:00:00 15.61 15.61 15.42 15.49 3128900.0 HPG 2023 1
619
- 2 2023-03-20 11:00:00 15.49 15.49 15.37 15.42 1437100.0 HPG 2023 1
620
- 3 2023-03-20 13:00:00 15.42 15.42 15.19 15.22 7626000.0 HPG 2023 1
621
- 4 2023-03-20 14:00:00 15.22 15.30 15.15 15.15 7198500.0 HPG 2023 1
622
- ```
623
-
624
- #### 3.3. Lấy từng chỉ số cụ thể
625
-
626
- ```python
627
- from quantvn import client
628
- client(apikey="your-apikey-here")
629
-
630
- from quantvn.vn.data import fund_feature
631
-
632
- # Lấy ROE
633
- roe_data = fund_feature("roe", "VCB")
634
- print(roe_data.head())
635
-
636
- ```
637
-
638
- **Output:**
639
-
640
- ```python
641
- Date time Open High Low Close Volume roe
642
- 0 2023-03-20 09:00:00 50.04 50.32 49.77 50.04 189400.0 NaN
643
- 1 2023-03-20 10:00:00 50.04 50.04 49.54 49.65 170900.0 NaN
644
- 2 2023-03-20 11:00:00 49.65 49.71 49.48 49.48 115500.0 NaN
645
- 3 2023-03-20 13:00:00 49.48 49.59 48.86 48.92 189800.0 NaN
646
- 4 2023-03-20 14:00:00 48.92 49.15 47.85 47.85 367000.0 NaN
647
- ```
648
-
649
- **Các chỉ số khả dụng:**
650
-
651
- - `earningPerShare` (EPS)
652
- - `bookValuePerShare` (BVPS)
653
- - `roe` (Return on Equity)
654
- - `roa` (Return on Assets)
655
- - `priceToEarning` (P/E)
656
- - `priceToBook` (P/B)
657
- - Và nhiều chỉ số khác...
658
-
659
- ---
660
-
661
- ### 4. Backtesting & Performance Analysis
662
-
663
- #### 4.1. Backtest cho phái sinh
664
-
665
- ```python
666
- from quantvn import client
667
- client(apikey="your-apikey-here")
668
-
669
- from quantvn.vn.metrics import Backtest_Derivates
670
- from quantvn.vn.data import get_derivatives_hist
671
- import pandas as pd
672
-
673
- # Lấy dữ liệu
674
- df = get_derivatives_hist("VN30F1M", "5m")
675
-
676
- # Tạo tín hiệu giao dịch đơn giản (ví dụ: MA crossover)
677
- df["ma_short"] = df["Close"].rolling(20).mean()
678
- df["ma_long"] = df["Close"].rolling(50).mean()
679
-
680
- # Position: 1 (long), -1 (short), 0 (no position)
681
- df["position"] = 0
682
- df.loc[df["ma_short"] > df["ma_long"], "position"] = 1
683
- df.loc[df["ma_short"] < df["ma_long"], "position"] = -1
684
- print(df.iloc[100:105])
685
-
686
- # Chạy backtest (PnL sau phí)
687
- backtest = Backtest_Derivates(df, pnl_type="after_fees")
688
-
689
- # Xem PnL tích lũy
690
- pnl = backtest.PNL()
691
- print(f"Final PnL: {pnl.iloc[-1]:,.2f} VND")
692
-
693
- # PnL theo ngày
694
- daily_pnl = backtest.daily_PNL()
695
- print(daily_pnl.tail())
696
-
697
- # Ước tính vốn tối thiểu
698
- min_capital = backtest.estimate_minimum_capital()
699
- print(f"Minimum capital needed: {min_capital:,.0f} VND")
700
-
701
- # Vẽ biểu đồ PnL
702
- backtest.plot_PNL("VN30F1M - MA Crossover Strategy")
703
- ```
704
-
705
- **Output**
706
-
707
- ```python
708
- Date time Open High Low Close volume Datetime ma_short ma_long position
709
- 100 2018-08-15 09:10:00 959.3 960.5 959.3 960.4 927.0 2018-08-15 09:10:00 958.645 956.424 1
710
- 101 2018-08-15 09:15:00 960.3 961.1 960.3 960.7 1413.0 2018-08-15 09:15:00 958.930 956.538 1
711
- 102 2018-08-15 09:20:00 960.8 960.8 960.1 960.3 1172.0 2018-08-15 09:20:00 959.135 956.606 1
712
- 103 2018-08-15 09:25:00 960.3 960.3 959.0 959.0 1735.0 2018-08-15 09:25:00 959.290 956.670 1
713
- 104 2018-08-15 09:30:00 959.3 960.1 959.2 960.1 1271.0 2018-08-15 09:30:00 959.460 956.762 1
714
-
715
- Final PnL: 1,783.93 VND
716
-
717
- 2022-12-26 1809.1830
718
- 2022-12-27 1823.1290
719
- 2022-12-28 1816.6955
720
- 2022-12-29 1794.6620
721
- 2022-12-30 1783.9285
722
-
723
- Minimum capital needed: 980 VND
724
- ```
725
-
726
- **Tham số:**
727
-
728
- - `pnl_type` (str):
729
- - `"raw"`: PnL thô (chưa trừ phí)
730
- - `"after_fees"`: PnL sau khi trừ phí giao dịch
731
-
732
- #### 4.2. Backtest cho cổ phiếu
733
-
734
- ```python
735
- from quantvn.vn.metrics import Backtest_Stock
736
- from quantvn.vn.data import get_stock_hist
737
-
738
- # Lấy dữ liệu
739
- df = get_stock_hist("VIC", resolution="1H")
740
-
741
- # Tạo chiến lược đơn giản
742
- df["ma20"] = df["Close"].rolling(20).mean()
743
- df["ma50"] = df["Close"].rolling(50).mean()
744
-
745
- # Position: số lượng cổ phiếu (ví dụ: 100 cổ)
746
- df["position"] = 0
747
- df.loc[df["ma20"] > df["ma50"], "position"] = 100
748
- print(df.iloc[100:105])
749
-
750
- # Backtest
751
- backtest = Backtest_Stock(df, pnl_type="after_fees")
752
- pnl = backtest.PNL()
753
- print(pnl.iloc[100:105])
754
-
755
- # Vẽ PnL
756
- backtest.plot_PNL("VIC - MA(20/50) Strategy")
757
- ```
758
-
759
- **Output:**
760
-
761
- ```python
762
- Date time Open High Low Close volume ma20 ma50 position
763
- 100 2023-04-17 09:00:00 26.45 26.50 26.25 26.25 196700.0 26.4800 27.264 0
764
- 101 2023-04-17 10:00:00 26.30 26.40 26.25 26.25 246900.0 26.4700 27.201 0
765
- 102 2023-04-17 11:00:00 26.30 26.30 26.20 26.20 156200.0 26.4525 27.138 0
766
- 103 2023-04-17 13:00:00 26.25 26.40 26.25 26.30 311700.0 26.4425 27.089 0
767
- 104 2023-04-17 14:00:00 26.30 26.35 26.25 26.25 331600.0 26.4175 27.039 0
768
-
769
- datetime
770
- 2023-04-17 09:00:00 -70.395
771
- 2023-04-17 10:00:00 -70.395
772
- 2023-04-17 11:00:00 -70.395
773
- 2023-04-17 13:00:00 -70.395
774
- 2023-04-17 14:00:00 -70.395
775
- ```
776
-
777
- #### 4.3. Metrics - Đánh giá hiệu suất
778
-
779
- ```python
780
- from quantvn import client
781
- client(apikey="your-apikey-here")
782
-
783
- from quantvn.vn.metrics import Metrics, Backtest_Derivates
784
- from quantvn.vn.data import get_derivatives_hist
785
-
786
- # Giả sử đã có backtest
787
- df = get_derivatives_hist("VN30F1M", "5m")
788
- # ... tạo position ...
789
- df["position"] = 1 # Ví dụ đơn giản: long cả ngày
790
-
791
- backtest = Backtest_Derivates(df, pnl_type="after_fees")
792
- metrics = Metrics(backtest)
793
-
794
- # Các chỉ số hiệu suất
795
- print(f"Sharpe Ratio: {metrics.sharpe():.3f}")
796
- print(f"Sortino Ratio: {metrics.sortino():.3f}")
797
- print(f"Calmar Ratio: {metrics.calmar():.3f}")
798
- print(f"Max Drawdown: {metrics.max_drawdown()*100:.2f}%")
799
- print(f"Win Rate: {metrics.win_rate()*100:.2f}%")
800
- print(f"Profit Factor: {metrics.profit_factor():.3f}")
801
- print(f"Average Win: {metrics.avg_win():,.0f} VND")
802
- print(f"Average Loss: {metrics.avg_loss():,.0f} VND")
803
- print(f"Risk of Ruin: {metrics.risk_of_ruin():.4f}")
804
-
805
- # Value at Risk (95% confidence)
806
- var_95 = metrics.value_at_risk(confidence_level=0.95)
807
- print(f"VaR (95%): {var_95:,.0f} VND")
808
- ```
809
-
810
- **Output:**
811
-
812
- ```python
813
- Sharpe Ratio: 0.019
814
- Sortino Ratio: 0.024
815
- Calmar Ratio: 0.434
816
- Max Drawdown: -72.36%
817
- Win Rate: 51.78%
818
- Profit Factor: 1.003
819
- Average Win: 11 VND
820
- Average Loss: -12 VND
821
- Risk of Ruin: 1.0061
822
- VaR (95%): 25 VND
823
- ```
824
-
825
- **Các metrics có sẵn:**
826
-
827
- - `sharpe()`: Sharpe Ratio
828
- - `sortino()`: Sortino Ratio
829
- - `calmar()`: Calmar Ratio
830
- - `max_drawdown()`: Drawdown tối đa
831
- - `win_rate()`: Tỷ lệ thắng
832
- - `profit_factor()`: Tỷ số lợi nhuận
833
- - `avg_win()`: Lãi trung bình
834
- - `avg_loss()`: Lỗ trung bình
835
- - `avg_return()`: Return trung bình
836
- - `volatility()`: Độ biến động
837
- - `value_at_risk(confidence_level)`: Value at Risk
838
- - `risk_of_ruin()`: Xác suất phá sản
839
-
840
- ---
841
-
842
- ## Ví dụ thực tế
843
-
844
- Xem cách triển khai và chạy trực tiếp trên Google Colab:
845
- https://colab.research.google.com/drive/1pEVYivKMNwRVxERy4mb9ujzoHrh7avJL?usp=sharing
846
-
847
- ---
848
-
849
- ## Testing
850
-
851
- Chạy tests:
852
-
853
- ```bash
854
- # Cài đặt dependencies cho dev
855
- pip install -e ".[dev]"
856
-
857
- # Chạy tests
858
- pytest tests/
859
-
860
- # Chạy với coverage
861
- pytest --cov=quantvn tests/
862
- ```
863
-
864
- ---
865
-
866
- ## Đóng góp
867
-
868
- Chúng tôi hoan nghênh mọi đóng góp! Để đóng góp:
869
-
870
- 1. Fork repository
871
- 2. Tạo branch mới (`git checkout -b feature/AmazingFeature`)
872
- 3. Commit changes (`git commit -m 'Add some AmazingFeature'`)
873
- 4. Push to branch (`git push origin feature/AmazingFeature`)
874
- 5. Mở Pull Request
875
-
876
- Vui lòng đọc [CONTRIBUTING.md](CONTRIBUTING.md) để biết thêm chi tiết.
877
-
878
- ---
879
-
880
- ## Tuyên bố miễn trách nhiệm
881
-
882
- **QuantVN** được phát triển nhằm phục vụ mục đích nghiên cứu và học tập.
883
-
884
- - Dữ liệu cung cấp có thể không đầy đủ hoặc không chính xác 100%
885
- - 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
886
- - 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
887
-
888
- **Lưu ý quan trọng:**
889
-
890
- - Luôn kiểm tra và xác thực dữ liệu trước khi sử dụng
891
- - Backtesting không đảm bảo kết quả trong tương lai
892
- - Quản lý rủi ro là trách nhiệm của người dùng
893
-
894
- ---
895
-
896
- ## Giấy phép
897
-
898
- Dự án này được phát hành theo giấy phép **MIT License**. Xem file [LICENSE](LICENSE) để biết thêm chi tiết.
899
-
900
- ---
901
-
902
- ## Changelog
903
-
904
- ### Version 0.1.5
905
-
906
- - Thêm hỗ trợ cryptocurrency data từ Binance
907
- - Cải thiện performance cho `get_stock_hist()`
908
- - Sửa lỗi timezone cho dữ liệu phái sinh
909
- - Thêm các metrics mới: Risk of Ruin, VaR
910
-
911
- ### Version 0.1.4
912
-
913
- - Thêm module backtesting cho cổ phiếu
914
- - Hỗ trợ Take Profit/Stop Loss
915
- - Cải thiện documentation
916
-
917
- ---
918
-
919
- ## Hỗ trợ
920
-
921
- - **GitHub Issues**: https://github.com/quantvn/quantvn-vn-markets/issues
922
- - **Documentation**: https://quantvn.gitbook.io/quantvn-docs
923
-
924
- ---
925
-
926
- **QuantVN** - Công cụ phân tích tài chính mạnh mẽ cho thị trường Việt Nam
1
+ Metadata-Version: 2.4
2
+ Name: quantvn
3
+ Version: 0.2.0
4
+ Summary: QuantVN API Library for Financial Data Analysis
5
+ Author: quantvn
6
+ Classifier: Development Status :: 3 - Alpha
7
+ Classifier: Intended Audience :: Developers
8
+ Classifier: Programming Language :: Python :: 3.9
9
+ Classifier: Programming Language :: Python :: 3.10
10
+ Classifier: Programming Language :: Python :: 3.11
11
+ Classifier: Programming Language :: Python :: 3.12
12
+ Classifier: Programming Language :: Python :: 3.13
13
+ Requires-Python: >=3.9
14
+ Description-Content-Type: text/markdown
15
+ License-File: LICENSE
16
+ Requires-Dist: requests
17
+ Requires-Dist: pandas
18
+ Requires-Dist: numpy
19
+ Requires-Dist: matplotlib
20
+ Requires-Dist: tqdm
21
+ Requires-Dist: ta
22
+ Requires-Dist: pyarrow
23
+ Provides-Extra: dev
24
+ Requires-Dist: pytest; extra == "dev"
25
+ Dynamic: author
26
+ Dynamic: classifier
27
+ Dynamic: description
28
+ Dynamic: description-content-type
29
+ Dynamic: license-file
30
+ Dynamic: provides-extra
31
+ Dynamic: requires-dist
32
+ Dynamic: requires-python
33
+ Dynamic: summary
34
+
35
+ # QuantVN - Python Library for Vietnamese Financial Market Analysis
36
+
37
+ **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.
38
+
39
+ ## Tính năng nổi bật
40
+
41
+ **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.
42
+
43
+ **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.
44
+
45
+ **Dữ liệu thị trường**:
46
+
47
+ - Cổ phiếu Việt Nam (HOSE, HNX, UPCOM)
48
+ - Phái sinh VN30
49
+
50
+ **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.
51
+
52
+ **Viết chiến lược cho nền tảng QuantVN**: Chạy thử chiến lược như khi chạy thật, phát hiện nhìn trước tương lai, mô phỏng khớp lệnh trung thực và gửi vị thế lên Track Record (mục 5).
53
+
54
+ ## Quy trình QuantVN
55
+
56
+ Để xây dựng một hệ thống giao dịch thành công, QuantVN vận hành theo một quy trình 4 bước khép kín và logic.
57
+
58
+ ![image](https://res.cloudinary.com/dbn4eimis/image/upload/v1773975369/image_1_pxtcuk.png)
59
+
60
+ ## Cài đặt
61
+
62
+ ### Từ PyPI (khuyến nghị)
63
+
64
+ ```bash
65
+ pip install quantvn
66
+ ```
67
+
68
+ ### Từ mã nguồn
69
+
70
+ ```bash
71
+ git clone https://github.com/your-repo/quantvn.git
72
+ cd quantvn
73
+ pip install -e .
74
+ ```
75
+
76
+ ### Yêu cầu hệ thống
77
+
78
+ - Python >= 3.9
79
+ - pandas
80
+ - requests
81
+ - matplotlib
82
+ - tqdm
83
+
84
+ ## Bắt đầu nhanh
85
+
86
+ ### Khởi tạo API Client
87
+
88
+ Để sử dụng các tính năng của QuantVN , người dùng cần cung cấp API Key được cấp từ nền tảng **QuantVN** | https://quantvn.com/.
89
+
90
+ ![image](https://res.cloudinary.com/dbn4eimis/image/upload/v1773975781/Gemini_Generated_Image_r5fls6r5fls6r5fl_ktk5hx.png)
91
+
92
+ <p align="center">
93
+ <a href="https://quantvn.com/">
94
+ <img src="https://img.shields.io/badge/🌐 Visit Website-QuantVN-blue?style=for-the-badge" />
95
+ </a>
96
+ </p>
97
+
98
+ API Key được sử dụng để xác thực các yêu cầu tới hệ thống dữ liệu của QuantVN, giúp kiểm soát truy cập, đảm bảo tính ổn định của dịch vụ và theo dõi mức sử dụng.
99
+
100
+ ```python
101
+ from quantvn.vn.data.utils import client
102
+
103
+ # Khởi tạo với API key (nếu có)
104
+ client(apikey="your_api_key_here")
105
+ ```
106
+
107
+ **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 đủ.
108
+
109
+ ### Các bước để lấy API Key
110
+
111
+ #### Bước 1: Truy cập website
112
+
113
+ Truy cập vào website chính thức:
114
+
115
+ https://quantvn.com/
116
+
117
+ Tại trang chủ, nhấn vào nút **"Tham gia ngay"** để bắt đầu.
118
+
119
+ ![image](https://res.cloudinary.com/dbn4eimis/image/upload/v1773988068/1_u0wfbq.png)
120
+
121
+ #### Bước 2: Đăng nhập hoặc đăng ký tài khoản
122
+
123
+ Nếu bạn đã có tài khoản:
124
+
125
+ - Nhập thông tin đăng nhập để truy cập hệ thống.
126
+ - Hoặc đăng nhập nhanh bằng Google
127
+
128
+ Nếu bạn chưa có tài khoản:
129
+
130
+ - Đăng ký tài khoản mới bằng email
131
+ - Hoặc đăng ký nhanh bằng Google
132
+
133
+ ![image](https://res.cloudinary.com/dbn4eimis/image/upload/v1773988068/2_jsniro.png)
134
+
135
+ #### Bước 3: Truy cập mục Hồ sơ & API Keys
136
+
137
+ Sau khi đăng nhập thành công:
138
+
139
+ - Nhấn vào **hình đại diện hồ sơ** ở góc trên cùng bên trái
140
+ - Một menu sẽ hiển thị
141
+ - Chọn mục **"Hồ sơ & API keys"**
142
+
143
+ ![image](https://res.cloudinary.com/dbn4eimis/image/upload/v1773989364/hihi_kwft6d.jpg)
144
+
145
+ #### Bước 4: Lấy API Key
146
+
147
+ Trong trang Hồ sơ & API Keys:
148
+
149
+ - Nhấn vào mục **"Cài đặt"**
150
+ - Tại đây bạn sẽ thấy API Key của mình
151
+
152
+ Bạn có thể:
153
+
154
+ - Nhấn **"Xem Key"** để hiển thị API Key và copy để sử dụng
155
+ - Hoặc nhấn **"Tạo API Key mới"** để tạo key mới
156
+
157
+ ![image](https://res.cloudinary.com/dbn4eimis/image/upload/v1773990774/hihhihihihii_qnbnrk.jpg)
158
+
159
+ #### Lưu ý
160
+
161
+ - Không chia sẻ API Key với người khác
162
+ - API Key được sử dụng để xác thực khi sử dụng thư viện QuantVN
163
+
164
+ ---
165
+
166
+ ## Tài liệu API
167
+
168
+ ### 1. Dữ liệu Cổ phiếu Việt Nam
169
+
170
+ Module: `quantvn.vn.data`
171
+
172
+ #### 1.1. Danh sách cổ phiếu thanh khoản cao
173
+
174
+ ```python
175
+ from quantvn import client
176
+ client(apikey="your_api_key_here")
177
+
178
+ from quantvn.vn.data import list_liquid_asset
179
+
180
+ # Lấy danh sách cổ phiếu có thanh khoản cao
181
+ liquid_stocks = list_liquid_asset()
182
+ print(liquid_stocks.head())
183
+ ```
184
+
185
+ **Output:**
186
+
187
+ ```python
188
+ symbol liquidity
189
+ 0 VCB 5.234567e+10
190
+ 1 HPG 4.123456e+10
191
+ 2 VIC 3.876543e+10
192
+ ```
193
+
194
+ #### 1.2. Dữ liệu lịch sử cổ phiếu
195
+
196
+ ```python
197
+ from quantvn.vn.data import get_stock_hist
198
+
199
+ # Lấy dữ liệu 1H (ví dụ sử dụng khung giờ 1H)
200
+ vic_hour = get_stock_hist("VIC", resolution="1H")
201
+ print(vic_hour.head())
202
+ ```
203
+
204
+ **Tham số:**
205
+
206
+ - `symbol` (str): Mã cổ phiếu (VD: "VIC", "HPG", "VCB")
207
+ - `resolution` (str): Khung thời gian, hiện chỉ hỗ trợ `"1H"` (bắt buộc).
208
+
209
+ **Output:**
210
+
211
+ ```python
212
+ Date time Open High Low Close volume
213
+ 0 2024-01-02 09:00:00 42.50 42.80 42.30 42.60 1234567.0
214
+ 1 2024-01-02 10:00:00 42.60 42.90 42.50 42.75 2345678.0
215
+ ```
216
+
217
+ #### 1.3. Thông tin chi tiết công ty
218
+
219
+ ```python
220
+ from quantvn import client
221
+ client(apikey="your_api_key_here")
222
+
223
+ from quantvn.vn.data import Company
224
+
225
+ company = Company("VIC")
226
+
227
+ # Thông tin tổng quan
228
+ overview = company.overview()
229
+ print("Thông tin tổng quan")
230
+ print(overview[["symbol", "id", "issue_share", "icb_name2", "icb_name4"]])
231
+
232
+ # Danh sách cổ đông
233
+ shareholders = company.shareholders()
234
+ print("Danh sách cổ đông")
235
+ print(shareholders.head())
236
+
237
+ # Ban lãnh đạo
238
+ officers = company.officers()
239
+ print("Ban lãnh đạo")
240
+ print(officers.head())
241
+
242
+ # Công ty con
243
+ subsidiaries = company.subsidiaries()
244
+ print("Công ty con")
245
+ print(subsidiaries.head())
246
+
247
+ # Sự kiện quan trọng
248
+ events = company.events()
249
+ print("Sự kiện quan trọng")
250
+ print(events.head())
251
+
252
+ # Tin tức
253
+ news = company.news()
254
+ print("Tin tức")
255
+ print(news.head())
256
+
257
+ # Tỷ số tài chính tổng hợp
258
+ ratios = company.ratio_summary()
259
+ print("Tỷ số tài chính tổng hợp")
260
+ print(ratios[["pe", "pb", "roe", "roa"]])
261
+ ```
262
+
263
+ **Output:**
264
+
265
+ ```python
266
+ Thông tin tổng quan
267
+ symbol id issue_share icb_name2 icb_name4
268
+ 0 VIC 76055 7706031024 Bất động sản Bất động sản
269
+
270
+ Danh sách cổ đông
271
+ id ticker ... updateDate __typename
272
+ 0 100950872 VIC ... 1770048564380 OrganizationShareHolders
273
+ 1 100950031 VIC ... 1767201363047 OrganizationShareHolders
274
+ 2 100971726 VIC ... 1767201489503 OrganizationShareHolders
275
+ 3 100972520 VIC ... 1770048733047 OrganizationShareHolders
276
+ 4 100950463 VIC ... 1770048609397 OrganizationShareHolders
277
+
278
+ Ban lãnh đạo
279
+ id ticker fullName ... percentage quantity __typename
280
+ 0 19 VIC Phạm Nhật Vượng ... 0.091010 703848781 OrganizationManager
281
+ 1 5 VIC Phạm Thu Hương ... 0.044280 341221050 OrganizationManager
282
+ 2 6 VIC Phạm Thúy Hằng ... 0.029630 228326892 OrganizationManager
283
+ 3 4 VIC Phạm Văn Khương ... 0.000600 2267587 OrganizationManager
284
+ 4 18 VIC Nguyễn Diệu Linh ... 0.000242 1865418 OrganizationManager
285
+
286
+ Công ty con
287
+ id organCode subOrganCode percentage subOrListingInfo __typename
288
+ 0 28590324 VIC 0110006565 0.6142 {'enOrganName': 'VS Development Investment Joi... Subsidiary
289
+ 1 28590325 VIC 0110009975 NaN {'enOrganName': 'Vincom Retail Investment Join... Subsidiary
290
+ 2 28590326 VIC 0110537975 0.6581 {'enOrganName': 'SV Tay Hanoi Real Estate Join... Subsidiary
291
+ 3 28590327 VIC 0110873550 0.7339 {'enOrganName': 'Vinhomes Ha Tinh Industrial Z... Subsidiary
292
+ 4 28590328 VIC 0110873568 0.7305 {'enOrganName': 'Vinhomes Hai Phong Industrial... Subsidiary
293
+
294
+ Sự kiện quan trọng
295
+ id organCode ticker eventTitle ... exrightDate eventListName en_EventListName __typename
296
+ 0 34642 VIC VIC Niêm yết thêm ... -6847804800000 Niêm yết thêm Additional Listing OrganizationEvent
297
+ 1 34686 VIC VIC Niêm yết thêm ... -6847804800000 Niêm yết thêm Additional Listing OrganizationEvent
298
+ 2 34687 VIC VIC Niêm yết thêm ... -6847804800000 Niêm yết thêm Additional Listing OrganizationEvent
299
+ 3 34702 VIC VIC VIC-Niêm yết bổ sung 484.473.162 cổ phiếu ... -6847804800000 Niêm yết thêm Additional Listing OrganizationEvent
300
+ 4 34657 VIC VIC Niêm yết thêm ... -6847804800000 Niêm yết thêm Additional Listing OrganizationEvent
301
+
302
+ Tin tức
303
+ id organCode ticker newsTitle newsSubTitle ... referencePrice floorPrice ceilingPrice percentPriceChange __typename
304
+ 0 9588803 VIC VIC VIC: Nghị quyết HĐQT về việc niêm yết trái phi... ... 145000.0 134900.0 155100.0 -0.002759 News
305
+ 1 9559000 VIC VIC VIC: Thông báo giao dịch cổ phiếu của tổ chức ... ... 141800.0 131900.0 151700.0 0.029619 News
306
+ 2 9515973 VIC VIC VIC: Thông báo về ngày đăng ký cuối cùng để th... ... 164800.0 153300.0 176300.0 -0.050364 News
307
+ 3 9479016 VIC VIC VIC: Quyết định về việc chốt danh sách người s... ... 168900.0 157100.0 180700.0 0.018354 News
308
+ 4 9469700 VIC VIC VIC: CBTT phát hành trái phiếu quốc tế ... 168900.0 157100.0 180700.0 0.018354 News
309
+
310
+ Tỷ số tài chính tổng hợp
311
+ pe pb roe roa
312
+ 0 83.96933 7.596341 0.09402 0.013734
313
+ ```
314
+
315
+ #### 1.4. Tỷ số tài chính
316
+
317
+ ```python
318
+ from quantvn import client
319
+ client(apikey="your-apikey-here")
320
+
321
+ from quantvn.vn.data import Finance
322
+
323
+ # Khởi tạo Finance (dùng BACKEND mặc định)
324
+ finance = Finance("HPG")
325
+
326
+ # Tỷ số tài chính theo quý
327
+ ratios_q = finance.ratio(period="Q")
328
+ print("Tỷ số tài chính theo quý:")
329
+ if not ratios_q.empty:
330
+ print(ratios_q[["year", "quarter", "revenue", "netProfit", "roe", "pe", "pb"]].head())
331
+
332
+ # Tỷ số tài chính theo năm
333
+ ratios_y = finance.ratio(period="Y")
334
+ print("\nTỷ số tài chính theo năm:")
335
+ if not ratios_y.empty:
336
+ print(ratios_y[["year", "revenue", "netProfit", "roe", "pe", "pb"]].head())
337
+ ```
338
+
339
+ **Output:**
340
+
341
+ ```python
342
+ Tỷ số tài chính theo quý:
343
+ year year quarter quarter revenue netProfit roe pe pb
344
+ 0 2025 2025 4 4 47301623136340 3860994446656 0.126882 13.314004 1.592397
345
+ 1 2025 2025 3 3 36793873449413 3988318474539 0.120224 14.527037 1.667413
346
+ 2 2025 2025 2 2 36286185846409 4256487211764 0.115502 16.199640 1.790441
347
+ 3 2025 2025 1 1 37950635502050 3344284694388 0.110522 15.817610 1.679199
348
+ 4 2024 2024 4 4 35232197602514 2808645369171 0.110732 13.754011 1.445857
349
+
350
+ Tỷ số tài chính theo năm:
351
+ year year revenue netProfit roe pe pb
352
+ 0 2025 2025 158332317934212 15450084827347 0.126882 13.314004 1.592397
353
+ 1 2024 2024 140561387448572 12021443836074 0.110732 14.344970 1.476620
354
+ 2 2023 2023 120355231616139 6835064334356 0.068771 23.858738 1.507863
355
+ 3 2022 2022 142770810676858 8483510554031 0.090911 19.253321 1.692821
356
+ 4 2021 2021 150865359967200 34478143197460 0.459707 2.407519 0.888407
357
+ ```
358
+
359
+ **Tham số:**
360
+
361
+ - `period` (str): `"Q"` (quý) hoặc `"Y"` (năm)
362
+ - `dropna` (bool): Loại bỏ các giá trị null (mặc định: `False`)
363
+
364
+ #### 1.5. Dữ liệu Quote realtime
365
+
366
+ ```python
367
+ from quantvn.vn.data import Quote
368
+
369
+ quote = Quote("ACB")
370
+
371
+ # Lấy dữ liệu lịch sử trong khoảng thời gian
372
+ history = quote.history(
373
+ start="2024-01-01",
374
+ end="2024-03-31",
375
+ interval="1D"
376
+ )
377
+ print("Dữ liệu lịch sử trong khoảng thời gian")
378
+ print(history.head())
379
+
380
+ # Dữ liệu tick intraday
381
+ intraday = quote.intraday(page_size=200)
382
+ print("Dữ liệu tick intraday")
383
+ print(intraday.head())
384
+
385
+ # Độ sâu thị trường (price depth)
386
+ depth = quote.price_depth()
387
+ print("Độ sâu thị trường (price depth)")
388
+ print(depth.head())
389
+ ```
390
+
391
+ **Output:**
392
+
393
+ ```python
394
+ Dữ liệu lịch sử trong khoảng thời gian
395
+ time open high low close volume
396
+ 0 2024-01-02 16808.59 17370.04 16808.59 17159.50 13896933
397
+ 1 2024-01-03 17194.59 17545.50 17019.13 17545.50 9817807
398
+ 2 2024-01-04 17685.86 18001.68 17615.68 17756.05 23605373
399
+ 3 2024-01-05 17756.05 17861.32 17580.59 17861.32 9282598
400
+ 4 2024-01-08 18036.77 18071.87 17685.86 17791.14 12398885
401
+
402
+ Dữ liệu tick intraday
403
+ time price volume match_type id
404
+ 0 2026-03-19 06:26:22 23300.0 1300.0 s 452011243
405
+ 1 2026-03-19 06:26:22 23300.0 200.0 s 452011242
406
+ 2 2026-03-19 06:26:22 23300.0 100.0 s 452011241
407
+ 3 2026-03-19 06:26:22 23300.0 400.0 s 452011240
408
+ 4 2026-03-19 06:26:21 23350.0 100.0 b 452011220
409
+
410
+ Độ sâu thị trường (price depth)
411
+ price acc_volume acc_buy_volume acc_sell_volume acc_undefined_volume
412
+ 0 23550.0 32800.0 21300.0 11500.0 0.0
413
+ 1 23500.0 627100.0 357900.0 7400.0 261800.0
414
+ 2 23450.0 2006100.0 1413700.0 592400.0 0.0
415
+ 3 23400.0 1724200.0 655300.0 1068900.0 0.0
416
+ 4 23350.0 1214700.0 569600.0 645100.0 0.0
417
+ ```
418
+
419
+ #### 1.6. Thông tin giao dịch
420
+
421
+ ```python
422
+ from quantvn.vn.data import Trading
423
+
424
+ # Bảng giá nhiều mã cùng lúc
425
+ price_board = Trading.price_board(["VCB", "ACB", "TCB"])
426
+ print(price_board)
427
+ ```
428
+
429
+ **Output:**
430
+
431
+ ```python
432
+ symbol open ceiling floor ref_price high low price_change price_change_pct foreign_volume foreign_room foreign_holding_room avg_match_volume_2w
433
+ 0 VCB None None None 60500.0 None None -1400.0 -2.314050 None None None None
434
+ 1 ACB None None None 23750.0 None None -450.0 -1.894737 None None None None
435
+ 2 TCB None None None 30300.0 None None -350.0 -1.155116 None None None None
436
+ ```
437
+
438
+ #### 1.7. Quỹ mở
439
+
440
+ ```python
441
+ from quantvn.vn.data import Fund
442
+
443
+ fund = Fund()
444
+
445
+ # Danh sách tất cả quỹ
446
+ all_funds = fund.listing()
447
+ print("Danh sách tất cả quỹ")
448
+ print(all_funds.head())
449
+
450
+ # Lọc theo loại quỹ
451
+ stock_funds = fund.listing(fund_type="STOCK") # Quỹ cổ phiếu
452
+ bond_funds = fund.listing(fund_type="BOND") # Quỹ trái phiếu
453
+ balanced_funds = fund.listing(fund_type="BALANCED") # Quỹ cân bằng
454
+
455
+ print("Quỹ cổ phiếu:")
456
+ print(stock_funds[["name", "code", "nav"]].head())
457
+
458
+ # Tìm kiếm quỹ theo tên
459
+ search_result = fund.filter("RVPIF")
460
+ print("Tìm kiếm quỹ theo tên")
461
+ print(search_result)
462
+ ```
463
+
464
+ **Output:**
465
+
466
+ ```python
467
+ Danh sách tất cả quỹ
468
+ id name shortName code ... productNavChange.updateAt extra.lastNAVDate extra.lastNAV extra.currentNAV
469
+ 0 38 QUỸ ĐẦU TƯ CHỦ ĐỘNG VND VNDAF VNDAF ... 1773901367003 1773853200000 19974.77 19974.77
470
+ 1 80 QUỸ ĐẦU TƯ CỔ PHIẾU CỔ TỨC NĂNG ĐỘNG VINACAPITAL VDEF VDEF ... 1773894131379 1773766800000 12475.45 12475.45
471
+ 2 21 QUỸ ĐẦU TƯ TRÁI PHIẾU BẢO THỊNH VINACAPITAL VFF VFF ... 1773894123666 1773680400000 25857.51 25857.51
472
+ 3 37 QUỸ ĐẦU TƯ TRÁI PHIẾU VND VNDBF VNDBF ... 1773894901858 1773853200000 15770.78 15770.78
473
+ 4 41 QUỸ ĐẦU TƯ CỔ PHIẾU TĂNG TRƯỞNG BALLAD VIỆT NAM TBLF TBLF ... 1773894127776 1773680400000 11281.69 11281.69
474
+
475
+ Quỹ cổ phiếu:
476
+ name code nav
477
+ 0 QUỸ ĐẦU TƯ CHỦ ĐỘNG VND VNDAF 19974.77
478
+ 1 QUỸ ĐẦU TƯ CỔ PHIẾU CỔ TỨC NĂNG ĐỘNG VINACAPITAL VDEF 12475.45
479
+ 2 QUỸ ĐẦU TƯ CỔ PHIẾU TĂNG TRƯỞNG BALLAD VIỆT NAM TBLF 11281.69
480
+ 3 QUỸ ĐẦU TƯ CỔ PHIẾU TĂNG TRƯỞNG MIRAE ASSET VI... MAGEF 21768.81
481
+ 4 QUỸ ĐẦU TƯ THU NHẬP CHỦ ĐỘNG VCBF VCBFAIF 11613.50
482
+
483
+ Tìm kiếm quỹ theo tên
484
+ id name shortName code ... productNavChange.updateAt extra.lastNAVDate extra.lastNAV extra.currentNAV
485
+ 55 83 QUỸ ĐẦU TƯ THỊNH VƯỢNG RỒNG VIỆT RVPIF RVPF24 ... 1773894120943 1773766800000 10881.64 10881.64
486
+ ```
487
+
488
+ #### 1.8. Danh sách mã chứng khoán
489
+
490
+ ```python
491
+ from quantvn.vn.data import Listing
492
+
493
+ listing = Listing()
494
+
495
+ # Lấy danh sách mã theo sàn
496
+ symbols = listing.symbols_by_exchange()
497
+ print(f"HOSE: {len(symbols['HOSE'])} symbols")
498
+ print(f"HNX: {len(symbols['HNX'])} symbols")
499
+ print(f"UPCOM: {len(symbols['UPCOM'])} symbols")
500
+ ```
501
+
502
+ **Output:**
503
+
504
+ ```python
505
+ HOSE: 3 symbols
506
+ HNX: 0 symbols
507
+ UPCOM: 0 symbols
508
+ ```
509
+
510
+ ---
511
+
512
+ ### 2. Phái sinh VN30
513
+
514
+ ```python
515
+ from quantvn import client
516
+ client(apikey="your-apikey-here")
517
+
518
+ from quantvn.vn.data import get_derivatives_hist
519
+
520
+ # Dữ liệu VN30F1M theo phút
521
+ vn30_1m = get_derivatives_hist("VN30F1M", "1m")
522
+ print("Dữ liệu VN30F1M theo phút")
523
+ print(vn30_1m.head())
524
+
525
+ # Dữ liệu VN30F1M theo 5 phút
526
+ vn30_5m = get_derivatives_hist("VN30F1M", "5m")
527
+ print("Dữ liệu VN30F1M theo 5 phút")
528
+ print(vn30_5m.head())
529
+
530
+ # Dữ liệu VN30F1M theo 15 phút
531
+ vn30_15m = get_derivatives_hist("VN30F1M", "15m")
532
+ print("Dữ liệu VN30F1M theo 15 phút")
533
+ print(vn30_15m.head())
534
+
535
+ # Các resolution hỗ trợ: "1m", "5m", "15m"
536
+ ```
537
+
538
+ **Output:**
539
+
540
+ ```python
541
+ Dữ liệu VN30F1M theo phút
542
+ Date time Open High Low Close volume Datetime
543
+ 0 2018-08-13 09:01:00 943.0 943.1 942.9 943.1 220.0 2018-08-13 09:01:00
544
+ 1 2018-08-13 09:02:00 943.0 943.6 943.0 943.5 121.0 2018-08-13 09:02:00
545
+ 2 2018-08-13 09:03:00 943.3 943.4 943.3 943.4 135.0 2018-08-13 09:03:00
546
+ 3 2018-08-13 09:04:00 943.2 943.2 943.0 943.1 361.0 2018-08-13 09:04:00
547
+ 4 2018-08-13 09:05:00 943.1 943.1 942.9 943.0 343.0 2018-08-13 09:05:00
548
+
549
+ Dữ liệu VN30F1M theo 5 phút
550
+ Date time Open High Low Close volume Datetime
551
+ 0 2018-08-13 09:00:00 943.5 943.6 942.9 943.1 1812.0 2018-08-13 09:00:00
552
+ 1 2018-08-13 09:05:00 943.1 943.5 942.9 943.3 1323.0 2018-08-13 09:05:00
553
+ 2 2018-08-13 09:10:00 943.2 943.3 942.6 943.1 1207.0 2018-08-13 09:10:00
554
+ 3 2018-08-13 09:15:00 943.1 943.1 942.3 942.6 1196.0 2018-08-13 09:15:00
555
+ 4 2018-08-13 09:20:00 942.6 943.7 942.4 943.7 1765.0 2018-08-13 09:20:00
556
+
557
+ Dữ liệu VN30F1M theo 15 phút
558
+ Date time Open High Low Close volume Datetime
559
+ 0 2018-08-13 09:00:00 943.5 943.6 942.6 943.1 4342.0 2018-08-13 09:00:00
560
+ 1 2018-08-13 09:15:00 943.1 945.9 942.3 945.3 5430.0 2018-08-13 09:15:00
561
+ 2 2018-08-13 09:30:00 945.2 945.5 943.3 944.5 4933.0 2018-08-13 09:30:00
562
+ 3 2018-08-13 09:45:00 944.5 946.4 944.3 946.0 4254.0 2018-08-13 09:45:00
563
+ 4 2018-08-13 10:00:00 945.9 946.3 944.5 945.2 4336.0 2018-08-13 10:00:00
564
+ ```
565
+
566
+ ---
567
+
568
+ ---
569
+
570
+ ### 3. Technical Analysis & Fundamental Features
571
+
572
+ #### 3.1. Thêm chỉ báo kỹ thuật
573
+
574
+ ```python
575
+ from quantvn.vn.data import add_all_ta_features, get_stock_hist
576
+
577
+ # Lấy dữ liệu
578
+ df = get_stock_hist("VIC", resolution="1H")
579
+
580
+ # Thêm tất cả chỉ báo kỹ thuật
581
+ df_with_ta = add_all_ta_features(df)
582
+
583
+ # DataFrame sẽ có thêm các cột: RSI, MACD, Bollinger Bands, etc.
584
+ print(df_with_ta.columns)
585
+ print(df_with_ta.head())
586
+ ```
587
+
588
+ **Output:**
589
+
590
+ ```python
591
+ ['Date', 'time', 'Open', 'High', 'Low', 'Close', 'volume', 'volume_adi', 'volume_obv', 'volume_cmf',...'sma_fast', 'sma_slow', 'ema_fast',
592
+ 'ema_slow', 'bb_middle', 'bb_high','bb_low', 'bb_width', 'bb_percent', 'atr']
593
+
594
+ Date time Open High Low Close volume ... ema_slow bb_middle bb_high bb_low bb_width bb_percent atr
595
+ 0 2023-03-20 09:00:00 26.50 26.60 26.20 26.30 188600.0 ... 26.300000 26.3000 26.300000 26.300000 0.000000 0.000000 0.0
596
+ 1 2023-03-20 10:00:00 26.25 26.40 26.00 26.10 319300.0 ... 26.285185 26.2000 26.400000 26.000000 1.526718 0.250000 0.0
597
+ 2 2023-03-20 11:00:00 26.05 26.10 25.85 25.90 294700.0 ... 26.256653 26.1000 26.426599 25.773401 2.502672 0.193814 0.0
598
+ 3 2023-03-20 13:00:00 25.90 25.95 25.70 25.75 928800.0 ... 26.219123 26.0125 26.427078 25.597922 3.187530 0.183413 0.0
599
+ 4 2023-03-20 14:00:00 25.80 26.40 25.70 26.40 1630900.0 ... 26.232521 26.0900 26.573322 25.606678 3.705035 0.820697 0.0
600
+ ```
601
+
602
+ #### 3.2. Thêm chỉ số tài chính cơ bản
603
+
604
+ ```python
605
+ from quantvn.vn.data import add_all_fund_features, get_stock_hist
606
+
607
+ # Lấy dữ liệu
608
+ df = get_stock_hist("HPG", resolution="1H")
609
+
610
+ # Thêm các chỉ số tài chính (PE, PB, ROE, ROA, etc.)
611
+ df_with_fund = add_all_fund_features(df, symbol="HPG")
612
+
613
+ print(df_with_fund.columns)
614
+ print(df_with_fund.head())
615
+ ```
616
+
617
+ **Output:**
618
+
619
+ ```python
620
+ ['Date', 'time', 'Open', 'High', 'Low', 'Close', 'volume', 'ticker','year', 'quarter']
621
+
622
+ Date time Open High Low Close volume ticker year quarter
623
+ 0 2023-03-20 09:00:00 15.46 15.61 15.37 15.57 3598400.0 HPG 2023 1
624
+ 1 2023-03-20 10:00:00 15.61 15.61 15.42 15.49 3128900.0 HPG 2023 1
625
+ 2 2023-03-20 11:00:00 15.49 15.49 15.37 15.42 1437100.0 HPG 2023 1
626
+ 3 2023-03-20 13:00:00 15.42 15.42 15.19 15.22 7626000.0 HPG 2023 1
627
+ 4 2023-03-20 14:00:00 15.22 15.30 15.15 15.15 7198500.0 HPG 2023 1
628
+ ```
629
+
630
+ #### 3.3. Lấy từng chỉ số cụ thể
631
+
632
+ ```python
633
+ from quantvn import client
634
+ client(apikey="your-apikey-here")
635
+
636
+ from quantvn.vn.data import fund_feature
637
+
638
+ # Lấy ROE
639
+ roe_data = fund_feature("roe", "VCB")
640
+ print(roe_data.head())
641
+
642
+ ```
643
+
644
+ **Output:**
645
+
646
+ ```python
647
+ Date time Open High Low Close Volume roe
648
+ 0 2023-03-20 09:00:00 50.04 50.32 49.77 50.04 189400.0 NaN
649
+ 1 2023-03-20 10:00:00 50.04 50.04 49.54 49.65 170900.0 NaN
650
+ 2 2023-03-20 11:00:00 49.65 49.71 49.48 49.48 115500.0 NaN
651
+ 3 2023-03-20 13:00:00 49.48 49.59 48.86 48.92 189800.0 NaN
652
+ 4 2023-03-20 14:00:00 48.92 49.15 47.85 47.85 367000.0 NaN
653
+ ```
654
+
655
+ **Các chỉ số khả dụng:**
656
+
657
+ - `earningPerShare` (EPS)
658
+ - `bookValuePerShare` (BVPS)
659
+ - `roe` (Return on Equity)
660
+ - `roa` (Return on Assets)
661
+ - `priceToEarning` (P/E)
662
+ - `priceToBook` (P/B)
663
+ - Và nhiều chỉ số khác...
664
+
665
+ ---
666
+
667
+ ### 4. Backtesting & Performance Analysis
668
+
669
+ #### 4.0. Quy tắc khớp lệnh (thay đổi từ bản 0.2.0)
670
+
671
+ Vị thế ghi ở một nến được quyết định bằng giá đóng cửa của nến đó, nên giá sớm nhất có thể giao dịch là giá **mở cửa của nến kế tiếp**. Từ bản 0.2.0, các lớp backtest tính theo đúng trình tự này:
672
+
673
+ - Vị thế của nến `t` được khớp tại `Open` của nến `t+1`.
674
+ - Mỗi nến ghi nhận lãi lỗ của vị thế cũ từ giá đóng cửa trước đến giá khớp, rồi của vị thế mới từ giá khớp đến giá đóng cửa.
675
+ - Phí được tính tại nến khớp, trên giá khớp.
676
+ - Chi phí thị trường Việt Nam dùng cùng mức với dịch vụ Track Record. Phái sinh VN30: 1,5 bp giá trị hợp đồng mỗi chiều (phí sở, phí bù trừ, thuế, môi giới và nửa bước giá), khoảng 0,28 điểm khi chỉ số ở 1.850. Cổ phiếu: 0,15% mỗi chiều, thêm 0,1% thuế khi bán và nửa bước giá. Các bản cũ chỉ tính phí sở 2.700 đồng cho phái sinh, khoảng một phần mười chi phí thực.
677
+ - Nếu dữ liệu không có cột `Open`, vị thế được khớp tại giá đóng cửa của nến kế tiếp và thư viện phát cảnh báo.
678
+
679
+ Các bản đến 0.1.25 tính lãi lỗ của vị thế ngay từ giá đóng cửa của chính nến ra quyết định, tức là một mức giá đã qua. Vì vậy **kết quả backtest của cùng một chiến lược sẽ khác so với bản cũ**, nhất là với chiến lược giao dịch nhiều. Con số mới là con số có thể đạt được khi chạy thật; các ví dụ đầu ra bên dưới được tạo từ bản cũ nên chỉ minh họa định dạng.
680
+
681
+ #### 4.1. Backtest cho phái sinh
682
+
683
+ ```python
684
+ from quantvn import client
685
+ client(apikey="your-apikey-here")
686
+
687
+ from quantvn.vn.metrics import Backtest_Derivates
688
+ from quantvn.vn.data import get_derivatives_hist
689
+ import pandas as pd
690
+
691
+ # Lấy dữ liệu
692
+ df = get_derivatives_hist("VN30F1M", "5m")
693
+
694
+ # Tạo tín hiệu giao dịch đơn giản (ví dụ: MA crossover)
695
+ df["ma_short"] = df["Close"].rolling(20).mean()
696
+ df["ma_long"] = df["Close"].rolling(50).mean()
697
+
698
+ # Position: 1 (long), -1 (short), 0 (no position)
699
+ df["position"] = 0
700
+ df.loc[df["ma_short"] > df["ma_long"], "position"] = 1
701
+ df.loc[df["ma_short"] < df["ma_long"], "position"] = -1
702
+ print(df.iloc[100:105])
703
+
704
+ # Chạy backtest (PnL sau phí)
705
+ backtest = Backtest_Derivates(df, pnl_type="after_fees")
706
+
707
+ # Xem PnL tích lũy
708
+ pnl = backtest.PNL()
709
+ print(f"Final PnL: {pnl.iloc[-1]:,.2f} VND")
710
+
711
+ # PnL theo ngày
712
+ daily_pnl = backtest.daily_PNL()
713
+ print(daily_pnl.tail())
714
+
715
+ # Ước tính vốn tối thiểu
716
+ min_capital = backtest.estimate_minimum_capital()
717
+ print(f"Minimum capital needed: {min_capital:,.0f} VND")
718
+
719
+ # Vẽ biểu đồ PnL
720
+ backtest.plot_PNL("VN30F1M - MA Crossover Strategy")
721
+ ```
722
+
723
+ **Output**
724
+
725
+ ```python
726
+ Date time Open High Low Close volume Datetime ma_short ma_long position
727
+ 100 2018-08-15 09:10:00 959.3 960.5 959.3 960.4 927.0 2018-08-15 09:10:00 958.645 956.424 1
728
+ 101 2018-08-15 09:15:00 960.3 961.1 960.3 960.7 1413.0 2018-08-15 09:15:00 958.930 956.538 1
729
+ 102 2018-08-15 09:20:00 960.8 960.8 960.1 960.3 1172.0 2018-08-15 09:20:00 959.135 956.606 1
730
+ 103 2018-08-15 09:25:00 960.3 960.3 959.0 959.0 1735.0 2018-08-15 09:25:00 959.290 956.670 1
731
+ 104 2018-08-15 09:30:00 959.3 960.1 959.2 960.1 1271.0 2018-08-15 09:30:00 959.460 956.762 1
732
+
733
+ Final PnL: 1,783.93 VND
734
+
735
+ 2022-12-26 1809.1830
736
+ 2022-12-27 1823.1290
737
+ 2022-12-28 1816.6955
738
+ 2022-12-29 1794.6620
739
+ 2022-12-30 1783.9285
740
+
741
+ Minimum capital needed: 980 VND
742
+ ```
743
+
744
+ **Tham số:**
745
+
746
+ - `pnl_type` (str):
747
+ - `"raw"`: PnL thô (chưa trừ phí)
748
+ - `"after_fees"`: PnL sau khi trừ phí giao dịch
749
+
750
+ #### 4.2. Backtest cho cổ phiếu
751
+
752
+ ```python
753
+ from quantvn.vn.metrics import Backtest_Stock
754
+ from quantvn.vn.data import get_stock_hist
755
+
756
+ # Lấy dữ liệu
757
+ df = get_stock_hist("VIC", resolution="1H")
758
+
759
+ # Tạo chiến lược đơn giản
760
+ df["ma20"] = df["Close"].rolling(20).mean()
761
+ df["ma50"] = df["Close"].rolling(50).mean()
762
+
763
+ # Position: số lượng cổ phiếu (ví dụ: 100 cổ)
764
+ df["position"] = 0
765
+ df.loc[df["ma20"] > df["ma50"], "position"] = 100
766
+ print(df.iloc[100:105])
767
+
768
+ # Backtest
769
+ backtest = Backtest_Stock(df, pnl_type="after_fees")
770
+ pnl = backtest.PNL()
771
+ print(pnl.iloc[100:105])
772
+
773
+ # Vẽ PnL
774
+ backtest.plot_PNL("VIC - MA(20/50) Strategy")
775
+ ```
776
+
777
+ **Output:**
778
+
779
+ ```python
780
+ Date time Open High Low Close volume ma20 ma50 position
781
+ 100 2023-04-17 09:00:00 26.45 26.50 26.25 26.25 196700.0 26.4800 27.264 0
782
+ 101 2023-04-17 10:00:00 26.30 26.40 26.25 26.25 246900.0 26.4700 27.201 0
783
+ 102 2023-04-17 11:00:00 26.30 26.30 26.20 26.20 156200.0 26.4525 27.138 0
784
+ 103 2023-04-17 13:00:00 26.25 26.40 26.25 26.30 311700.0 26.4425 27.089 0
785
+ 104 2023-04-17 14:00:00 26.30 26.35 26.25 26.25 331600.0 26.4175 27.039 0
786
+
787
+ datetime
788
+ 2023-04-17 09:00:00 -70.395
789
+ 2023-04-17 10:00:00 -70.395
790
+ 2023-04-17 11:00:00 -70.395
791
+ 2023-04-17 13:00:00 -70.395
792
+ 2023-04-17 14:00:00 -70.395
793
+ ```
794
+
795
+ #### 4.3. Metrics - Đánh giá hiệu suất
796
+
797
+ ```python
798
+ from quantvn import client
799
+ client(apikey="your-apikey-here")
800
+
801
+ from quantvn.vn.metrics import Metrics, Backtest_Derivates
802
+ from quantvn.vn.data import get_derivatives_hist
803
+
804
+ # Giả sử đã có backtest
805
+ df = get_derivatives_hist("VN30F1M", "5m")
806
+ # ... tạo position ...
807
+ df["position"] = 1 # Ví dụ đơn giản: long cả ngày
808
+
809
+ backtest = Backtest_Derivates(df, pnl_type="after_fees")
810
+ metrics = Metrics(backtest)
811
+
812
+ # Các chỉ số hiệu suất
813
+ print(f"Sharpe Ratio: {metrics.sharpe():.3f}")
814
+ print(f"Sortino Ratio: {metrics.sortino():.3f}")
815
+ print(f"Calmar Ratio: {metrics.calmar():.3f}")
816
+ print(f"Max Drawdown: {metrics.max_drawdown()*100:.2f}%")
817
+ print(f"Win Rate: {metrics.win_rate()*100:.2f}%")
818
+ print(f"Profit Factor: {metrics.profit_factor():.3f}")
819
+ print(f"Average Win: {metrics.avg_win():,.0f} VND")
820
+ print(f"Average Loss: {metrics.avg_loss():,.0f} VND")
821
+ print(f"Risk of Ruin: {metrics.risk_of_ruin():.4f}")
822
+
823
+ # Value at Risk (95% confidence)
824
+ var_95 = metrics.value_at_risk(confidence_level=0.95)
825
+ print(f"VaR (95%): {var_95:,.0f} VND")
826
+ ```
827
+
828
+ **Output:**
829
+
830
+ ```python
831
+ Sharpe Ratio: 0.019
832
+ Sortino Ratio: 0.024
833
+ Calmar Ratio: 0.434
834
+ Max Drawdown: -72.36%
835
+ Win Rate: 51.78%
836
+ Profit Factor: 1.003
837
+ Average Win: 11 VND
838
+ Average Loss: -12 VND
839
+ Risk of Ruin: 1.0061
840
+ VaR (95%): 25 VND
841
+ ```
842
+
843
+ **Các metrics có sẵn:**
844
+
845
+ - `sharpe()`: Sharpe Ratio
846
+ - `sortino()`: Sortino Ratio
847
+ - `calmar()`: Calmar Ratio
848
+ - `max_drawdown()`: Drawdown tối đa
849
+ - `win_rate()`: Tỷ lệ thắng
850
+ - `profit_factor()`: Tỷ số lợi nhuận
851
+ - `avg_win()`: Lãi trung bình
852
+ - `avg_loss()`: Lỗ trung bình
853
+ - `avg_return()`: Return trung bình
854
+ - `volatility()`: Độ biến động
855
+ - `value_at_risk(confidence_level)`: Value at Risk
856
+ - `risk_of_ruin()`: Xác suất phá sản
857
+
858
+ ### 5. Viết chiến lược và Paper trading
859
+
860
+ Phần này dành cho người tự viết chiến lược để chạy trên QuantVN. Hai module `quantvn.strategy` và `quantvn.paper` giúp bạn biết trước chiến lược sẽ chạy thế nào trên nền tảng, và kết quả sẽ được tính ra sao.
861
+
862
+ #### 5.1. Chiến lược là gì
863
+
864
+ Một chiến lược là một file Python có hàm `gen_position(df)` ở cấp ngoài cùng:
865
+
866
+ ```python
867
+ import pandas as pd
868
+
869
+ def gen_position(df):
870
+ df["ma"] = df["Close"].rolling(20).mean()
871
+ df["position"] = (df["Close"] > df["ma"]).astype(int) * 2 - 1 # 1: mua, -1: bán
872
+ return df
873
+ ```
874
+
875
+ - `df` có các cột `Datetime, Date, time, Open, High, Low, Close, volume`. `Datetime` là thời điểm **mở** nến, giờ Việt Nam.
876
+ - Hàm trả về DataFrame có cột `position`. Giá trị ở dòng cuối là quyết định cho nến vừa đóng.
877
+ - `position` là **tỷ trọng vốn**: từ -1 đến 1 với phái sinh VN30, từ 0 đến 1 với cổ phiếu (không bán khống). Giá trị ngoài khoảng này bị cắt về biên. Đây không phải số hợp đồng hay số cổ phiếu.
878
+
879
+ Mỗi khi một nến đóng, nền tảng gọi `gen_position` với các nến của **phiên giao dịch trước và hôm nay**, tính đến nến vừa đóng. Khung nến: 1 phút với `VN30F1M`, 5 phút với `VN30F5M`, 15 phút với `VN30F15M`, 5 phút với cổ phiếu.
880
+
881
+ #### 5.2. Kiểm tra trước khi tải lên
882
+
883
+ ```python
884
+ from quantvn import strategy
885
+
886
+ bars = strategy.candles("VN30F1M") # nến từ đúng nguồn nền tảng dùng, không cần API key
887
+ report = strategy.check(gen_position, bars, symbol="VN30F1M")
888
+ print(report)
889
+ ```
890
+
891
+ `check` gọi chiến lược tại nhiều thời điểm trong ngày, mỗi lần chỉ đưa các nến đã có ở thời điểm đó, rồi so với vị thế mà chính hàm này tính ra khi được xem cả ngày. Báo cáo cho biết:
892
+
893
+ - **Nhìn trước tương lai (look-ahead).** Nếu hai kết quả khác nhau, backtest của bạn đang dùng dữ liệu chưa tồn tại (ví dụ `shift(-1)`, hoặc chuẩn hóa theo cả chuỗi). Kết quả backtest như vậy sẽ không lặp lại khi chạy thật.
894
+ - **Lỗi hợp đồng.** Thiếu cột `position`, vị thế là `NaN` (thường do chưa đủ nến cho chỉ báo), hoặc hàm báo lỗi.
895
+ - **Vị thế bị cắt.** Giá trị vượt khoảng cho phép.
896
+ - **Chạy chậm.** Mỗi lần gọi bị dừng sau 10 giây CPU; nên giữ dưới một giây.
897
+
898
+ `report.live` là bảng quyết định theo từng nến, `report.differences` liệt kê các nến có khác biệt. Muốn xem toàn bộ quyết định trong ngày, dùng `strategy.replay(gen_position, bars, "VN30F1M")`.
899
+
900
+ #### 5.3. Kiểm tra file chiến lược
901
+
902
+ Chiến lược tải lên chạy trong sandbox: không có mạng, không ghi được file ngoài thư mục tạm, và mỗi nến là một tiến trình mới. Vì vậy mọi lệnh nằm ngoài hàm đều chạy lại ở mỗi nến, và không có gì được nhớ giữa hai lần gọi.
903
+
904
+ ```python
905
+ print(strategy.validate_script("my_strategy.py"))
906
+
907
+ gen_position = strategy.load_script("my_strategy.py") # nạp file theo cách sandbox nạp
908
+ print(strategy.check(gen_position, bars))
909
+ ```
910
+
911
+ `validate_script` đọc mã nguồn (không chạy) và báo những chỗ sẽ hỏng trong sandbox: import thư viện cần mạng (`requests`, `yfinance`...), gọi các hàm lấy dữ liệu trực tuyến của SDK, `input()`, thiếu hàm `gen_position`. Nó cũng cảnh báo khi phần backtest và vẽ biểu đồ nằm ngoài hàm; hãy đặt phần đó dưới `if __name__ == "__main__":`.
912
+
913
+ Trong sandbox, `client(apikey=...)` không làm gì, còn `get_derivatives_hist` / `get_stock_hist` trả về đúng bộ nến mà `gen_position` nhận được. Hãy dùng tham số `df` thay vì tự lấy dữ liệu.
914
+
915
+ #### 5.4. Mô phỏng khớp lệnh trung thực
916
+
917
+ Một vị thế chỉ được biết **sau khi** nến đóng, nên không ai mua bán được ở chính giá đóng cửa đó. Từ bản 0.2.0, mọi lớp backtest của thư viện (`Backtest_Derivates`, `Backtest_Stock`, `Backtest_Crypto`, `Backtest_US_Stock`, `TradingBacktest`) khớp vị thế tại giá **mở cửa** của nến sau (mục 4.0). `paper.simulate` dùng cùng quy tắc đó, nhưng tính theo cách của dịch vụ Track Record: vị thế là tỷ trọng vốn, vốn bắt đầu từ 1 và cộng dồn theo lãi kép, chi phí lấy theo từng thị trường.
918
+
919
+ ```python
920
+ from quantvn import paper
921
+
922
+ df = gen_position(bars.copy())
923
+ result = paper.simulate(df, market="VN_DERIVATIVE") # khớp ở giá mở cửa nến kế tiếp
924
+ print(result)
925
+ print(paper.simulate(df, market="VN_DERIVATIVE", delay_bars=2)) # chậm thêm một nến, gần với chạy thật ở khung 1 phút
926
+ ```
927
+
928
+ - Chi phí mặc định lấy theo dịch vụ: phái sinh 1,5 bp mỗi chiều; cổ phiếu 15 bp mỗi chiều, thêm 10 bp thuế khi bán và nửa bước giá cho chênh lệch mua bán.
929
+ - `result.nav` là vốn theo từng nến (bắt đầu từ 1), `result.fills` là các lần khớp, `result.daily` là lợi nhuận theo ngày, `result.stats` gồm lợi nhuận, Sharpe, mức sụt giảm tối đa.
930
+ - `result.notes` ghi rõ những gì mô phỏng này **chưa** tính: quy định T+2 và biên độ giá với cổ phiếu, việc chuyển hợp đồng hằng tháng với phái sinh. Dịch vụ Track Record có áp dụng các quy định đó.
931
+
932
+ #### 5.5. Gửi vị thế lên Track Record
933
+
934
+ Nếu bạn tự chạy chiến lược trên máy của mình, chương trình chỉ cần gửi vị thế. Máy chủ ghi lại thời điểm nhận và tự tính kết quả từ nguồn giá của nó: mỗi tín hiệu khớp tại giá mở cửa của nến 1 phút đầu tiên sau khi máy chủ nhận được. Giá do chương trình của bạn gửi lên không được dùng.
935
+
936
+ ```python
937
+ from quantvn.paper import TrackRecord
938
+
939
+ tr = TrackRecord(email="ban@example.com", api_key="API_KEY_CUA_BAN")
940
+ tr.send("bot-dau-tien", "VN30F1M", 1) # mua toàn bộ vốn
941
+ tr.send("bot-dau-tien", "VN30F1M", 0) # về trạng thái không nắm giữ
942
+
943
+ print(tr.bots()) # các bot và thống kê mới nhất
944
+ print(tr.record("bot-dau-tien")["fills"]) # các lần khớp: thời điểm, giá, vị thế trước/sau, phí
945
+ ```
946
+
947
+ - `email` là email tài khoản QuantVN sở hữu API key.
948
+ - Kết quả được tính lại mỗi giờ, nên bot mới sẽ chưa có số liệu ngay.
949
+ - `tr.assets()` trả về các mã đang nhận tín hiệu, kèm khoảng vị thế và chi phí của từng thị trường.
950
+ - `tr.publish(ten_bot)` công khai thành tích. Việc công khai là vĩnh viễn: về sau có thể đánh dấu rút lại, nhưng bản ghi vẫn xem được.
951
+ - Khi máy chủ từ chối, thư viện báo `paper.TrackRecordError` với `code` như `rate_limited`, `position_out_of_range`, `bot_limit_reached`.
952
+
953
+ ---
954
+
955
+ ## Ví dụ thực tế
956
+
957
+ Xem cách triển khai và chạy trực tiếp trên Google Colab:
958
+ https://colab.research.google.com/drive/1pEVYivKMNwRVxERy4mb9ujzoHrh7avJL?usp=sharing
959
+
960
+ ---
961
+
962
+ ## Testing
963
+
964
+ Chạy tests:
965
+
966
+ ```bash
967
+ # Cài đặt dependencies cho dev
968
+ pip install -e ".[dev]"
969
+
970
+ # Chạy tests
971
+ pytest tests/
972
+
973
+ # Chạy với coverage
974
+ pytest --cov=quantvn tests/
975
+ ```
976
+
977
+ ---
978
+
979
+ ## Đóng góp
980
+
981
+ Chúng tôi hoan nghênh mọi đóng góp! Để đóng góp:
982
+
983
+ 1. Fork repository
984
+ 2. Tạo branch mới (`git checkout -b feature/AmazingFeature`)
985
+ 3. Commit changes (`git commit -m 'Add some AmazingFeature'`)
986
+ 4. Push to branch (`git push origin feature/AmazingFeature`)
987
+ 5. Mở Pull Request
988
+
989
+ Vui lòng đọc [CONTRIBUTING.md](CONTRIBUTING.md) để biết thêm chi tiết.
990
+
991
+ ---
992
+
993
+ ## Tuyên bố miễn trách nhiệm
994
+
995
+ **QuantVN** được phát triển nhằm phục vụ mục đích nghiên cứu và học tập.
996
+
997
+ - Dữ liệu cung cấp có thể không đầy đủ hoặc không chính xác 100%
998
+ - 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
999
+ - 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
1000
+
1001
+ **Lưu ý quan trọng:**
1002
+
1003
+ - Luôn kiểm tra và xác thực dữ liệu trước khi sử dụng
1004
+ - Backtesting không đảm bảo kết quả trong tương lai
1005
+ - Quản lý rủi ro là trách nhiệm của người dùng
1006
+
1007
+ ---
1008
+
1009
+ ## Giấy phép
1010
+
1011
+ Dự án này được phát hành theo giấy phép **MIT License**. Xem file [LICENSE](LICENSE) để biết thêm chi tiết.
1012
+
1013
+ ---
1014
+
1015
+ ## Changelog
1016
+
1017
+ ### Version 0.2.0
1018
+
1019
+ - Thêm `quantvn.strategy`: lấy nến theo đúng khung nền tảng dùng, chạy thử chiến lược như khi chạy thật (`replay`), phát hiện nhìn trước tương lai (`check`), kiểm tra file trước khi tải lên (`validate_script`)
1020
+ - Thêm `quantvn.paper`: mô phỏng khớp lệnh tại giá mở cửa nến kế tiếp (`simulate`) và client của dịch vụ Track Record (`TrackRecord`)
1021
+ - Mọi lệnh gọi mạng trong thư viện đều có thời gian chờ tối đa 30 giây
1022
+ - **Thay đổi kết quả backtest**: mọi lớp backtest khớp vị thế tại giá mở cửa của nến kế tiếp thay vì giá đóng cửa của nến ra quyết định (mục 4.0). Chi phí phái sinh và cổ phiếu Việt Nam được tính đủ theo mức của Track Record
1023
+ - Thêm bộ test (`pytest tests/`)
1024
+
1025
+ ### Version 0.1.5
1026
+
1027
+ - Thêm hỗ trợ cryptocurrency data từ Binance
1028
+ - Cải thiện performance cho `get_stock_hist()`
1029
+ - Sửa lỗi timezone cho dữ liệu phái sinh
1030
+ - Thêm các metrics mới: Risk of Ruin, VaR
1031
+
1032
+ ### Version 0.1.4
1033
+
1034
+ - Thêm module backtesting cho cổ phiếu
1035
+ - Hỗ trợ Take Profit/Stop Loss
1036
+ - Cải thiện documentation
1037
+
1038
+ ---
1039
+
1040
+ ## Hỗ trợ
1041
+
1042
+ - **GitHub Issues**: https://github.com/quantvn/quantvn-vn-markets/issues
1043
+ - **Documentation**: https://quantvn.gitbook.io/quantvn-docs
1044
+
1045
+ ---
1046
+
1047
+ **QuantVN** - Công cụ phân tích tài chính mạnh mẽ cho thị trường Việt Nam