XNO API

https://github.com/xno-quant/xnoapi
Admin
XNO API is a comprehensive, free, and open-source Python library for quantitative analysis and...
Tokens:26,768
Snippets:92
Trust Score:2.3
License:MIT
Update:1 year ago
Show doc for...
Tokens:
Raw
### Quantitative Data Analysis Example

Source: https://github.com/xno-quant/xnoapi/blob/main/README.md

Demonstrates how to connect to the XNO API, retrieve market indices, and get snapshot data for the VNINDEX.

```APIDOC
## Quantitative Data Analysis Example

This example illustrates basic quantitative data analysis using the XNO API v2.

### 1. Connection Check and Index Retrieval

```python
from xnoapi.vn.data import *
import datetime as dt

# Check API connection
if ping():
    print("✅ Connection successful!")

# Get available market indices
indices = get_indices()
print("Available indices:", indices)
```

### 2. Snapshot Data Retrieval

```python
# Get a market index snapshot for VNINDEX
vni_snapshot = get_market_index_snapshot("VNINDEX")
print("VNINDEX current snapshot:", vni_snapshot)
```
```

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

### Install XNO API from Source

Source: https://github.com/xno-quant/xnoapi/blob/main/source/index.txt

Installs the XNO API library from its GitHub repository. This is useful for developers who want to use the latest code or contribute to the project.

```bash
git clone https://github.com/xnoproject/xnoapi.git
pip install ./xnoapi
```

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

### Install XNO API using pip

Source: https://github.com/xno-quant/xnoapi/blob/main/source/index.txt

Installs the stable release of the XNO API library from PyPI. This is the recommended method for most users.

```bash
pip install xnoapi
```

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

### Simple Backtest MA(20/50) for VIC Stock

Source: https://github.com/xno-quant/xnoapi/blob/main/source/index.txt

Demonstrates a simple backtest strategy using Moving Averages (20 and 50 periods) on the VIC stock. This example utilizes the Backtest_Stock class from the xnoapi.vn.metrics.backtest module.

```python
from xnoapi.vn.metrics.backtest import Backtest_Stock
```

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

### Get Cryptocurrency Price History using Python

Source: https://github.com/xno-quant/xnoapi/blob/main/README.md

Fetches historical price data for cryptocurrencies (e.g., BTC, ETH) between a start and end date. Uses the 'xnoapi.vn.data.stocks.Global' class. Provides historical quote data for crypto assets.

```python
Global = Global()
print("\nGlobal.BTCUSD:")
Global.crypto("BTCUSD").quote.history(start="2024-01-01", end="2024-12-31")
```

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

### Get Company Overview using Python

Source: https://github.com/xno-quant/xnoapi/blob/main/README.md

Retrieves a general overview of a company using its stock symbol. Requires the 'xnoapi.vn.data.stocks.Company' class. Outputs company summary information.

```python
from xnoapi.vn.data.stocks import Company
c = Company("ACB")
print("\nACB.Company.overview:")
c.overview()
```

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

### Price Board - Multi-Symbol Real-Time Data

Source: https://context7.com/xno-quant/xnoapi/llms.txt

Get consolidated real-time pricing data for multiple symbols with ceiling/floor prices and foreign trading info.

```APIDOC
## Price Board - Multi-Symbol Real-Time Data

### Description
Get consolidated real-time pricing data for multiple symbols with ceiling/floor prices and foreign trading info.

### Method
GET

### Endpoint
/vn/data/trading/price_board

### Parameters
#### Query Parameters
- **symbols** (array[string]) - Required - List of stock symbols to retrieve data for.

### Request Example
```json
{
  "symbols": ["VCB", "ACB", "TCB", "HPG", "VIC"]
}
```

### Response
#### Success Response (200)
- **symbol** (string) - Stock ticker symbol.
- **open** (float) - Opening price.
- **ceiling** (float) - Ceiling price.
- **floor** (float) - Floor price.
- **ref_price** (float) - Reference price.
- **high** (float) - Highest price.
- **low** (float) - Lowest price.
- **price_change** (float) - Price change.
- **price_change_pct** (float) - Percentage price change.
- **foreign_volume** (integer) - Volume traded by foreign investors.
- **foreign_room** (integer) - Remaining foreign ownership room.
- **foreign_holding_room** (integer) - Foreign holding room.
- **avg_match_volume_2w** (integer) - Average matching volume over the last 2 weeks.

#### Response Example
```json
[
  {
    "symbol": "VCB",
    "open": 90.0,
    "ceiling": 95.0,
    "floor": 85.0,
    "ref_price": 90.0,
    "high": 94.0,
    "low": 89.0,
    "price_change": 1.5,
    "price_change_pct": 1.67,
    "foreign_volume": 1000000,
    "foreign_room": 50000000,
    "foreign_holding_room": 120000000,
    "avg_match_volume_2w": 500000
  }
  // ... other symbols
]
```
```

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

### Get Company Profile using Python

Source: https://github.com/xno-quant/xnoapi/blob/main/README.md

Fetches detailed profile information for a company based on its stock symbol. Utilizes the 'xnoapi.vn.data.stocks.Company' class. Provides in-depth company details.

```python
c = Company("HPG")
print("\nHPG.Company.profile:")
c.profile()
```

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

