Vnstock

https://vnstocks.com/docs
Admin
Vnstock is a powerful and comprehensive stock market API for Vietnam that provides financial data...
Tokens:165,786
Snippets:1,229
Trust Score:6.1
Update:2 months ago
Show doc for...
Tokens:
Raw
### Initialize Analytics Object

Source: https://vnstocks.com/docs/vnstock-data/analytics-layer-v3

Setup the Analytics instance and configure the target market index.

```Python
from vnstock_data import Analytics

ana = Analytics()
val = ana.valuation("VNINDEX")  # Cấu hình index mục tiêu (Mặc định: "VNINDEX")
```

--------------------------------

### Fundamental Layer Syntax Examples

Source: https://vnstocks.com/docs/vnstock-data/fundamental-layer-v3

Demonstrates the two supported syntax patterns for accessing fundamental data.

```python
fun.equity("TCB").cash_flow()
```

```python
fun.equity.cash_flow("TCB")
```

--------------------------------

### Retrieve Valuation Metrics

Source: https://vnstocks.com/docs/vnstock-data/analytics-layer-v3

Examples of fetching historical P/E, P/B, and evaluation data for specific indices and durations.

```Python
from vnstock_data import Analytics
ana = Analytics()

df_pe = ana.valuation("VNINDEX").pe(duration="1Y")
print(df_pe.tail())
df_pe_hnx = ana.valuation("HNX").pe(duration="5Y")

df_pb = ana.valuation("VNINDEX").pb(duration="1Y")

df_eval = ana.valuation("VNINDEX").evaluation(duration="5Y")
print(df_eval.head())
```

--------------------------------

### Access Warrant Summary

Source: https://vnstocks.com/docs/vnstock-data/market-layer-v3

Get fundamental information such as maturity date, conversion ratio, and strike price.

```python
summary_warrant = mkt.warrant("CACB2511").summary()
```

--------------------------------

### GET /api/agent/docs

Source: https://vnstocks.com/docs/vnstock-insider-api/co-che-agent-skills-docs

Recursively scans the public documentation directory on the website and returns the content in Markdown format.

```APIDOC
## GET /api/agent/docs

### Description
Recursively scans the public documentation directory on the website and returns the content in Markdown format.

### Method
GET

### Endpoint
/api/agent/docs

### Headers
- **x-api-key** or **Authorization: Bearer** - Required - Authentication token.
```

--------------------------------

### Listing Module Initialization

Source: https://vnstocks.com/docs/vnstock-data/trang-thai-niem-yet

Demonstrates how to initialize the Listing module either as a general wrapper or by specifying a data source.

```APIDOC
## Listing Initialization

### Description
Initializes the Listing module to access market data. Use the general wrapper for index-related data or specify a source (e.g., 'VCI', 'KBS') for detailed symbol and industry lookups.

### Usage
```python
from vnstock_data import Listing

# General wrapper (for indices)
lst_common = Listing(show_log=False)
df_indices = lst_common.all_indices()

# Source-specific (for symbols, industries, etc.)
lst_vci = Listing(source='VCI')
df_symbols = lst_vci.all_symbols()
```
```

--------------------------------

### Retrieve ETF Real-time Quote

Source: https://vnstocks.com/docs/vnstock-data/market-layer-v3

Gets the current price and liquidity status for an ETF.

```python
quote_etf = mkt.etf("E1VFVN30").quote()
```

--------------------------------

### Deprecation Warning Message

Source: https://vnstocks.com/docs/vnstock-data/macro-layer-v3

Example of the warning message displayed when using legacy methods.

```text
[DEPRECATED] Macro.interest_rate() sẽ bị xóa sau ngày 31/8/2026. 
Vui lòng sử dụng Macro().currency().interest_rate() thay thế. | 
Macro.interest_rate() is deprecated and will be removed after 31/8/2026. 
Please use Macro().currency().interest_rate() instead.
```

--------------------------------

### Reference Initialization

Source: https://vnstocks.com/docs/vnstock/tra-cuu-thong-tin-tham-chieu-reference

How to initialize the Reference object to access market data tools.

```APIDOC
## Initialization

### Description
Initialize the Reference object to start using market data tools.

### Code
```python
from vnstock import Reference
ref = Reference()
```
```

--------------------------------

### Retrieve Global Macro Indicators

Source: https://vnstocks.com/docs/vnstock-data/macro-layer-v3

Demonstrates how to initialize the Macro class and fetch bond yields, Fed rates, and global indices like DXY.

```python
from vnstock_data import Macro

mac = Macro()

df_bond = mac.global.bond_yield(market="VN", tenor="10Y")

df_fed = mac.global.fed_rate()

df_dxy = mac.global.index(symbol="DXY")
```

--------------------------------

### Get Order Details

Source: https://vnstocks.com/docs/vnstock/api-dat-lenh-giao-dich-dnse

Query the specific details of an existing order using its unique order ID.

```python
client.order_detail(order_id='MÃ_LỆNH_CỦA_BẠN', sub_account='MÃ_TIỂU_KHOẢN_CỦA_BẠN', asset_type='stock')
```

--------------------------------

### Sử dụng Unified UI

Source: https://vnstocks.com/docs/vnstock-data/kien-truc-thu-vien

Sử dụng giao diện hợp nhất với cơ chế gọi chuỗi lệnh (method chaining) để truy xuất dữ liệu thị trường.

```python
from vnstock_data import Market, Reference, Fundamental

# Ví dụ tra cứu giá lịch sử thông qua Market Layer
df = Market.quote(symbol="VCI") \
           .history(start="2024-02-01", end="2025-04-18", interval="1D")
```

