quant-agent 0.3.0__py3-none-any.whl

quant_agent/technical.py

@@ -0,0 +1,134 @@
+"""
+Historical & intraday OHLC price data.
+  - `ohlc_data` / `stock_historical_data(source='DNSE')` -> DNSE/Entrade.
+  - `longterm_ohlc_data` / `stock_historical_data(source='VCI')` -> VCI (VietCap Securities).
+"""
+
+from .config import *
+
+def stock_historical_data (symbol='TCB', start_date='2023-06-01', end_date='2023-06-17', resolution='1D', type='stock', beautify=True, decor=False, source='DNSE'):
+    """
+    Get historical price data. The unit price is VND.
+    Parameters:
+        symbol (str): ticker of a stock or index. Available indices are: VNINDEX, VN30, HNX, HNX30, UPCOM, VNXALLSHARE, VN30F1M, VN30F2M, VN30F1Q, VN30F2Q
+        start_date (str): start date of the historical price data
+        end_date (str): end date of the historical price data
+        resolution (str): resolution of the historical price data. Default is '1D' (daily), other options are '1' (1 minute), 15 (15 minutes), 30 (30 minutes), '1H' (hourly). For stock, the limit of 90 days is applied to resolution 1, 15, 30, 1H.
+        type (str): stock, index, or derivative. Default is 'stock'
+        beautify (bool): if True, convert open, high, low, close to VND for stock symbols. Default is True which means the unit price is thousands VND
+        decor (bool): if True, rename columns to Title Case (Open, High, Low, Close instead of open, high, low, close) and set Time column as index. Default is False. This option helps integrate quant_agent with other libraries such as TA-Lib out of the box.
+        source (str): data source. Default is 'DNSE' (EntradeX); other option is 'VCI' (VietCap Securities) for longterm daily data.
+    Returns:
+        :obj:`pandas.DataFrame`:
+        | time | open | high | low | close | volume |
+        | ----------- | ---- | ---- | --- | ----- | ------ |
+        | YYYY-mm-dd  | xxxx | xxxx | xxx | xxxxx | xxxxxx |
+    """
+    if source.upper() == 'DNSE':
+        df = ohlc_data(symbol, start_date, end_date, resolution, type, headers=entrade_headers)
+    elif source.upper() == 'VCI':
+        if resolution != '1D':
+            print("VCI only supports longterm daily data. Please set resolution to '1D'")
+            return None
+        df = longterm_ohlc_data(symbol, start_date, end_date, 'D', type)
+    else:
+        print(f"Unknown source '{source}'. Use 'DNSE' or 'VCI'.")
+        return None
+    if df is None:
+        return None
+
+    df = df[['time', 'open', 'high', 'low', 'close', 'volume', 'ticker']]
+    if beautify and type == 'stock':
+        df[['open', 'high', 'low', 'close']] = (df[['open', 'high', 'low', 'close']] * 1000).astype(int)
+    if decor:
+        df.columns = df.columns.str.title()
+        df = df.set_index('Time')
+    return df
+
+
+_VCI_TIMEFRAME_MAP = {'D': 'ONE_DAY', '1D': 'ONE_DAY', 'H': 'ONE_HOUR', '1H': 'ONE_HOUR', '1': 'ONE_MINUTE'}
+
+def longterm_ohlc_data (symbol='REE', start_date='2022-01-01', end_date='2023-10-31', resolution='D', type='stock', headers=None):
+    """
+    Get longterm OHLC data.
+    Data source: VCI (VietCap Securities) chart endpoint. Returns up
+    to 1000 bars per request in a single call.
+    Parameters:
+    symbol (str): ticker of a stock or index, default is 'REE'.
+    start_date (str): start date, 'YYYY-MM-DD'.
+    end_date (str): end date, 'YYYY-MM-DD'.
+    resolution (str): 'D' (daily, default), 'H' (hourly), or '1' (1-minute).
+    type (str): stock, index, or derivative.
+    """
+    timeframe = _VCI_TIMEFRAME_MAP.get(resolution, 'ONE_DAY')
+    start_dt = datetime.strptime(start_date, '%Y-%m-%d')
+    end_dt = datetime.strptime(end_date, '%Y-%m-%d')
+    count_back = (end_dt - start_dt).days + 5  # small buffer for non-trading days
+    to_timestamp = int(end_dt.timestamp())
+
+    url = 'https://trading.vietcap.com.vn/api/chart/OHLCChart/gap-chart'
+    payload = {'timeFrame': timeframe, 'symbols': [symbol], 'to': to_timestamp, 'countBack': count_back}
+    data = fetch_json('POST', url, headers=vci_headers, json=payload, source='VCI')
+    if not data:
+        print(f'No OHLC data returned by VCI for {symbol}.')
+        return None
+
+    bars = data[0]
+    df = pd.DataFrame({
+        'time': pd.to_datetime([int(t) for t in bars['t']], unit='s').strftime('%Y-%m-%d'),
+        'open': bars['o'], 'high': bars['h'], 'low': bars['l'], 'close': bars['c'], 'volume': bars['v'],
+    })
+    df['ticker'] = symbol
+    df = df[(df['time'] >= start_date) & (df['time'] <= end_date)]
+    if type == 'stock':
+        df[['open', 'high', 'low', 'close']] = round(df[['open', 'high', 'low', 'close']] / 1000, 2)
+    df[['open', 'high', 'low', 'close']] = df[['open', 'high', 'low', 'close']].astype(float)
+    df['volume'] = df['volume'].astype(int)
+    return df.reset_index(drop=True)
+
+def ohlc_data (symbol, start_date='2023-06-01', end_date='2023-06-17', resolution='1D', type='stock', headers=entrade_headers):
+    """
+    Get historical price data from entrade.com.vn. The unit price is VND.
+    Parameters:
+        symbol (str): ticker of a stock or index. Available indices are: VNINDEX, VN30, HNX, HNX30, UPCOM, VNXALLSHARE, VN30F1M, VN30F2M, VN30F1Q, VN30F2Q
+        start_date (str): start date of the historical price data
+        end_date (str): end date of the historical price data
+        resolution (str): resolution of the historical price data. Default is '1D' (daily), other options are '1' (1 minute), 15 (15 minutes), 30 (30 minutes), '1H' (hourly)
+        type (str): stock or index. Default is 'stock'
+        headers (dict): headers of the request
+    Returns:
+        :obj:`pandas.DataFrame`:
+        | time | open | high | low | close | volume |
+        | ----------- | ---- | ---- | --- | ----- | ------ |
+        | YYYY-mm-dd  | xxxx | xxxx | xxx | xxxxx | xxxxxx |
+    """
+    end_date = (datetime.strptime(end_date, '%Y-%m-%d') + timedelta(days=1)).strftime('%Y-%m-%d')
+    start_timestamp = int(datetime.strptime(start_date, '%Y-%m-%d').timestamp())
+    end_timestamp = int(datetime.strptime(end_date, '%Y-%m-%d').timestamp())
+
+    # Resolutions finer than 1 day are limited to the most recent 90 days.
+    if resolution != '1D':
+        ninety_days_ago = int(datetime.now().timestamp()) - 90 * 24 * 60 * 60
+        if end_timestamp < ninety_days_ago:
+            print("The 'end_date' value in the report should be no more than 90 days from today for all resolutions shorter than 1 day.\n")
+        elif ninety_days_ago > start_timestamp:
+            start_timestamp = ninety_days_ago
+            print("The retrieval of stock data is restricted to the most recent 90 days from today for all resolutions shorter than 1 day.\n")
+
+    url = f"https://services.entrade.com.vn/chart-api/v2/ohlcs/{type}?from={start_timestamp}&to={end_timestamp}&symbol={symbol}&resolution={resolution}"
+    data = fetch_json('GET', url, headers=headers, source='DNSE')
+    if data is None:
+        return None
+
+    df = pd.DataFrame(data)
+    df['t'] = pd.to_datetime(df['t'], unit='s')
+    df = df.rename(columns={'t': 'time', 'o': 'open', 'h': 'high', 'l': 'low', 'c': 'close', 'v': 'volume'}).drop(columns=['nextTime'])
+    df['ticker'] = symbol
+    df['time'] = df['time'].dt.tz_localize('UTC').dt.tz_convert('Asia/Ho_Chi_Minh')
+    if resolution == '1D':
+        df['time'] = df['time'].dt.date
+    else:
+        df['time'] = df['time'].dt.strftime('%Y-%m-%d %H:%M:%S')
+    df[['open', 'high', 'low', 'close']] = df[['open', 'high', 'low', 'close']].astype(float)
+    df['volume'] = df['volume'].astype(int)
+    return df