### Get Real-time Price Board using Python

Source: https://github.com/xno-quant/xnoapi/blob/main/README.md

Fetches real-time price data for a list of stock symbols, including foreign investment data and ceiling/floor prices. Uses the 'xnoapi.vn.data.stocks.Trading.price_board' function. Provides a snapshot of current market prices.

```python
from xnoapi.vn.data.stocks import Trading
Trading.price_board(["VCB","ACB","TCB"])
```

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

### Market Index Snapshot

Source: https://context7.com/xno-quant/xnoapi/llms.txt

Get current market index information including trading statistics and price changes.

```APIDOC
## Market Index Snapshot - Real-Time Market Overview

### Description
Get current market index information including trading statistics and price changes.

### Method
`get_market_index_snapshot(index_symbol)`

### Endpoint
`/vn/data/get_market_index_snapshot`

### Parameters
#### Path Parameters
None

#### Query Parameters
- **index_symbol** (str) - Required - The symbol of the market index (e.g., "VNINDEX", "HNX").

### Request Example
```python
from xnoapi.vn.data import get_market_index_snapshot, get_indices, ping

# Check API connectivity
if ping():
    print("✅ API connection successful")

# Get list of available indices
indices = get_indices()
print(indices.head())

# Get real-time VNINDEX snapshot
vnindex = get_market_index_snapshot("VNINDEX")
print(vnindex)
```

### Response
#### Success Response (200)
- **time** (str) - The timestamp of the snapshot.
- **symbol** (str) - The index symbol.
- **name** (str) - The index name.
- **prior** (float) - The previous day's closing value.
- **value** (float) - The current index value.
- **total_vol** (float) - The total trading volume.
- **total_val** (float) - The total trading value.
- **advance** (int) - The number of advancing stocks.
- **decline** (int) - The number of declining stocks.
- **nochange** (int) - The number of stocks with no change.

#### Response Example
```json
{
  "time": "2025-08-22T14:45:15Z",
  "symbol": "VNINDEX",
  "name": "VNINDEX",
  "prior": 1688,
  "value": 1645.469971,
  "total_vol": 2234243072,
  "total_val": 6.067808e+12,
  "advance": 71,
  "decline": 251,
  "nochange": 27
}
```
```

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

### Get Balance Sheet using Python

Source: https://github.com/xno-quant/xnoapi/blob/main/README.md

Fetches the balance sheet for a company for a specified period (year or quarter). Uses the 'xnoapi.vn.data.stocks.Finance' class and a stock symbol. Displays assets, liabilities, and equity.

```python
f = Finance("HPG")
print("\nACB.Finance.balance_sheet(year):")
f.balance_sheet(period="year")
```

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

### Price Board API

Source: https://github.com/xno-quant/xnoapi/blob/main/README.md

Get real-time price board information for multiple stock symbols, including foreign investor activity and ceiling/floor prices.

```APIDOC
## Price Board API

### Real-time Price Board

- **Method**: Not applicable (function call)
- **Endpoint**: `Trading.price_board(symbols)`
- **Description**: Retrieves real-time market data for a list of stock symbols.
- **Parameters**: 
  - `symbols` (list of strings) - Required - A list of stock symbols to query.
- **Request Example**: 
```python
from xnoapi.vn.data.stocks import Trading
Trading.price_board(["VCB","ACB","TCB"])
```
```

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

### Get Market Index Snapshot using Python

Source: https://github.com/xno-quant/xnoapi/blob/main/README.md

Fetches a real-time snapshot of a specific market index, such as VNINDEX. Uses the 'get_market_index_snapshot' function from 'xnoapi.vn.data'. Provides current index values.

```python
vni_snapshot = get_market_index_snapshot("VNINDEX")
print("VNINDEX hiện tại:", vni_snapshot)
```

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

### Get Company Financial Ratios Summary using Python

Source: https://github.com/xno-quant/xnoapi/blob/main/README.md

Fetches a summary of key financial ratios for a company using its stock symbol. This method is part of the 'xnoapi.vn.data.stocks.Company' class. Includes metrics like P/E, ROE, etc.

```python
c = Company("TPB")
print("\nTPB.Company.ratio_summary:")
c.ratio_summary()
```

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

### Get Available Indices using Python

Source: https://github.com/xno-quant/xnoapi/blob/main/README.md

Retrieves a list of available market indices supported by the API. Uses the 'get_indices' function from 'xnoapi.vn.data'. Useful for identifying which indices can be queried.

```python
indices = get_indices()
print("Các chỉ số có sẵn:", indices)
```

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

### Get Market Index Snapshot and List

Source: https://context7.com/xno-quant/xnoapi/llms.txt

Retrieves real-time market index snapshots and a list of available indices. Includes a function to check API connectivity. The snapshot provides trading statistics and price changes for a given index symbol.