--------------------------------

### Macro.retail()

Source: https://vnstocks.com/docs/vnstock-data/kinh-te-vi-mo

Retrieves Retail Sales data.

```APIDOC
## Macro.retail()

### Description
Retrieves retail sales data.

### Parameters
- **start** (str) - Optional - Start date (format: "YYYY-MM").
- **end** (str) - Optional - End date (format: "YYYY-MM").
- **period** (str) - Required - "month" or "year".
```

--------------------------------

### Retrieve Currency and Interest Rate Data

Source: https://vnstocks.com/docs/vnstock-data/macro-layer-v3

Demonstrates how to fetch exchange rates and interest rates using the macro.currency module with various period and format configurations.

```python
from vnstock_data import Macro

mac = Macro()

df_exr = mac.currency().exchange_rate(
    start="2026-02-06",
    end="2026-03-06",
    period="day"
)
print(df_exr[['time', 'USD', 'EUR', 'JPY']])
df_exr_m = mac.currency().exchange_rate(period="month", length=12)
print(df_exr_m[['time', 'USD', 'EUR']].tail())

df_ir = mac.currency().interest_rate(
    period="day",
    length=365  # 1 năm gần nhất
)
print(df_ir[['time', 'lending_rate', 'deposit_rate']])
df_ir_long = mac.currency().interest_rate(period="month", format="long")
print(df_ir_long[['date', 'rate_type', 'rate_value']].head(10))
```

--------------------------------

### Retrieve Current Futures Quote

Source: https://vnstocks.com/docs/vnstock-data/market-layer-v3

Gets the latest matched price, open interest (OI), and basis for a futures contract.

```python
quote_vn30f = mkt.futures("VN30F2503").quote()
```

--------------------------------

### Adapter API Data Call

Source: https://vnstocks.com/docs/vnstock-data/data-sources

Example of a data request requiring an explicit source parameter for Adapter API sources.

```python
Quote(source='cafef', symbol='VIC').history()
```

--------------------------------

### TopStock Class Initialization

Source: https://vnstocks.com/docs/vnstock-data/dinh-gia-thi-truong

Initializes the TopStock instance to access market insight methods.

```APIDOC
## TopStock()

### Description
Initializes the TopStock class to fetch market data.

### Parameters
- **show_log** (bool, default=False) - Optional - Display debug logs.
- **random_agent** (bool, default=False) - Optional - Use a random user agent to avoid blocking.
```

--------------------------------

### Unified UI Data Call

Source: https://vnstocks.com/docs/vnstock-data/data-sources

Example of a standard data request that automatically routes through the default Unified UI sources.

```python
Market().equity('VIC').ohlcv()
```

--------------------------------

### Finance Module Initialization

Source: https://vnstocks.com/docs/vnstock-data/bao-cao-tai-chinh

Initialize the Finance object by specifying the data source and the stock symbol.

```APIDOC
## Finance Initialization

### Description
Initialize the Finance class to access financial data for a specific stock ticker from a chosen source.

### Parameters
- **source** (string) - Required - Data source: 'VCI', 'MAS', or 'KBS'.
- **symbol** (string) - Required - Stock ticker symbol (e.g., 'TCB').
```

--------------------------------

### GET /api/skills/[name]/content

Source: https://vnstocks.com/docs/vnstock-insider-api/co-che-agent-skills-docs

Retrieves the source code content of a specific Agent Skill. Supports buffer decoding for advanced skills.

```APIDOC
## GET /api/skills/[name]/content

### Description
Retrieves the source code content of a specific Agent Skill.

### Method
GET

### Endpoint
/api/skills/[name]/content

### Parameters
#### Path Parameters
- **name** (string) - Required - The unique identifier of the skill.

### Headers
- **x-api-key** or **Authorization: Bearer** - Required - Authentication token.
```

--------------------------------

### Macro().economy().credit()

Source: https://vnstocks.com/docs/vnstock-data/cau-truc-du-lieu/macro

Retrieves credit growth data.

```APIDOC
## Macro().economy().credit()

### Description
Retrieves credit growth statistics.

### Data Fields
- **time** (datetime64[ns]) - Transaction time
- **credit_growth** (float64) - Credit growth
- **vnindex** (float64) - VN-INDEX value
```

--------------------------------

### quote.history(start, end, length, interval, get_all)

Source: https://vnstocks.com/docs/vnstock/thong-ke-gia-lich-su

Retrieves historical price data for a stock symbol. Data is returned as a pandas DataFrame containing OHLCV information.

```APIDOC
## Method: quote.history

### Description
Retrieves historical price data (OHLCV) for a specific stock symbol. The data is adjusted for corporate actions.

### Parameters
- **start** (str) - Optional - Start date in YYYY-MM-DD format. Required if length is not provided.
- **end** (str) - Optional - End date in YYYY-MM-DD format. Defaults to current date.
- **interval** (str) - Optional - Time interval for data points. Supported: "1m", "5m", "15m", "30m", "1H", "1D", "1W", "1M". Defaults to "1D".
- **length** (str/int) - Optional - Lookback period from current date or number of candles. Examples: "1M", "3M", "1Y", 150, "100b".
- **get_all** (bool) - Optional - (KBS only) If True, retrieves all available columns. Defaults to False.

### Usage Example
```python
# Get last 1 month of data
quote.history(length="1M", interval="1D")