quant_agent/trading.py

@@ -0,0 +1,110 @@
+"""
+Trading-side data: live price board, price depth (order book), and intraday
+matched trades.
+
+Data sources:
+  - Price depth (order book)        -> VPS.
+  - Price board, intraday trades    -> VCI (VietCap Securities).
+"""
+
+from .config import *
+
+
+# =============================================================================
+# TRADING PRICE TABLE
+# =============================================================================
+
+def price_depth (stock_list='VPB,TCB', headers=vps_headers):
+    """
+    This function returns the trading price board of a target stocks list.
+    Args:
+      stock_list (:obj:`str`, required): STRING list of symbols separated by "," without any space. Ex: "TCB,SSI,BID"
+    """
+    url = f"https://bgapidatafeed.vps.com.vn/getliststockdata/{stock_list}"
+    data = fetch_json('GET', url, headers=headers, data={}, source='VPS')
+    if data is None:
+        return None
+    df = json_normalize(data)
+    df.rename(columns={'sym': 'Mã CP', 'c': 'Giá Trần', 'f': 'Giá Sàn', 'r': 'Giá tham chiếu', 'lot': 'Tổng Khối Lượng', 'highPrice': 'Giá cao', 'lowPrice': 'Giá thấp', 'avePrice': 'Giá TB', 'lastPrice': 'Giá khớp lệnh', 'lastVolume': 'KL Khớp lệnh', 'ot': '+/- (Khớp lệnh)', 'changePc': '% (Khớp lệnh)', 'fBVol': 'ĐTNN Mua', 'fSVolume': 'ĐTNN Bán', 'fRoom': 'ĐTNN Room'}, inplace=True)
+    # columns g1..g6 pack "price|volume" for 3 bid + 3 ask levels
+    df['Giá mua 3'] = df['g1'].str.split('|').str[0]
+    df['KL mua 3'] = df['g1'].str.split('|').str[1]
+    df['Giá mua 2'] = df['g2'].str.split('|').str[0]
+    df['KL mua 2'] = df['g2'].str.split('|').str[1]
+    df['Giá mua 1'] = df['g3'].str.split('|').str[0]
+    df['KL mua 1'] = df['g3'].str.split('|').str[1]
+    df['Giá bán 1'] = df['g4'].str.split('|').str[0]
+    df['KL bán 1'] = df['g4'].str.split('|').str[1]
+    df['Giá bán 2'] = df['g5'].str.split('|').str[0]
+    df['KL bán 2'] = df['g5'].str.split('|').str[1]
+    df['Giá bán 3'] = df['g6'].str.split('|').str[0]
+    df['KL bán 3'] = df['g6'].str.split('|').str[1]
+    df.drop(columns=['id', 'mc', 'g1', 'g2', 'g3', 'g4', 'g5', 'g6'], inplace=True)
+    df = df[['Mã CP', 'Giá tham chiếu', 'Giá Trần', 'Giá Sàn', 'Giá mua 3', 'KL mua 3', 'Giá mua 2', 'KL mua 2', 'Giá mua 1', 'KL mua 1', 'Giá khớp lệnh', 'KL Khớp lệnh', 'Giá bán 1', 'KL bán 1', 'Giá bán 2', 'KL bán 2', 'Giá bán 3', 'KL bán 3', 'Tổng Khối Lượng', 'ĐTNN Mua', 'ĐTNN Bán', 'ĐTNN Room']]
+    # "Giá*" columns are quoted in thousands VND; convert to whole VND
+    for col in df.columns:
+        if 'Giá' in col:
+            try:
+                df[col] = (df[col].astype(float) * 1000).astype(int)
+            except (ValueError, TypeError):
+                pass
+    return df
+
+def price_board (symbol_ls):
+    """
+    This function returns the trading price board of a target stocks list.
+    Data source: VCI (VietCap Securities). Live bid/ask ladder + match price.
+    Args:
+        symbol_ls (:obj:`str`, required): STRING list of symbols separated by "," without any space. Ex: "TCB,SSI,BID"
+    """
+    symbols = [s.strip() for s in symbol_ls.split(',') if s.strip()] if isinstance(symbol_ls, str) else list(symbol_ls)
+    url = "https://trading.vietcap.com.vn/api/price/symbols/getList"
+    data = fetch_json('POST', url, headers=vci_headers, data=json.dumps({"symbols": symbols}), source='VCI')
+    if not data:
+        print(f'No price board data returned by VCI for {symbols}.')
+        return None
+    rows = []
+    for item in data:
+        row = {}
+        listing = item.get('listingInfo', {}) or {}
+        row['ticker'] = listing.get('ticker')
+        row['exchange'] = listing.get('board')
+        match = item.get('matchPrice', {}) or {}
+        row['matchPrice'] = match.get('matchPrice')
+        row['matchVolume'] = match.get('matchVol')
+        bid_ask = item.get('bidAsk', {}) or {}
+        for i, level in enumerate(bid_ask.get('bidPrices', [])[:3], start=1):
+            row[f'bidPrice{i}'] = level.get('price')
+            row[f'bidVolume{i}'] = level.get('volume')
+        for i, level in enumerate(bid_ask.get('askPrices', [])[:3], start=1):
+            row[f'askPrice{i}'] = level.get('price')
+            row[f'askVolume{i}'] = level.get('volume')
+        rows.append(row)
+    return pd.DataFrame(rows)
+
+def stock_intraday_data (symbol='ACB', page_size=100, page=0, investor_segment=True, headers=None):
+    """
+    Get intraday matched-trade data for a stock.
+    Data source: VCI (VietCap Securities).
+    Parameters:
+        symbol (str): ticker of the stock
+        page_size (int): number of matched trades to fetch (VCI returns them most-recent-first). Default is 100.
+        page (int): unused.
+        investor_segment (bool): unused.
+        headers (dict): unused.
+    """
+    url = "https://trading.vietcap.com.vn/api/market-watch/LEData/getAll"
+    payload = {"symbol": symbol, "limit": page_size, "truncTime": None}
+    records = fetch_json('POST', url, headers=vci_headers, data=json.dumps(payload), source='VCI')
+    if not records:
+        print(f'No intraday data returned by VCI for {symbol}.')
+        return None
+    df = pd.DataFrame(records)
+    df = df.rename(columns={'truncTime': 'time', 'matchPrice': 'price', 'matchVol': 'volume', 'matchType': 'orderType'})
+    df['time'] = pd.to_datetime(df['time'].astype(float), unit='s').dt.tz_localize('UTC').dt.tz_convert('Asia/Ho_Chi_Minh')
+    df['ticker'] = symbol
+    for col in ['price', 'volume']:
+        if col in df.columns:
+            df[col] = df[col].astype(float)
+    keep_cols = [c for c in ['ticker', 'time', 'orderType', 'volume', 'price'] if c in df.columns]
+    return df[keep_cols].reset_index(drop=True)