```python
from xnoapi.vn.data import get_market_index_snapshot, get_indices, ping

# Check API connectivity
if ping():
    print("✅ API connection successful")

# Get list of available indices
indices = get_indices()
print(indices.head())
#    symbol           name
# 0     HNX            HNX
# 1   HNX30          HNX30
# 2 VNINDEX        VNINDEX
# 3   VN30           VN30
# 4 VN100          VN100

# Get real-time VNINDEX snapshot
vnindex = get_market_index_snapshot("VNINDEX")
print(vnindex)
#                     time   symbol     name  prior        value   total_vol      total_val  advance  decline  nochange
# 0  2025-08-22T14:45:15Z  VNINDEX  VNINDEX   1688  1645.469971  2234243072  6.067808e+12       71      251        27
```

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

### Get Income Statement using Python

Source: https://github.com/xno-quant/xnoapi/blob/main/README.md

Retrieves the income statement for a company for a specified period (year or quarter). Requires the 'xnoapi.vn.data.stocks.Finance' class and a stock symbol. Outputs revenue, expenses, and net income.

```python
from xnoapi.vn.data.stocks import Finance
f = Finance("ACB")
print("\nACB.Finance.income_statement(year):")
f.income_statement(period="year")
```

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

### Integrate TA-Lib for Technical Analysis with Python

Source: https://context7.com/xno-quant/xnoapi/llms.txt

This Python code demonstrates how to integrate TA-Lib features with stock price data using the xnoapi library. It shows how to fetch historical stock data, rename columns to meet TA-Lib requirements, and add a comprehensive suite of technical indicators to the DataFrame. The example also illustrates how to access specific indicators like RSI.

```python
from xnoapi.vn.data import get_stock_hist, add_all_ta_features

# Get historical data
df = get_stock_hist("HPG", resolution='h')

# Rename columns to match TA-Lib requirements
df = df.rename(columns={
    'Open': 'Open',
    'High': 'High',
    'Low': 'Low',
    'Close': 'Close',
    'volume': 'Volume'
})

# Add all technical indicators (requires: pip install ta)
df_with_ta = add_all_ta_features(
    df,
    open='Open',
    high='High',
    low='Low',
    close='Close',
    volume='Volume',
    fillna=True
)

# Check added indicators
print(f"Original columns: {len(df.columns)}")
print(f"With TA features: {len(df_with_ta.columns)}")

# Common indicators now available:
# - RSI: df_with_ta['momentum_rsi']
```

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

### Backtest Long-Only Equity Strategy

Source: https://context7.com/xno-quant/xnoapi/llms.txt

This Python code snippet is the beginning of a backtest for a long-only equity strategy. It focuses on backtesting stock trading strategies with T+2 settlement rules and Vietnamese transaction fees, starting by fetching historical stock data.

```python
from xnoapi.vn.data import get_stock_hist
from xnoapi.vn.metrics import Backtest_Stock, Metrics
import pandas as pd

# Get HPG hourly data
df = get_stock_hist("HPG", resolution='h')
```

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

### Get Foreign Exchange Rate History using Python

Source: https://github.com/xno-quant/xnoapi/blob/main/README.md

Retrieves historical FX rate data for specified currency pairs (e.g., USDVND, EURUSD) between a start and end date. Requires the 'xnoapi.vn.data.stocks.Global' class. Outputs historical quote data.

```python
from xnoapi.vn.data.stocks import Global
Global = Global()
print("\nGlobal.FX USDVND:")
Global.fx("USDVND").quote.history(start="2024-01-01", end="2024-12-31")
```

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

### Initialize XNO API Client

Source: https://github.com/xno-quant/xnoapi/blob/main/source/index.txt

Demonstrates how to import necessary modules from the XNO API library and initialize the client with an API key. This is a prerequisite for using most of the library's functionalities.

```python
from xnoapi import client
from xnoapi.vn.data import stocks, derivatives
from xnoapi.vn.metrics import Metrics, Backtest_Derivates

# Khởi tạo client với API key
client(apikey="your_api_key")
```

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

### Get World Index History using Python

Source: https://github.com/xno-quant/xnoapi/blob/main/README.md

Retrieves historical data for international stock market indices (e.g., DJI, SPX, N225) between a start and end date. Requires the 'xnoapi.vn.data.stocks.Global' class. Outputs historical quote data for global indices.

```python
Global = Global()
print("\nGlobal.DJI:")
Global.world_index("DJI").quote.history(start="2024-01-01", end="2024-12-31")
```

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

### Initialize XNO API Client

Source: https://context7.com/xno-quant/xnoapi/llms.txt

Initializes the XNO API client with an API key. This step is mandatory before making any API requests. Ensure you obtain your API key from the provided URL.

```python
from xnoapi import client

# Initialize with your API key
client(apikey="xd_your_api_key_here")

# This must be called before making any API requests
# API keys can be obtained from https://xno.vn
```

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

### Fetch Company Overview, Profile, and Financials with xnoapi

Source: https://github.com/xno-quant/xnoapi/blob/main/README.md

This snippet demonstrates how to initialize Company and Finance objects from the xnoapi library to retrieve the overview and profile of a company (e.g., HPG) and its annual income statement. It shows how to display the head of the returned dataframes. Dependencies include the xnoapi library and typically a display function for dataframes.

```python
from xalpha.data import Company, Finance, Fund, Listing

comp = Company('HPG')
print('Company overview:')
display(comp.overview().head(1))

print('Company profile:')
display(comp.profile().head(1))

fin = Finance('HPG')
print('Income statement (year):')
display(fin.income_statement(period='year').head(1))
```

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