# Get data for a specific range
quote.history(start='2024-01-01', end='2024-05-25', interval="1D")
```

### Response
Returns a pandas DataFrame with columns: time, open, high, low, close, volume.
```

--------------------------------

### Macro().economy().retail()

Source: https://vnstocks.com/docs/vnstock-data/cau-truc-du-lieu/macro

Retrieves retail economic data.

```APIDOC
## Macro().economy().retail()

### Description
Returns retail economic data including report time, time, name, value, unit, and source.

### Response
- **report_time** (object) - Time/Date
- **time** (object) - Transaction time
- **name** (object) - Full name of organization/company/fund
- **value** (float64) - Transaction value
- **unit** (object) - Unit
- **source** (object) - Data source
```

--------------------------------

### Tra cứu cấu trúc API với show_api()

Source: https://vnstocks.com/docs/vnstock-data/kien-truc-thu-vien

Sử dụng hàm show_api() để hiển thị toàn bộ cây tính năng và các endpoint có sẵn trong thư viện.

```python
from vnstock_data import show_api, show_doc
>>> show_api()
```

--------------------------------

### Handle Deprecated Macro Methods

Source: https://vnstocks.com/docs/vnstock-data/macro-layer-v3

Shows the transition from deprecated interest rate methods to the recommended currency-based approach.

```python
m = Macro()
df = m.interest_rate(length=90)  # ⚠️ Warning
```

```python
df = Macro().currency().interest_rate(length=90)
```

--------------------------------

### overview()

Source: https://vnstocks.com/docs/vnstock-data/thong-tin-cong-ty

Retrieves general company information including business model, charter capital, and contact details.

```APIDOC
## overview()

### Description
Retrieves the general overview of a company. Available via `company_vci` and `company_kbs` modules.

### Parameters
None

### Response
Returns a DataFrame containing company details such as symbol, charter capital, history, and profile information.
```

--------------------------------

### show_api()

Source: https://vnstocks.com/docs/vnstock-data/kien-truc-thu-vien

Displays the complete tree structure of available API endpoints within the vnstock_data library.

```APIDOC
## show_api()

### Description
Displays the full hierarchy of available functions and data access points within the vnstock_data library.

### Usage
```python
from vnstock_data import show_api
show_api()
```
```

--------------------------------

### Sử dụng Core Adapter

Source: https://vnstocks.com/docs/vnstock-data/kien-truc-thu-vien

Sử dụng cổng giao tiếp chung để duy trì tính tương thích với mã nguồn cũ và linh hoạt thay đổi nhà cung cấp.

```python
from vnstock_data import Quote, Trading, Finance, Listing, Company, Macro

quote = Quote(source="vci", symbol="VCI")
df = quote.history(start="2024-02-01", end="2025-04-18", interval="1D")
```

--------------------------------

### Filter Stocks and Retrieve Industry Data with Python

Source: https://vnstocks.com/docs/vnstock-data/insights-layer-v3

Demonstrates applying custom filters for exchange and financial ratios, as well as fetching industry classification data and filtering by sector.

```python
from vnstock_data import Insights

ins = Insights()

custom_filters = [
    {
        "name": "exchange",
        "conditionOptions": [{"type": "value", "value": "hsx"}]
    },
    {
        "name": "ttmRoe",
        "conditionOptions": [{"from": 15, "to": 100}]
    },
    {
        "name": "ttmPe",
        "conditionOptions": [{"from": 0, "to": 10}]
    }
]

df_filtered = ins.screener.filter(filters=custom_filters)
print(f"Cổ phiếu HSX, P/E < 10, ROE > 15: {len(df_filtered)}")
print(df_filtered[['ticker', 'ttm_pe', 'ttm_roe']].head())

from vnstock_data import Listing

lst_vci = Listing(source="vci")
icb_df = lst_vci.industries_icb()

lv1_sectors = icb_df[icb_df['level'] == 1]
print("Danh sách mã ngành cấp 1:\n", lv1_sectors[['icb_code', 'icb_name']].head())

sector_code = "1000" 
sector_filter = [
    {
        "name": "sectorLv1",
        "conditionOptions": [{"type": "value", "value": sector_code}]
    }
]

df_sector = ins.screener.filter(filters=sector_filter)
print(f"\nCổ phiếu thuộc nhóm ngành {sector_code}: {len(df_sector)}")
print(df_sector[['ticker', 'exchange', 'sector_lv1']].head())

df_all = ins.screener.filter()
print(f"Total stocks: {len(df_all)}")

cheap_good = df_all[
    (df_all['pe'] < 10) & (df_all['roe'] > 15)
]
print(cheap_good[['symbol', 'pe', 'roe']].head())
```

--------------------------------

### Indicator Initialization

Source: https://vnstocks.com/docs/vnstock-ta/chi-bao-ky-thuat

How to initialize the Indicator class with a DataFrame containing market data.

```APIDOC
from vnstock_ta import Indicator

# Initialize with DataFrame (requires columns: open, high, low, close, volume)
ta = Indicator(data=df)
```

--------------------------------

### Messenger.__init__

Source: https://vnstocks.com/docs/vnstock/gui-tin-nhan-telegram-slack-larksuite

Khởi tạo đối tượng Messenger để kết nối với nền tảng nhắn tin.

```APIDOC
### Constructor
`Messenger(platform, channel, token_key)`

#### Parameters
- **platform** (str) - Required - Nền tảng nhắn tin: 'telegram', 'slack', hoặc 'lark'.
- **channel** (str) - Required - Mã định danh kênh hoặc nhóm (để None nếu là Lark).
- **token_key** (str) - Required - Mã bảo mật API hoặc webhook ID.
```