quant_agent/utils.py

@@ -0,0 +1,53 @@
+"""
+Generic date helper not tied to any specific data source. For the
+`today`/`last_xd`/`start_xm` helpers used as default `start_date`/`end_date`
+values elsewhere in this package, see `config.py` instead.
+"""
+
+from datetime import datetime, timedelta
+from dateutil.relativedelta import relativedelta
+
+def get_date(n, unit):
+    """
+    Return YYYY-mm-dd value from today to n days, months or years in the past
+    Parameters:
+        n: number of days, months or years
+        unit: 'day', 'month' or 'year'
+    """
+    if unit == 'day':
+        return (datetime.now() - timedelta(days=n)).strftime('%Y-%m-%d')
+    elif unit == 'month':
+        return (datetime.now() - relativedelta(months=n)).strftime('%Y-%m-%d')
+    elif unit == 'year':
+        return (datetime.now() - relativedelta(years=n)).strftime('%Y-%m-%d')
+
+# def previous_weekday (date):
+#   date_value = datetime.strptime(date, '%Y-%m-%d')
+#   weekday_name = date_value.strftime('%a')
+#   if weekday_name == 'Sun':
+#     prev_weekday_date = date_value - timedelta(days=2)
+#   elif weekday_name == 'Mon':
+#     prev_weekday_date = date_value - timedelta(days=3)
+#   else:
+#     prev_weekday_date = date_value - timedelta(days=1)
+#   return prev_weekday_date
+
+# def countBack (start_date, end_date):
+#   fd_value = datetime.strptime(start_date, '%Y-%m-%d')
+#   td_value = datetime.strptime(end_date, '%Y-%m-%d')
+#   diff = td_value - fd_value # Calculate the difference
+#   seconds = diff.total_seconds() # Get the total number of seconds
+#   # Define the number of seconds in each scenario
+#   minute = 60
+#   quarter_hour = 15 * minute
+#   hour = 60 * minute
+#   day = 60 * 6 * minute # trading time from 9AM to 3PM which is 6 hours
+#   week = 6 * day
+#   month = 23 * day # maximum of 23 working days in a month
+#   # Calculate the diff in each scenario
+#   diff_minute = round(seconds / minute)
+#   diff_quarter_hour = round(seconds / quarter_hour)
+#   diff_hour = round(seconds / hour)
+#   diff_week = round(seconds / week)
+#   diff_month = round(seconds / month)
+#   return diff_minute, diff_quarter_hour, diff_hour, diff_week, diff_month