### Fetch Fund Listings and Exchange Symbols with xnoapi

Source: https://github.com/xno-quant/xnoapi/blob/main/README.md

This code segment illustrates how to use the xnoapi library to retrieve a listing of funds and their associated information, as well as a mapping of symbols by exchange. It initializes Fund and Listing objects and displays the head of the fund listing and the symbols by exchange. This requires the xnoapi library.

```python
from xalpha.data import Company, Finance, Fund, Listing

f = Fund()
print('Funds listing (head):')
display(f.listing().head(1))

lst = Listing()
print('Listing symbols_by_exchange:')
print(lst.symbols_by_exchange())
```

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

### Client Initialization

Source: https://context7.com/xno-quant/xnoapi/llms.txt

Initialize API authentication for accessing XNO services. This must be called before making any API requests.

```APIDOC
## Client Initialization

### Description
Initialize API authentication for accessing XNO services.

### Method
Initialization function

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
from xnoapi import client

# Initialize with your API key
client(apikey="xd_your_api_key_here")
```

### Response
No explicit response, but subsequent API calls will be authenticated.
```

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

### Get Company Shareholders using Python

Source: https://github.com/xno-quant/xnoapi/blob/main/README.md

Retrieves information about a company's shareholders using its stock symbol. This function is part of the 'xnoapi.vn.data.stocks.Company' class. Lists major shareholders.

```python
c = Company("VCI")
print("\nVCI.Company.shareholders:")
c.shareholders()
```

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

### Trading Backtest API (Upgraded)

Source: https://github.com/xno-quant/xnoapi/blob/main/README.md

A versatile backtesting class with enhanced features for strategy evaluation, including profit/loss management and comprehensive metric calculation.

```APIDOC
## Trading Backtest API (`xnoapi.metrics.TradingBacktest`)

This is an upgraded, versatile backtesting class with advanced capabilities:

### Features

- **Take Profit/Stop Loss**: Apply fixed take profit and stop loss levels.
  - `apply_tp_sl(df, tp_percentage, sl_percentage)`
- **Trailing Stop Loss**: Implement dynamic trailing stop loss orders.
  - `apply_tp_sl_trailing(df, tp_percentage, sl_percentage)`
- **Comprehensive Metrics**: Calculates a suite of performance metrics including:
  - Sharpe Ratio
  - Sortino Ratio
  - Calmar Ratio
  - Max Drawdown
  - Win Rate
  - Profit Factor
  - Risk of Ruin
- **Flexible PnL Calculation**: Supports both raw PnL and PnL after accounting for fees.
```

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

### Apply Take Profit/Stop Loss using Python

Source: https://github.com/xno-quant/xnoapi/blob/main/README.md

Applies Take Profit and Stop Loss levels to a backtested trading strategy represented by a DataFrame. Requires percentages for TP and SL. This is a feature of the 'xnoapi.metrics.TradingBacktest' class.

```python
apply_tp_sl(df, tp_percentage, sl_percentage)
```

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

### Get Market Indices and Snapshots

Source: https://github.com/xno-quant/xnoapi/blob/main/source/index.txt

Retrieves a list of market indices and a snapshot of a specific index's performance. This function requires access to market data and returns a pandas DataFrame with index details.

```python
print("Ping:", 'OK' if Trading and True else 'Loaded')
print("Indices:")
display(get_indices().head(1))

print("VNINDEX snapshot:")
display(get_market_index_snapshot('VNINDEX').head(1))
```

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

### Backtesting Derivates API

Source: https://github.com/xno-quant/xnoapi/blob/main/README.md

Perform logic backtesting for derivative trading strategies, incorporating Vietnamese trading fee models.

```APIDOC
## Backtesting Derivates API (`xnoapi.vn.metrics.Backtest_Derivates`)

This module facilitates backtesting for derivative trading strategies with the following features:

- **Derivative Strategy Backtesting**: Implements backtesting logic for derivative trading.
- **Vietnamese Fee Model**: Supports standard Vietnamese transaction and overnight fees.
- **PnL Calculation**: Computes both gross Profit and Loss (PnL) and PnL after fees.
- **Minimum Capital Estimation**: Provides an estimate of the minimum capital required for the strategy.
```

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

### Backtest VN30 Futures Strategy with Fees

Source: https://context7.com/xno-quant/xnoapi/llms.txt

This Python code backtests a derivatives trading strategy for VN30 futures, incorporating Vietnamese market fees and overnight charges. It uses a simple moving average crossover strategy and provides detailed performance metrics.

```python
from xnoapi.vn.data import get_derivatives_hist
from xnoapi.vn.metrics import Backtest_Derivates, Metrics
import numpy as np
import pandas as pd

# Get VN30F1M data (5-minute bars)
df = get_derivatives_hist("VN30F1M", "5m")

# Create simple moving average crossover strategy
df['sma_fast'] = df['Close'].rolling(window=20).mean()
df['sma_slow'] = df['Close'].rolling(window=50).mean()

# Generate position signals (1 = long, -1 = short, 0 = flat)
df['position'] = 0
df.loc[df['sma_fast'] > df['sma_slow'], 'position'] = 1   # Long
df.loc[df['sma_fast'] < df['sma_slow'], 'position'] = -1  # Short