--------------------------------

### Đọc dữ liệu đã xuất bằng StorageConfig

Source: https://vnstocks.com/docs/vnstock-pipeline/tuy-chinh-pipeline

Sử dụng lớp StorageConfig để tự động giải quyết đường dẫn lưu trữ, tránh việc viết cứng đường dẫn trong mã nguồn.

```python
import pandas as pd
from vnstock_pipeline.core.storage.config import StorageConfig

# Load cấu hình từ file pipeline.toml hiện tại
config = StorageConfig.load()

# Tự động giải quyết đường dẫn tuyệt đối dù bạn chạy script ở bất kỳ đâu
base_path = config.resolve_base_path()

# Ví dụ đọc dữ liệu Parquet
file_path = base_path / "ohlcv" / "ACB.parquet"
df = pd.read_parquet(file_path)
```

--------------------------------

### Listing Module Methods

Source: https://vnstocks.com/docs/vnstock-data/trang-thai-niem-yet

Summary of available methods in the Listing module and their support across different data sources.

```APIDOC
## Available Methods

- **all_indices()**: Retrieve list of market indices.
- **indices_by_group()**: Filter indices by group (HOSE, Sector, etc.).
- **all_symbols()**: Retrieve list of all stock symbols.
- **symbols_by_industries()**: Retrieve symbols filtered by industry.
- **industries_icb()**: Retrieve ICB industry classification information.
- **symbols_by_group()**: Filter symbols by group (VN30, HNX30, etc.).
- **all_government_bonds()**: Retrieve government bonds list.
- **all_covered_warrant()**: Retrieve covered warrants (CW) list.
- **all_etf()**: Retrieve ETF list.
- **all_future_indices()**: Retrieve future contracts list.
```

--------------------------------

### CommodityPrice Initialization

Source: https://vnstocks.com/docs/vnstock-data/thi-truong-hang-hoa

Initializes the CommodityPrice class to fetch commodity data.

```APIDOC
## Class: CommodityPrice

### Description
Initializes the data provider for commodity market prices.

### Parameters
- **start** (str, optional) - Start date (YYYY-MM-DD)
- **end** (str, optional) - End date (YYYY-MM-DD)
- **length** (str|int, optional) - Time range (default '1Y')
- **show_log** (bool, default=False) - Enable debug logs
```

--------------------------------

### Company.overview()

Source: https://vnstocks.com/docs/vnstock/thong-tin-cong-ty

Retrieves an overview of company information. The structure and content of the returned data depend on the source (KBS or VCI) specified during the initialization of the Company object.

```APIDOC
## Company.overview()

### Description
Retrieves comprehensive company profile data. The output format varies significantly between the 'KBS' and 'VCI' data sources.

### Method
Python SDK Method

### Parameters
None

### Response
#### Success Response
- **KBS Source (30 columns)**: Returns fields including `business_model`, `symbol`, `founded_date`, `charter_capital`, `number_of_employees`, `listing_date`, `par_value`, `exchange`, `listing_price`, `listed_volume`, `ceo_name`, `ceo_position`, `inspector_name`, `inspector_position`, `establishment_license`, `business_code`, `tax_id`, `auditor`, `company_type`, `address`, `phone`, `fax`, `email`, `website`, `branches`, `history`, `free_float_percentage`, `free_float`, `outstanding_shares`, `as_of_date`.
- **VCI Source (10 columns)**: Returns fields including `symbol`, `id`, `issue_share`, `history`, `company_profile`, `icb_name3`, `icb_name2`, `icb_name4`, `financial_ratio_issue_share`, `charter_capital`.

### Usage Example
```python
company = Company(symbol='VCI', source='KBS')
company.overview()
```
```

--------------------------------

### Macro().economy().gdp()

Source: https://vnstocks.com/docs/vnstock-data/cau-truc-du-lieu/macro

Retrieves GDP components and total GDP.

```APIDOC
## Macro().economy().gdp()

### Description
Retrieves GDP data broken down by sector.

### Data Fields
- **time** (datetime64[ns]) - Transaction time
- **agriculture** (float64) - Agriculture sector
- **industry** (float64) - Industry sector
- **services** (float64) - Services sector
- **tax** (float64) - Tax
- **gdp** (float64) - Total GDP
- **vnindex** (float64) - VN-INDEX value
```

--------------------------------

### Market Class Initialization

Source: https://vnstocks.com/docs/vnstock-data/thong-ke-thi-truong

Initializes the Market object to fetch data for a specific index.

```APIDOC
## Market(index="VNINDEX", random_agent=False)

### Description
Initializes the Market class to access historical market valuation data.

### Parameters
- **index** (str, default="VNINDEX") - Optional - Market index to fetch data for. Supported: "VNINDEX" (HSX), "HNX" or "HNXINDEX" (HNX).
- **random_agent** (bool, default=False) - Optional - Whether to use a random user agent to avoid blocking.
```

--------------------------------

### Reference().etf.list

Source: https://vnstocks.com/docs/vnstock-data/cau-truc-du-lieu/reference

Retrieves a list of all available ETFs.

```APIDOC
## Reference().etf.list()

### Description
Returns a list of all ETFs available in the system.

### Response
- **symbol** (object) - ETF security identifier
```

--------------------------------

### Finance(symbol, source, standardize_columns, period, get_all)

Source: https://vnstocks.com/docs/vnstock/bao-cao-tai-chinh