# Clean date/time columns
df['Date'] = pd.to_datetime(df['Date']).dt.strftime('%Y-%m-%d')
df['time'] = pd.to_datetime(df['time'], format='%H:%M:%S').dt.strftime('%H:%M:%S')

# Run backtest with fee calculation
backtest = Backtest_Derivates(df, pnl_type='after_fees')

# Get cumulative PNL
cumulative_pnl = backtest.PNL()
print(f"Final PNL: {cumulative_pnl.iloc[-1]:,.0f} points")

# Get daily aggregated PNL
daily_pnl = backtest.daily_PNL()
print(f"Total trading days: {len(daily_pnl)}")

# Estimate minimum capital required
min_capital = backtest.estimate_minimum_capital()
print(f"Minimum capital needed: {min_capital:,.0f} VND")

# Calculate performance metrics
metrics = Metrics(backtest)
print("\n=== Strategy Performance ===")
print(f"Sharpe Ratio: {metrics.sharpe():.3f}")
print(f"Sortino Ratio: {metrics.sortino():.3f}")
print(f"Calmar Ratio: {metrics.calmar():.3f}")
print(f"Max Drawdown: {metrics.max_drawdown()*100:.2f}%")
print(f"Win Rate: {metrics.win_rate()*100:.1f}%")
print(f"Profit Factor: {metrics.profit_factor():.3f}")
print(f"Avg Win: {metrics.avg_win():.2f}")
print(f"Avg Loss: {metrics.avg_loss():.2f}")
print(f"Value at Risk (5%): {metrics.value_at_risk(0.05):.2f}")
print(f"Risk of Ruin: {metrics.risk_of_ruin():.6f}")
```

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

### Get Company Subsidiaries using Python

Source: https://github.com/xno-quant/xnoapi/blob/main/README.md

Retrieves a list of a company's subsidiary companies using its stock symbol. Accessed via the 'xnoapi.vn.data.stocks.Company' class. Lists all controlled entities.

```python
c = Company("VIC")
print("\nVIC.Company.subsidiaries:")
c.subsidiaries()
```

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

### Performance Metrics API

Source: https://github.com/xno-quant/xnoapi/blob/main/README.md

Analyze and evaluate trading strategy performance using various quantitative metrics.

```APIDOC
## Performance Metrics API (`xnoapi.vn.metrics.Metrics`)

This module provides key performance indicators for evaluating investment strategies:

- **Sharpe Ratio**: Measures risk-adjusted return.
- **Sortino Ratio**: Focuses on downside risk-adjusted return.
- **Calmar Ratio**: Relates average annual return to the maximum drawdown.
- **Max Drawdown**: Identifies the largest peak-to-trough decline in portfolio value.
- **Average Gain/Loss**: Calculates the average profit or loss per trade.
- **Win Rate**: The percentage of profitable trades.
- **Profit Factor**: Gross profits divided by gross losses.
- **Value at Risk (VaR)**: Estimates potential loss at a given confidence level.
- **Risk of Ruin**: The probability of losing all trading capital.
```

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

### Analyze Open-End Funds and International Markets (Python)

Source: https://github.com/xno-quant/xnoapi/blob/main/source/index.txt

This snippet demonstrates how to analyze open-end funds and compare international market indices using the xnoapi library. It fetches fund listings, top holdings, and historical data for VNINDEX, S&P 500, and Nikkei 225, as well as USD/VND exchange rates. Dependencies include the `xnoapi` library and `datetime`.

```python
from xnoapi.vn.data.stocks import Fund, Global
import datetime as dt

# Phân tích quỹ mở
fund = Fund()

# Tìm quỹ cổ phiếu
stock_funds = fund.listing(fund_type="STOCK")
print("Top 5 quỹ cổ phiếu:")
print(stock_funds[["name", "code", "nav", "productNavChange.navTo1Months"]].head())

# Phân tích danh mục của một quỹ cụ thể
if not stock_funds.empty:
    fund_code = stock_funds.iloc[0]["code"]
    holdings = Fund.details.top_holding(fund_code)
    print(f"\nDanh mục top holdings của {fund_code}:")
    print(holdings.head())

# Dữ liệu thị trường quốc tế
glb= Global()

# So sánh VNINDEX với các chỉ số quốc tế
start_date = "2024-01-01"
end_date = "2024-12-31"

vni_data = glb.world_index("VNI").quote.history(start_date, end_date)
spy_data = glb.world_index("INX").quote.history(start_date, end_date)  # S&P 500
nikkei_data = glb.world_index("N225").quote.history(start_date, end_date)

print("\nSo sánh hiệu suất chỉ số 2024:")
print("=" * 40)

def calculate_return(df):
    if df.empty or df["close"].isna().all():
        return 0
    return (df["close"].iloc[-1] / df["close"].iloc[0] - 1) * 100

vni_return = calculate_return(vni_data)
spy_return = calculate_return(spy_data)
nikkei_return = calculate_return(nikkei_data)

print(f"VNINDEX: {vni_return:.2f}%")
print(f"S&P 500: {spy_return:.2f}%")
print(f"Nikkei 225: {nikkei_return:.2f}%")

# Tỷ giá USD/VND
usd_vnd = glb.fx("USDVND").quote.history(start_date, end_date)
if not usd_vnd.empty:
    usd_change = calculate_return(usd_vnd)
    print(f"USD/VND: {usd_change:.2f}%")
```

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

### Get Company News using Python

Source: https://github.com/xno-quant/xnoapi/blob/main/README.md

Retrieves recent news articles related to a company's activities using its stock symbol. Available through the 'xnoapi.vn.data.stocks.Company' class. Provides a feed of relevant news.

```python
c = Company("FPT")
print("\nFPT.Company.news:")
c.news()
```

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

### Get Company Officers using Python

Source: https://github.com/xno-quant/xnoapi/blob/main/README.md

Fetches details about a company's management team (officers) using its stock symbol. This method is available in the 'xnoapi.vn.data.stocks.Company' class. Provides names and titles of key personnel.

```python
c = Company("VNM")
print("\nVNM.Company.officers:")
c.officers()
```

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

### Get Stock Information (HPG)

Source: https://github.com/xno-quant/xnoapi/blob/main/source/index.txt

Fetches detailed information for a specific stock symbol, including general info, trade matches, top prices, and foreign trading data. This function requires a valid stock symbol as input.

```python
symbol = 'HPG'
print("Stock info HPG:")
display(get_stock_info(symbol).head(1))

print("Stock matches HPG:")
display(get_stock_matches(symbol).head(1))

print("Stock top price HPG:")
display(get_stock_top_price(symbol).head(1))

print("Foreign trading:")
display(get_stock_foreign_trading(symbol).head(1))
```

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

### Company, Finance, Fund, and Listing Data (HPG)

Source: https://github.com/xno-quant/xnoapi/blob/main/source/index.txt

Demonstrates how to retrieve company-specific data, financial statements, fund listings, and exchange information. This involves instantiating Company, Finance, Fund, and Listing objects with appropriate parameters.

```python
comp = Company('HPG')
print('Company overview:')
display(comp.overview().head(1))

print('Company profile:')
display(comp.profile().head(1))

fin = Finance('HPG')
print('Income statement (year):')
display(fin.income_statement(period='year').head(1))

f = Fund()
print('Funds listing (head):')
display(f.listing().head(1))

lst = Listing()
print('Listing symbols_by_exchange:')
print(lst.symbols_by_exchange())
```

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

### Get Company Events using Python

Source: https://github.com/xno-quant/xnoapi/blob/main/README.md

Fetches important upcoming and past events for a company using its stock symbol. This function belongs to the 'xnoapi.vn.data.stocks.Company' class. Includes earnings dates, dividend dates, etc.

```python
c = Company("VCB")
print("\nVCB.Company.events:")
c.events()
```

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

### Apply Trailing Stop Loss using Python

Source: https://github.com/xno-quant/xnoapi/blob/main/README.md

Implements a trailing stop loss mechanism for a backtested trading strategy DataFrame. Takes TP and SL percentages as input. Part of the enhanced 'xnoapi.metrics.TradingBacktest' class.

```python
apply_tp_sl_trailing(df, tp_percentage, sl_percentage)
```

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

### Fund Data API

Source: https://github.com/xno-quant/xnoapi/blob/main/README.md

Access information about open-end funds, including listings and search capabilities.

```APIDOC
## Fund Data Endpoints

### Fund Listing

- **Method**: Not applicable (function call)
- **Endpoint**: `Fund().listing(fund_type="")`
- **Description**: Retrieves a list of open-end funds, optionally filtered by type.
- **Parameters**: 
  - `fund_type` (string) - Optional - Filters funds by type (e.g., 'BALANCED', 'BOND', 'STOCK').
- **Request Example**: 
```python
from xnoapi.vn.data.stocks import Fund
fund = Fund()
fund.listing(fund_type="STOCK")
```

### Fund Search

- **Method**: Not applicable (function call)
- **Endpoint**: `Fund().filter(q)`
- **Description**: Searches for funds by name.
- **Parameters**: 
  - `q` (string) - Required - The search query for the fund name.
- **Request Example**: 
```python
fund = Fund()
fund.filter('RVPIF')
```
```

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

### Get Cash Flow Statement using Python

Source: https://github.com/xno-quant/xnoapi/blob/main/README.md

Retrieves the cash flow statement for a company for a specified period (year or quarter). Requires the 'xnoapi.vn.data.stocks.Finance' class and a stock symbol. Shows cash generated from operating, investing, and financing activities.

```python
f = Finance("VNM")
print("\nACB.Finance.cash_flow(year):")
f.cash_flow(period="year")
```

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

### Get Global FX Quotes

Source: https://github.com/xno-quant/xnoapi/blob/main/source/index.txt

Retrieves historical FX data for a specified currency pair. It uses the Global class and its fx method to fetch data, with a history function to specify the date range and interval. Returns an empty DataFrame if no data is found.

```python
from xnoapi.global_module import Global

g = Global()
print('FX EURUSD:')
df_fx = g.fx('EURUSD').quote.history('2024-01-01', '2024-03-01', '1h')
print(df_fx.head())
```

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

### Company, Finance, Fund, and Listing APIs

Source: https://github.com/xno-quant/xnoapi/blob/main/source/index.txt

Access detailed company information, financial statements, fund listings, and stock exchange data.

```APIDOC
## GET /api/company/overview