Initializes the Finance object to fetch financial data for a specific stock symbol from a chosen data source.

```APIDOC
## Finance Initialization

### Description
Initializes the Finance client to interact with financial data sources (KBS or VCI).

### Parameters
- **symbol** (str) - Required - Stock ticker symbol (e.g., 'VCI', 'ACB').
- **source** (str) - Required - Data source provider ('KBS' or 'VCI').
- **standardize_columns** (bool) - Optional - Whether to standardize column names. Default: True.
- **period** (str) - Optional - Data frequency (e.g., 'quarter').
- **get_all** (bool) - Optional - Whether to retrieve all available fields.

### Usage Example
```python
from vnstock import Finance
finance = Finance(source="KBS", symbol="VCI", standardize_columns=True)
```
```

--------------------------------

### Truy xuất báo cáo kết quả kinh doanh nguồn KBS

Source: https://vnstocks.com/docs/vnstock/bao-cao-tai-chinh

Sử dụng lớp Finance với nguồn KBS để lấy dữ liệu báo cáo kết quả kinh doanh. Hỗ trợ tùy chỉnh chế độ hiển thị trường dữ liệu thông qua FieldDisplayMode.

```python
from vnstock import Finance
from vnstock.explorer.kbs.financial import FieldDisplayMode

finance = Finance(symbol="VCI", source="KBS")

# Mode mặc định - Standardized
df = finance.income_statement(period="quarter")
print(f"Shape: {df.shape}")  # (90, 6)
```

```shell
>>> finance.income_statement(period="quarter")

                                                item                             item_id      2025-Q4      2025-Q3      2025-Q2      2025-Q1
0                             I. DOANH THU HOẠT ĐỘNG                             operating_income          NaN          NaN          NaN          NaN
1  1.1. Lãi từ các tài sản tài chính ghi nhận thô...  gains_from_financial_assets_at_fair_value_thro...   750209276.0   590437543.0   615976718.0   524812855.0
2                    a. Lãi bán các tài sản tài chính  a_realised_gains_on_disposals_of_fvtpl_financi...   748943883.0   589172069.0   614712244.0   523548381.0

[90 rows x 6 columns]
```

```shell
>>> finance.income_statement(period="quarter", display_mode=FieldDisplayMode.ALL)

                                                item                                           item_en                             item_id  unit  levels  row_number      2025-Q4      2025-Q3      2025-Q2      2025-Q1
0                             I. DOANH THU HOẠT ĐỘNG                                     OPERATING INCOME                             operating_income  NaN      1.0           0          NaN          NaN          NaN          NaN
1  1.1. Lãi từ các tài sản tài chính ghi nhận thô...  1.1. Gains from financial assets at fair value...  gains_from_financial_assets_at_fair_value_thro...  VND      2.0           1   750209276.0   590437543.0   615976718.0   524812855.0

[90 rows x 10 columns]
```

--------------------------------

### Retail.exchange_rate()

Source: https://vnstocks.com/docs/vnstock/du-lieu-thi-truong-hang-hoa-retail

Retrieves foreign exchange rate data from Vietcombank (VCB).

```APIDOC
## Method: Retail.exchange_rate(date='')

### Description
Tracks foreign exchange rate fluctuations directly from Vietcombank. If date is empty, the current rate is returned.

### Parameters
- **date** (string) - Optional - Date in 'YYYY-MM-DD' format.

### Returns
- **pandas.DataFrame** - Contains columns: currency, buy_cash, buy_transfer, sell.
```

--------------------------------

### Retrieve Commodity Price Data

Source: https://vnstocks.com/docs/vnstock-data/macro-layer-v3

Demonstrates how to fetch various commodity prices including gold, gas, oil, and agricultural products using the macro.commodity module.

```python
from vnstock_data import Macro
import pandas as pd

mac = Macro()

df_gold_vn = mac.commodity().gold(market="VN")
print(df_gold_vn[['time', 'price']].tail())
df_gold_global = mac.commodity().gold(market="GLOBAL")
print(df_gold_global.head(1))  # OHLCV DataFrame
df_gas_vn = mac.commodity().gas(market="VN")
print(df_gas_vn.head(1))
df_gas_global = mac.commodity().gas(market="GLOBAL")
print(df_gas_global.head(1))  # USD/MMBtu (OHLCV)

df_oil = mac.commodity().oil_crude()
print(df_oil.head(1))
df_coke = mac.commodity().coke()
print(df_coke.head(1))

df_steel_vn = mac.commodity().steel(market="VN")
print(df_steel_vn.head(1))

df_steel_global = mac.commodity().steel(market="GLOBAL")
print(df_steel_global.head(1))  # USD/tấn (OHLCV)

df_ore = mac.commodity().iron_ore()
print(df_ore.head(1))  # USD/tấn (OHLCV)

df_soy = mac.commodity().soybean()
print(df_soy.head(1))  # USD/bushel (OHLCV)

df_corn = mac.commodity().corn()
print(df_corn.head(1))

df_sugar = mac.commodity().sugar()
print(df_sugar[['time', 'price']])

df_pork_vn = mac.commodity().pork(market="VN")
print(df_pork_vn[['time', 'price']])  # VNĐ/kg

df_pork_china = mac.commodity().pork(market="CHINA")
print(df_pork_china[['time', 'price']])
```

--------------------------------

### Market Layer Methods

Source: https://vnstocks.com/docs/vnstock-data/market-layer-v3

The Market() class provides entry points for different asset classes and market data types.