### Description
Retrieves an overview of a company, including its industry, establishment details, and stock rating.

### Method
GET

### Endpoint
/api/company/overview

### Parameters
#### Query Parameters
- **symbol** (string) - Required - The stock symbol (e.g., 'HPG').

### Request Example
None

### Response
#### Success Response (200)
- **exchange** (string) - The stock exchange the company is listed on.
- **shortName** (string) - The short name of the company.
- **industryID** (integer) - The industry ID.
- **industryIDv2** (integer) - The industry ID v2.
- **industryIdLevel2** (integer) - The level 2 industry ID.
- **industryIdLevel4** (integer) - The level 4 industry ID.
- **industry** (string) - The industry name.
- **industryEn** (string) - The industry name in English.
- **establishedYear** (integer) - The year the company was established.
- **noEmployees** (integer) - The number of employees.
- **noShareholders** (integer) - The number of shareholders.
- **foreignPercent** (float) - The percentage of foreign ownership.
- **website** (string) - The company's website.
- **stockRating** (float) - The stock rating.
- **deltaInWeek** (float) - The stock price change in the last week.
- **deltaInMonth** (float) - The stock price change in the last month.
- **deltaInYear** (float) - The stock price change in the last year.
- **outstandingShare** (float) - The number of outstanding shares.
- **issueShare** (float) - The number of issued shares.
- **companyType** (string) - The type of company.
- **ticker** (string) - The stock ticker symbol.

#### Response Example
```json
{
  "exchange": "HOSE",
  "shortName": "Hòa Phát",
  "industryID": 159,
  "industryIDv2": 1757,
  "industryIdLevel2": 1700,
  "industryIdLevel4": 1757,
  "industry": "Tài nguyên Cơ bản",
  "industryEn": "Basic Resources",
  "establishedYear": 2001,
  "noEmployees": 32780,
  "noShareholders": 165914,
  "foreignPercent": 0.191,
  "website": "http://www.hoaphat.com.vn",
  "stockRating": 3.1,
  "deltaInWeek": 0.041,
  "deltaInMonth": 0.022,
  "deltaInYear": 0.09,
  "outstandingShare": 7675.5,
  "issueShare": 7675.5,
  "companyType": "CT",
  "ticker": "HPG"
}
```

## GET /api/company/profile

### Description
Retrieves the detailed profile of a company, including its description, history, and business strategies.

### Method
GET

### Endpoint
/api/company/profile

### Parameters
#### Query Parameters
- **symbol** (string) - Required - The stock symbol (e.g., 'HPG').

### Request Example
None

### Response
#### Success Response (200)
- **id** (string or null) - The company ID.
- **companyName** (string) - The full name of the company.
- **ticker** (string or null) - The stock ticker symbol.
- **companyProfile** (string) - A description of the company profile.
- **historyDev** (string) - The company's development history.
- **companyPromise** (string) - The company's promises.
- **businessRisk** (string) - Information on business risks.
- **keyDevelopments** (string) - Key developments of the company.
- **businessStrategies** (string) - The company's business strategies.

#### Response Example
```json
{
  "id": null,
  "companyName": "Công ty Cổ phần Tập đoàn Hòa Phát",
  "ticker": null,
  "companyProfile": "<div style=\"FONT-FAMILY: Arial; FONT-SIZE: 10p...",
  "historyDev": "<div style=\"FONT-FAMILY: Arial; FONT-SIZE: 10p...",
  "companyPromise": "<div style=\"FONT-FAMILY: Arial; FONT-SIZE: 10p...",
  "businessRisk": "<div style=\"FONT-FAMILY: Arial; FONT-SIZE: 10p...",
  "keyDevelopments": "<div style=\"FONT-FAMILY: Arial; FONT-SIZE: 10p...",
  "businessStrategies": "<div style=\"FONT-FAMILY: Arial; FONT-SIZE: 10p..."
}
```

## GET /api/finance/income_statement

### Description
Retrieves the income statement for a company, available on a quarterly or yearly basis.

### Method
GET

### Endpoint
/api/finance/income_statement

### Parameters
#### Query Parameters
- **symbol** (string) - Required - The stock symbol (e.g., 'HPG').
- **period** (string) - Optional - The period for the income statement ('year' or 'quarter'). Defaults to 'year'.

### Request Example
None

### Response
#### Success Response (200)
- **ticker** (string) - The stock ticker symbol.
- **quarter** (integer) - The quarter of the financial statement.
- **year** (integer) - The year of the financial statement.
- **revenue** (float) - Total revenue.
- **yearRevenueGrowth** (float) - Year-over-year revenue growth.
- **quarterRevenueGrowth** (float or null) - Quarter-over-quarter revenue growth.
- **costOfGoodSold** (float) - Cost of goods sold.
- **grossProfit** (float) - Gross profit.
- **operationExpense** (float) - Operating expenses.
- **operationProfit** (float) - Operating profit.
- **yearOperationProfitGrowth** (float) - Year-over-year operating profit growth.
- **quarterOperationProfitGrowth** (float or null) - Quarter-over-quarter operating profit growth.
- **interestExpense** (float or null) - Interest expense.
- **preTaxProfit** (float) - Profit before tax.
- **postTaxProfit** (float) - Profit after tax.
- **shareHolderIncome** (float) - Income attributable to shareholders.
- **yearShareHolderIncomeGrowth** (float) - Year-over-year shareholder income growth.
- **quarterShareHolderIncomeGrowth** (float or null) - Quarter-over-quarter shareholder income growth.
- **investProfit** (float or null) - Investment profit.
- **serviceProfit** (float or null) - Service profit.
- **otherProfit** (float or null) - Other profit.
- **provisionExpense** (float or null) - Provision expense.
- **operationIncome** (float) - Operating income.
- **ebitda** (float) - Earnings before interest, taxes, depreciation, and amortization.

#### Response Example
```json
{
  "ticker": "HPG",
  "quarter": 5,
  "year": 2024,
  "revenue": 138855,
  "yearRevenueGrowth": 0.167,
  "quarterRevenueGrowth": null,
  "costOfGoodSold": -120358,
  "grossProfit": 18498,
  "operationExpense": -3883,
  "operationProfit": 14615,
  "yearOperationProfitGrowth": 0.511,
  "quarterOperationProfitGrowth": null,
  "interestExpense": -2287,
  "preTaxProfit": 13694,
  "postTaxProfit": 12020,
  "shareHolderIncome": 12021,
  "yearShareHolderIncomeGrowth": 0.759,
  "quarterShareHolderIncomeGrowth": null,
  "investProfit": null,
  "serviceProfit": null,
  "otherProfit": null,
  "provisionExpense": null,
  "operationIncome": null,
  "ebitda": 21530
}
```

## GET /api/fund/listing

### Description
Retrieves a list of available funds.

### Method
GET

### Endpoint
/api/fund/listing

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **Example fields**: This endpoint is expected to return a list of fund objects, where each object contains details like fund name, ID, and performance metrics. (Specific fields depend on implementation).

#### Response Example
```json
{
  "fund_id": "FUND001",
  "fund_name": "Example Growth Fund",
  "nav": 10.50,
  "performance_1y": "15.2%"
}
```

## GET /api/listing/symbols_by_exchange

### Description
Retrieves a list of stock symbols categorized by their respective exchanges.

### Method
GET

### Endpoint
/api/listing/symbols_by_exchange

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **Example fields**: This endpoint is expected to return a JSON object where keys are exchange names and values are lists of stock symbols traded on that exchange. (Specific fields depend on implementation).

#### Response Example
```json
{
  "HOSE": ["HPG", "VNM", "VIC"],
  "HNX": ["ACB", "SHB"]
}
```
```

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

### Derivatives Historical Data

Source: https://context7.com/xno-quant/xnoapi/llms.txt

Access high-frequency derivatives data for VN30 futures with multiple timeframe support.

```APIDOC
## Derivatives Historical Data - High-Frequency Trading

### Description
Access high-frequency derivatives data for VN30 futures with multiple timeframe support.

### Method
`get_derivatives_hist(symbol, resolution)`

### Endpoint
`/vn/data/get_derivatives_hist`

### Parameters
#### Path Parameters
None

#### Query Parameters
- **symbol** (str) - Required - The derivatives symbol (e.g., "VN30F1M").
- **resolution** (str) - Required - The data resolution. Supported values: "1m", "5m", "15m", "30m", "1H", "1D".

### Request Example
```python
from xnoapi.vn.data import get_derivatives_hist

# Get 1-minute bars for VN30F1M (front month contract)
vn30_1m = get_derivatives_hist("VN30F1M", "1m")
print(vn30_1m.head())

# Get 5-minute aggregated data
vn30_5m = get_derivatives_hist("VN30F1M", "5m")
```

### Response
#### Success Response (200)
- **Date** (str) - The date of the data point.
- **time** (str) - The time of the data point.
- **Open** (float) - The opening price.
- **High** (float) - The highest price.
- **Low** (float) - The lowest price.
- **Close** (float) - The closing price.
- **volume** (float) - The trading volume.

#### Response Example
```json
{
  "Date": "2018-08-13",
  "time": "09:01:00",
  "Open": 943.0,
  "High": 943.1,
  "Low": 942.9,
  "Close": 943.1,
  "volume": 220.0
}
```
```

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

### Get Price Board for Multiple Stocks

Source: https://context7.com/xno-quant/xnoapi/llms.txt

Fetches consolidated real-time pricing data for multiple stock symbols, including ceiling/floor prices and foreign trading information. The output is a pandas DataFrame suitable for market scanning and filtering.

```python
from xnoapi.vn.data import Trading

# Get price board for multiple stocks
symbols = ["VCB", "ACB", "TCB", "HPG", "VIC"]
price_board = Trading.price_board(symbols)
print(price_board)

# Returns DataFrame with columns:
# symbol, open, ceiling, floor, ref_price, high, low,
# price_change, price_change_pct, foreign_volume, foreign_room,
# foreign_holding_room, avg_match_volume_2w

# Useful for quick market scanning and filtering
filtered = price_board[price_board['price_change_pct'] > 2.0]
print(f"Stocks up >2%: {filtered['symbol'].tolist()}")
```
Tokens:
Raw