```APIDOC
## Market() Methods

### Description
Access market data for specific asset classes or aggregate quotes.

### Methods
- **.equity(symbol)**: Market data for stocks.
- **.index(symbol)**: Market data for indices.
- **.futures(symbol)**: Market data for futures contracts.
- **.warrant(symbol)**: Market data for warrants.
- **.bond(symbol)**: Market data for bonds.
- **.etf(symbol)**: Market data for ETFs.
- **.fund(symbol)**: Market data for open-ended funds.
- **.crypto(symbol)**: Market data for cryptocurrencies.
- **.forex(symbol)**: Market data for forex.
- **.commodity(symbol)**: Market data for international commodities.
- **.quote(symbols_list)**: Real-time price table for a list of symbols.
```

--------------------------------

### Retrieve Session Statistics

Source: https://vnstocks.com/docs/vnstock-data/market-layer-v3

Aggregates liquidity metrics and buy/sell ratios for the current session.

```python
session = mkt.equity("VIC").session_stats()
```

--------------------------------

### Market(index)

Source: https://vnstocks.com/docs/vnstock-data/thong-ke-thi-truong

Initializes a Market instance for a specific stock index to perform statistical analysis.

```APIDOC
## Market(index)

### Description
Initializes the Market class for a specific stock index (e.g., 'VNINDEX', 'HNX').

### Parameters
- **index** (str) - Required - The index symbol to analyze.

### Methods
- **pe(duration)**: Returns a DataFrame containing P/E ratios for the specified duration (e.g., '5Y').
```

--------------------------------

### Analytics.valuation(index)

Source: https://vnstocks.com/docs/vnstock-data/analytics-layer-v3

Initializes the valuation module for a specific market index to access historical P/E and P/B data.

```APIDOC
## Analytics.valuation(index)

### Description
Initializes the valuation module for a specific market index. This is the entry point for accessing historical valuation metrics.

### Parameters
- **index** (str) - Required - The market index to analyze (e.g., "VNINDEX", "HNX", "VN30").

### Usage Example
```python
from vnstock_data import Analytics
ana = Analytics()
val = ana.valuation("VNINDEX")
```
```

--------------------------------

### Xem trợ giúp hàm biểu diễn dữ liệu

Source: https://vnstocks.com/docs/vnstock/bieu-dien-du-lieu

Sử dụng phương thức .viz.help() để xem hướng dẫn chi tiết về các tham số của một hàm biểu diễn dữ liệu cụ thể.

```python
df.viz.help('timeseries')
```

--------------------------------

### Macro().economy().industry_prod()

Source: https://vnstocks.com/docs/vnstock-data/cau-truc-du-lieu/macro

Retrieves industrial production growth data.

```APIDOC
## Macro().economy().industry_prod()

### Description
Retrieves industrial production growth statistics.

### Data Fields
- **report_time** (object) - Report date
- **time** (object) - Transaction time
- **group_name** (object) - Group name
- **name** (object) - Industry name
- **value** (float64) - Growth value
- **unit** (object) - Unit of measurement
- **source** (object) - Data source
```

--------------------------------

### macro.currency Methods

Source: https://vnstocks.com/docs/vnstock-data/macro-layer-v3

Methods for retrieving currency exchange rates, interest rates, and monetary policy data.

```APIDOC
## macro.currency Methods

### Methods
- **exchange_rate(start, end, period)**: Get exchange rate data.
- **interest_rate(start, end, period, format)**: Get interest rate data.
- **interbank_rate(start, end, period)**: Get interbank interest rate data.
- **policy_rate(start, end)**: Get central bank policy rate data.
- **omo(start, end)**: Get open market operations data.
- **deposit_rate(mode, period, start, end)**: Get deposit interest rate data.

### Parameters
- **period** (string): Frequency of data, options: "day" (default), "month", "quarter".
- **format** (string): Data format, options: "pivot" (default), "long".
- **length** (int): Number of most recent periods to retrieve.
```

--------------------------------

### Macro().economy().state_budget()

Source: https://vnstocks.com/docs/vnstock-data/cau-truc-du-lieu/macro

Retrieves state budget statistics.

```APIDOC
## Macro().economy().state_budget()

### Description
Returns state budget data including revenue, expenditure, and net balance.

### Response
- **time** (datetime64[ns]) - Transaction time
- **budget_in** (int64) - Budget revenue
- **budget_out** (int64) - Budget expenditure
- **budget_net** (int64) - Budget balance
```

--------------------------------

### company_vci.ratio_summary()

Source: https://vnstocks.com/docs/vnstock-data/thong-tin-cong-ty

Retrieves a snapshot of key financial ratios from the VCI source.

```APIDOC
## company_vci.ratio_summary()

### Description
Retrieves a snapshot of key financial ratios from the VCI source.

### Response
- **pe** (float) - P/E
- **pb** (float) - P/B
- **roe** (float) - ROE
- **roa** (float) - ROA
- **eps** (float) - EPS cơ bản
- **revenue_growth** (float) - Tăng trưởng doanh thu
- **net_profit_growth** (float) - Tăng trưởng lợi nhuận
- **dividend** (int) - Cổ tức tiền mặt gần nhất
- **net_profit_margin** (float) - Biên lợi nhuận ròng
- **debt_equity** (float) - Tỷ số Nợ/Vốn chủ sở hữu
```

--------------------------------

### Macro().currency().exchange_rate()

Source: https://vnstocks.com/docs/vnstock-data/cau-truc-du-lieu/macro

Retrieves historical exchange rate data including center rates, Vietcombank rates, and market rates.

```APIDOC
## Macro().currency().exchange_rate()

### Description
Retrieves historical exchange rate data including center rates, Vietcombank rates, and market rates alongside the VN-INDEX.

### Data Fields
- **time** (datetime64[ns]) - Transaction time
- **center_rate** (float64) - Center rate
- **vcb_rate** (float64) - Vietcombank rate
- **market_rate** (int64) - Interbank market rate
- **vnindex** (float64) - VN-INDEX value
```

--------------------------------

### Macro().currency().omo()

Source: https://vnstocks.com/docs/vnstock-data/cau-truc-du-lieu/macro

Retrieves Open Market Operation (OMO) flow data.

```APIDOC
## Macro().currency().omo()

### Description
Retrieves OMO flow data including inflow, outflow, and netflow amounts.

### Data Fields
- **time** (datetime64[ns]) - Transaction time
- **vnindex** (float64) - VN-INDEX value
- **inflow_amount** (float64) - Inflow amount
- **outflow_amount** (float64) - Outflow amount
- **netflow_amount** (float64) - Netflow amount
- **cumulative_flow_amount** (float64) - Cumulative flow amount
```

--------------------------------

### Analytics().valuation().pb()

Source: https://vnstocks.com/docs/vnstock-data/cau-truc-du-lieu/analytics

Retrieves the Price to Book (P/B) ratio for a specified symbol over a given duration.

```APIDOC
## Analytics().valuation(symbol).pb(duration)

### Description
Retrieves the historical P/B ratio data for the specified symbol.

### Parameters
- **symbol** (string) - The market index or stock symbol.
- **duration** (string) - The time range for the data.

### Response
- **reportDate** (datetime64[ns]) - The date of the report.
- **pb** (float64) - Price to Book ratio.
```

--------------------------------

### Reference().bond().list()

Source: https://vnstocks.com/docs/vnstock-data/cau-truc-du-lieu/reference

Lists available bonds with their identifiers and types.

```APIDOC
## Reference().bond().list()

### Description
Returns a list of bonds including their symbol and type.

### Response
- **symbol** (object) - Identifier
- **type** (object) - Type (e.g., corporate, STOCK)
```

--------------------------------

### company.affiliate()

Source: https://vnstocks.com/docs/vnstock/thong-tin-cong-ty

Retrieves information about company affiliates, supporting both KBS and VCI sources with different return schemas.

```APIDOC
## company.affiliate()

### Description
Retrieves a list of affiliated companies. The structure of the returned data depends on the underlying source (KBS or VCI).

### Parameters
- None

### Response (KBS Source)
- **update_date** (object): Date of update
- **name** (object): Name of the affiliate
- **charter_capital** (int64): Charter capital
- **ownership_percent** (float64): Ownership percentage (%)
- **currency** (object): Currency type
- **type** (object): Relationship type

### Response (VCI Source)
- **id** (object): Affiliate ID
- **sub_organ_code** (object): Subsidiary code
- **organ_name** (object): Company name
- **ownership_percent** (object): Ownership percentage (can be null)
```

--------------------------------

### volume()

Source: https://vnstocks.com/docs/vnstock-data/dinh-gia-thi-truong

Retrieves the top stocks by volume spike.

```APIDOC
## volume(index="VNINDEX", limit=10)

### Description
Returns a DataFrame of top stocks by volume spike percentage.

### Parameters
- **index** (str, default="VNINDEX") - Optional - Market index (VNINDEX, HNX, VN30).
- **limit** (int, default=10) - Optional - Number of stocks to return.

### Response
- **DataFrame** - Contains 15 columns including symbol, index, last_price, and volume_spike_20d_pct.
```

--------------------------------

### Macro.economy() Methods

Source: https://vnstocks.com/docs/vnstock-data/macro-layer-v3

Methods for retrieving Vietnam's economic data including GDP, CPI, FDI, and trade statistics.

```APIDOC
## SDK Method: macro.economy()

### Description
Provides access to Vietnam's economic data series such as GDP, CPI, FDI, and trade balance.

### Methods
- gdp(start, end, period)
- cpi(start, end, period)
- industry_prod(start, end, period)
- import_export(start, end, period)
- retail(start, end, period)
- fdi(start, end, period)
- money_supply(start, end, period, breakdown)
- population_labor(start, end, period)
- credit(start, end, period, breakdown)
- total_investment(start, end, period)
- state_budget(start, end, period)

### Parameters
- start (string) - Optional - Start date (e.g., "2020-01" or "2020")
- end (string) - Optional - End date (e.g., "2026-03")
- period (string) - Optional - Frequency: "quarter" (default), "month", or "year"
- length (int) - Optional - Number of most recent periods to retrieve
- breakdown (string) - Optional - Specific breakdown for money supply or credit data

### Usage Example
```python
from vnstock_data import Macro
mac = Macro()
df = mac.economy().gdp(start="2020-01", end="2026-03", period="quarter")
```
```

--------------------------------

### Truy xuất báo cáo lưu chuyển tiền tệ từ nguồn KBS

Source: https://vnstocks.com/docs/vnstock/bao-cao-tai-chinh

Sử dụng Finance với source='KBS' để lấy dữ liệu lưu chuyển tiền tệ theo quý.

```python
finance = Finance(symbol="VCI", source="KBS")
df = finance.cash_flow(period="quarter")
print(f"Shape: {df.shape}")  # (159, 6)
```

```shell
>>> finance.cash_flow(period="quarter")

                                                item                             item_id      2025-Q4      2025-Q3      2025-Q2      2025-Q1
0                      I. Lưu chuyển tiền tệ từ hoạt động kinh doanh                             cash_from_operations          NaN          NaN          NaN          NaN
1                                            Lợi nhuận trước thuế                             profit_before_tax  1452727693070.0 1370219906556.0 1100476657055.0   987654321098.0
2                               Các khoản điều chỉnh lại lợi nhuận trước thuế                    adjustments_to_profit_before_tax  -1234567890.0  -1234567890.0  -1234567890.0  -1234567890.0

[159 rows x 6 columns]
```

--------------------------------

### Vẽ biểu đồ Pie với Vnstock

Source: https://vnstocks.com/docs/vnstock/bieu-dien-du-lieu

Sử dụng phương thức viz.pie để hiển thị tỉ lệ phần trăm của các cổ đông.

```python
shareholders_df.viz.pie(title='Cổ đông lớn VNM',
                                             labels='share_holder',
                                             values='share_own_percent',
                                             figsize=(10, 6),
                                             ylabel='',
                                             color_palette='stock')
```

--------------------------------

### deal()

Source: https://vnstocks.com/docs/vnstock-data/dinh-gia-thi-truong

Retrieves the top stocks by negotiated deal volume spike.

```APIDOC
## deal(index="VNINDEX", limit=10)

### Description
Returns a DataFrame of top stocks by negotiated deal volume spike percentage.

### Parameters
- **index** (str, default="VNINDEX") - Optional - Market index (VNINDEX, HNX, VN30).
- **limit** (int, default=10) - Optional - Number of stocks to return.

### Response
- **DataFrame** - Contains 15 columns including symbol, index, last_price, and deal_volume_spike_20d_pct.
```

--------------------------------

### client.place_order

Source: https://vnstocks.com/docs/vnstock/api-dat-lenh-giao-dich-dnse

Places a new trading order for stocks or derivatives.

```APIDOC
## client.place_order(sub_account, symbol, side, quantity, price, order_type, loan_package_id, asset_type)

### Description
Places a new buy or sell order for a specified sub-account.

### Parameters
- **sub_account** (string) - Required - The sub-account code used for trading.
- **symbol** (string) - Required - The stock ticker or derivative contract code.
- **side** (string) - Required - Order side: 'buy' or 'sell'.
- **quantity** (integer) - Required - Number of shares or contracts.
- **price** (float) - Required - Price per unit.
- **order_type** (string) - Required - Order type: 'LO', 'MP', 'MTL', 'ATO', 'ATC', 'MOK', 'MAK'.
- **loan_package_id** (string) - Optional - Loan package code.
- **asset_type** (string) - Required - Asset type: 'stock' or 'derivative'.
```

--------------------------------

### Lấy top theo giao dịch thỏa thuận đột biến

Source: https://vnstocks.com/docs/vnstock-data/dinh-gia-thi-truong

Sử dụng phương thức deal() để lấy danh sách các cổ phiếu có giao dịch thỏa thuận đột biến.

```python
# Lấy top 10 theo giao dịch thỏa thuận (mặc định)
df = insights.deal()

# Lấy top 5
df = insights.deal(limit=5)
```

```text
  symbol    index  last_price  deal_volume_spike_20d_pct
0    BKG  VNINDEX        2.92                       22.50
1    NAB  VNINDEX       14.35                        2.69
2    CDC  VNINDEX       25.00                        6.24
```

--------------------------------

### ref.events.market()

Source: https://vnstocks.com/docs/vnstock-data/reference-layer-v3

Retrieves general market events such as holidays or system maintenance.

```APIDOC
## Method: ref.events.market(start, end, event_type)

### Description
Looks up market events such as trading holidays, system maintenance, or incidents.

### Usage
```python
market_events = ref.events.market()
```
```

--------------------------------

### Reference().warrant().list()

Source: https://vnstocks.com/docs/vnstock-data/cau-truc-du-lieu/reference

Lists available warrants.

```APIDOC
## Reference().warrant().list()

### Description
Returns a list of available warrants.

### Response
- **symbol** (object) - Mã định danh chứng khoán / tổ chức
```

--------------------------------

### Sử dụng FieldDisplayMode để kiểm soát hiển thị

Source: https://vnstocks.com/docs/vnstock/bao-cao-tai-chinh

Sử dụng các chế độ hiển thị khác nhau để tùy chỉnh các trường dữ liệu trả về trong báo cáo tài chính.

```python
from vnstock import Finance
from vnstock.explorer.kbs.financial import FieldDisplayMode

finance = Finance(symbol="VCI", source="KBS")

# Mode 1: Standardized (mặc định) - Chỉ item tiếng Việt + item_id
df_std = finance.income_statement(
    period="quarter",
    display_mode=FieldDisplayMode.STD
)

# Mode 2: All Fields - Hiển thị cả item (VN), item_en, item_id
df_all = finance.income_statement(
    period="quarter",
    display_mode=FieldDisplayMode.ALL
)

# Mode 3: Auto Convert - Tự động chuyển đổi
df_auto = finance.income_statement(
    period="quarter",
    display_mode=FieldDisplayMode.AUTO
)

# Mode 4: chỉ Tiếng Việt (backward compatible)
df_vi = finance.income_statement(
    period="quarter",
    display_mode='vi'
)

# Mode 5: chỉ Tiếng Anh (backward compatible)
df_en = finance.income_statement(
    period="quarter",
    display_mode='en'
)
```
Tokens:
Raw