quant-agent 0.3.0__py3-none-any.whl

quant_agent/__init__.py

@@ -0,0 +1,25 @@
+"""
+quant_agent (quant-agent): Vietnamese stock market data, read-only, no account/API key needed.
+
+Every function below is exposed at the top level (`quant_agent.stock_historical_data(...)`,
+etc.) via the re-exports below, so submodule names (technical, fundamental, ...) are
+an internal organizing detail, not part of the public API contract.
+
+The one exception is the `broker` subpackage (e.g. `DNSEClient`): it performs
+real authenticated trading (login, place_order, cancel_order) against a real
+brokerage account, a fundamentally different risk profile from the rest of
+this read-only library. It's re-exported here too for backward
+compatibility, but see `broker/__init__.py` before using it.
+"""
+
+__author__ = "quant-agent"
+
+from .config import *       # date helpers + re-exports the `sources` subpackage
+from .utils import *
+from .fundamental import *  # stock listing, company profile, financials
+from .technical import *    # historical/intraday OHLC price data
+from .trading import *      # price board, price depth, intraday trades
+from .funds import *        # mutual fund data
+from .chart import *        # candlestick / Bollinger Bands visualization
+from .integration import *  # third-party data export (Amibroker)
+from .broker import *       # authenticated brokerage trading clients - see broker/__init__.py

quant_agent/broker/__init__.py

@@ -0,0 +1,20 @@
+"""
+Authenticated brokerage trading clients - login, place/cancel real orders,
+check balances. A DIFFERENT RISK CATEGORY from every other package in
+quant_agent, which is read-only market data requiring no account or credentials.
+Nothing here is called automatically; each client must be constructed and
+logged in explicitly.
+
+To add a new broker: create `broker/<name>.py` with its own client class
+(see `dnse.py` for the shape: `login`, `place_order`, `cancel_order`,
+account/balance getters), then add one line below (both the
+`from .<name> import *` AND its client class name in `__all__` - see
+`sources/__init__.py` for why `__all__` matters here). There's no shared
+base class yet since only one broker is implemented so far - once a second
+one lands, factor out whatever actually turns out to be common (e.g. the
+Bearer-token-per-request pattern) rather than guessing at an interface now.
+"""
+
+from .dnse import *
+
+__all__ = ['DNSEClient']

quant_agent/broker/dnse.py

@@ -0,0 +1,257 @@
+# DNSE Lightspeed API: https://www.dnse.vn
+"""
+!!! DIFFERENT RISK CATEGORY FROM THE REST OF THIS LIBRARY !!!
+
+Every other module in quant_agent is read-only market data (prices, financials,
+listings). `DNSEClient` below is NOT: it authenticates with real DNSE
+brokerage credentials and can PLACE and CANCEL REAL ORDERS
+(`place_order`, `cancel_order`) against a real trading account with real
+money.
+
+Nothing in this file is called automatically by any other part of quant_agent -
+you must construct a `DNSEClient`, call `.login(...)`, and invoke its
+methods explicitly to do anything with it.
+"""
+
+from ..config import *
+
+
+class DNSEClient:
+    def __init__(self):
+        self.token = None
+        self.trading_token = None
+
+    def login(self, user_name, password):
+        """
+        Authenticate the user and obtain a JWT token for further API requests.
+
+        Args:
+            user_name (str): DNSE username. Can be 064CXXXXX, your email, or your phone number.
+            password (str): Your DNSE password.
+
+        Returns:
+            str: JWT token if authentication is successful, None otherwise.
+        """
+        url = "https://services.entrade.com.vn/dnse-user-service/api/auth"
+        payload = json.dumps({'username': user_name, 'password': password})
+        headers = {'Content-Type': 'application/json'}
+        data = fetch_json('POST', url, headers=headers, data=payload, source='DNSE')
+        if data is None:
+            print('Login failed')
+            return None
+        print('Login successfully')
+        self.token = data['token']
+        return self.token
+
+    def account(self):
+        """
+        Get the full user profile from DNSE.
+
+        Returns:
+            DataFrame: A DataFrame containing the user profile if successful, None otherwise.
+        """
+        url = "https://services.entrade.com.vn/dnse-user-service/api/me"
+        headers = {'Content-Type': 'text/plain', 'Authorization': f'Bearer {self.token}'}
+        data = fetch_json('GET', url, headers=headers, data="N/A", source='DNSE')
+        if data is None:
+            print('Get profile failed')
+            return None
+        print('Get profile successfully')
+        return pd.DataFrame(data, index=[0])
+
+    def sub_accounts(self):
+        """
+        Get sub-accounts information.
+
+        Returns:
+            DataFrame: A DataFrame containing the sub-accounts information if successful, None otherwise.
+        """
+        url = "https://services.entrade.com.vn/dnse-order-service/accounts"
+        headers = {"Authorization": f"Bearer {self.token}"}
+        data = fetch_json('GET', url, headers=headers, source='DNSE')
+        return json_normalize(data['accounts']) if data is not None else None
+
+    def account_balance (self, sub_account):
+        """
+        Get account balance for a specific sub-account.
+
+        Args:
+            sub_account (str): DNSE sub account number (mã tiểu khoản).
+        """
+        url = f"https://services.entrade.com.vn/dnse-order-service/account-balances/{sub_account}"
+        headers = {"Authorization": f"Bearer {self.token}"}
+        data = fetch_json('GET', url, headers=headers, source='DNSE')
+        return json_normalize(data) if data is not None else None
+
+    def email_otp(self):
+        """
+        Trigger an email OTP request to DNSE. The OTP will be sent to the email address associated with the DNSE account.
+
+        Returns:
+            None.
+        """
+        url = "https://services.entrade.com.vn/dnse-auth-service/api/email-otp"
+        headers = {"Authorization": f"Bearer {self.token}"}
+        response = fetch('GET', url, headers=headers, source='DNSE')
+        if response is not None:
+            print("OTP sent to email")
+
+    def get_trading_token(self, otp, smart_otp=True):
+        """
+        Authenticate using OTP and get the trading token.
+
+        Args:
+            otp (str): OTP code for authentication. Input as a string.
+
+        Returns:
+            str: Trading token if authentication is successful, None otherwise.
+        """
+        if smart_otp:
+            url = "https://services.entrade.com.vn/dnse-order-service/trading-token"
+            headers = {"Authorization": f"Bearer {self.token}", "smart-otp": otp}
+        else:
+            url = "https://services.entrade.com.vn/dnse-auth-service/api/email-otp"
+            headers = {"Authorization": f"Bearer {self.token}", "otp": otp}
+        data = fetch_json('POST', url, headers=headers, source='DNSE')
+        if data is None:
+            print("Error authenticating")
+            return None
+        self.trading_token = data.get("tradingToken")
+        print("Authenticated! Trading token returned.")
+        return self.trading_token
+
+    def loan_packages(self, sub_account, asset_type='stock'):
+        """
+        Get the list of loan packages for a specific sub account.
+
+        Args:
+            sub_account (str): DNSE sub account number (mã tiểu khoản).
+            asset_type (str): Asset type, either 'stock' or 'derivative'.
+
+        Returns:
+            DataFrame: A DataFrame containing the list of loan packages if successful, None otherwise.
+        """
+        suffix = 'loan-packages' if asset_type == 'stock' else 'derivative-loan-packages'
+        url = f"https://services.entrade.com.vn/dnse-order-service/accounts/{sub_account}/{suffix}"
+        headers = {"Authorization": f"Bearer {self.token}"}
+        data = fetch_json('GET', url, headers=headers, source='DNSE')
+        return json_normalize(data['loanPackages']) if data is not None else None
+
+    def trade_capacities(self, symbol, price, sub_account, asset_type='stock', loan_package_id=None):
+        """
+        Get the list of trade capacities (sức mua/bán) for a specific sub account.
+
+        Args:
+            symbol (str): Symbol of the asset.
+            price (float): Price of the asset, unit is VND.
+            sub_account (str): DNSE sub account number (mã tiểu khoản).
+            asset_type (str): Asset type, either 'stock' or 'derivative'.
+            loan_package_id (int): Loan package ID (if applicable).
+        Returns:
+            DataFrame: A DataFrame containing the list of trade capacities if successful, None otherwise.
+        """
+        if asset_type == 'stock':
+            url = f'https://services.entrade.com.vn/dnse-order-service/accounts/{sub_account}/ppse'
+            query_params = {"symbol": symbol, "price": price, "loanPackageId": loan_package_id}
+            query_params = {k: v for k, v in query_params.items() if v is not None}
+            if query_params:
+                url += "?" + "&".join(f"{key}={value}" for key, value in query_params.items())
+        else:
+            url = f'https://services.entrade.com.vn/dnse-order-service/accounts/{sub_account}/derivative-ppse?symbol={symbol}&price={price}&loanPackageId={loan_package_id}'
+        headers = {"Authorization": f"Bearer {self.token}"}
+        data = fetch_json('GET', url, headers=headers, source='DNSE')
+        return json_normalize(data) if data is not None else None
+
+    def place_order(self, sub_account, symbol, side, quantity, price, order_type, loan_package_id, asset_type='stock'):
+        """
+        Place an order for stocks or derivatives. THIS SENDS A REAL ORDER TO A REAL
+        BROKERAGE ACCOUNT - it is not a simulation.
+
+        Args:
+            sub_account (str): Sub account number.
+            symbol (str): Symbol of the asset.
+            side (str): 'buy' or 'sell'.
+            quantity (int): Order quantity.
+            price (float): Order price.
+            loan_package_id (int): Loan package ID (if applicable).
+            asset_type (str): Asset type, either 'stock' or 'derivative'.
+
+        Returns:
+            DataFrame: A DataFrame containing the order information if successful, None otherwise.
+        """
+        side_code = 'NB' if side == 'buy' else 'NS'
+        url = ("https://services.entrade.com.vn/dnse-order-service/v2/orders" if asset_type == 'stock'
+               else "https://services.entrade.com.vn/dnse-order-service/derivative/orders")
+        headers = {"Authorization": f"Bearer {self.token}", "Trading-Token": self.trading_token}
+        payload = {
+            "accountNo": sub_account, "symbol": symbol, "side": side_code, "quantity": quantity,
+            "price": price, 'orderType': order_type, "loanPackageId": loan_package_id,
+        }
+        data = fetch_json('POST', url, headers=headers, json=payload, source='DNSE')
+        return json_normalize(data) if data is not None else None
+
+    def order_list(self, sub_account, asset_type='stock'):
+        """
+        Get the list of orders for a specific account.
+
+        Args:
+            sub_account (str): DNSE sub account number (mã tiểu khoản).
+            asset_type (str): Asset type, either 'stock' or 'derivative'.
+
+        Returns:
+            DataFrame: A DataFrame containing the list of orders if successful, None otherwise.
+        """
+        suffix = 'v2/orders' if asset_type == 'stock' else 'derivative/orders'
+        url = f"https://services.entrade.com.vn/dnse-order-service/{suffix}?accountNo={sub_account}"
+        headers = {"Authorization": f"Bearer {self.token}"}
+        data = fetch_json('GET', url, headers=headers, source='DNSE')
+        if data is None:
+            return None
+        print('Order list retrieved')
+        return json_normalize(data['orders'])
+
+    def order_detail(self, order_id, sub_account, asset_type='stock'):
+        """
+        Get the details of a specific order for a specific sub account.
+        Args:
+            order_id (str): Order ID.
+            sub_account (str): DNSE sub account number (mã tiểu khoản).
+            asset_type (str): Asset type, either 'stock' or 'derivative'.
+        """
+        suffix = 'v2/orders' if asset_type == 'stock' else 'derivative/orders'
+        url = f"https://services.entrade.com.vn/dnse-order-service/{suffix}/{order_id}?accountNo={sub_account}"
+        headers = {"Authorization": f"Bearer {self.token}"}
+        data = fetch_json('GET', url, headers=headers, source='DNSE')
+        return json_normalize(data) if data is not None else None
+
+    def cancel_order (self, order_id, sub_account, asset_type='stock'):
+        """
+        Cancel an order. THIS AFFECTS A REAL ORDER ON A REAL BROKERAGE ACCOUNT.
+        Args:
+            order_id (str): Order ID.
+            sub_account (str): DNSE sub account number (mã tiểu khoản).
+            asset_type (str): Asset type, either 'stock' or 'derivative'.
+        """
+        suffix = 'v2/orders' if asset_type == 'stock' else 'derivative/orders'
+        url = f"https://services.entrade.com.vn/dnse-order-service/{suffix}/{order_id}?accountNo={sub_account}"
+        headers = {"Authorization": f"Bearer {self.token}"}
+        response = fetch('DELETE', url, headers=headers, source='DNSE')
+        if response is None:
+            return None
+        print("Order cancelled")
+        return json_normalize(response.json())
+
+    def deals_list (self, sub_account, asset_type='stock'):
+        """
+        Get the list of deals for a specific sub account.
+        Args:
+            sub_account (str): DNSE sub account number (mã tiểu khoản).
+        """
+        url = (f'https://services.entrade.com.vn/dnse-deal-service/deals?accountNo={sub_account}' if asset_type == 'stock'
+               else f'https://services.entrade.com.vn/dnse-derivative-core/deals?accountNo={sub_account}')
+        headers = {"Authorization": f"Bearer {self.token}"}
+        data = fetch_json('GET', url, headers=headers, source='DNSE')
+        if data is None:
+            return None
+        print('Deals list retrieved')
+        return json_normalize(data['data'])

quant_agent/chart.py

@@ -0,0 +1,235 @@
+"""
+Plotly visualizations built on top of the OHLC DataFrame shape returned by
+`technical.stock_historical_data()` (columns: time, open, high, low, close,
+volume, ticker). Pure computation/plotting - no network calls, so nothing
+here is affected by any data source's availability.
+"""
+
+from .config import *
+from .technical import *
+
+import plotly.graph_objs as go
+
+
+# CANDLESTICK CHART
+def candlestick_chart(df, title='Candlestick Chart with MA and Volume', x_label='Date', y_label='Price', ma_periods=None, show_volume=True, figure_size=(15, 8), reference_period=None, colors=('#00F4B0', '#FF3747'), reference_colors=('blue', 'black')):
+    """
+    Generate a candlestick chart with optional Moving Averages (MA) lines, volume data, and reference lines.
+
+    Parameters:
+    - df: DataFrame with candlestick data ('time', 'open', 'high', 'low', 'close', 'volume', 'ticker').
+    - title: Title of the chart.
+    - x_label: Label for the x-axis.
+    - y_label: Label for the y-axis.
+    - ma_periods: List of MA periods to calculate and plot (e.g., [10, 50, 200]).
+    - show_volume: Boolean to indicate whether to display volume data.
+    - figure_size: Tuple specifying the figure size (width, height).
+    - reference_period: Number of days to consider for reference lines (e.g., 90).
+    - colors: Tuple of color codes for up and down candles (e.g., ('#00F4B0', '#FF3747')).
+    - reference_colors: Tuple of color codes for reference lines (e.g., ('black', 'blue')).
+
+    Returns:
+    - Plotly figure object.
+    """
+    # Create the base candlestick chart
+    candlestick_trace = go.Candlestick(
+        x=df['time'],
+        open=df['open'],
+        high=df['high'],
+        low=df['low'],
+        close=df['close'],
+        name='Candlestick',
+    )
+
+    # Create a figure
+    fig = go.Figure(data=[candlestick_trace])
+
+    # Add volume data if specified
+    if show_volume:
+        volume_trace = go.Bar(
+            x=df['time'],
+            y=df['volume'],
+            name='Volume',
+            yaxis='y2',  # Use the secondary y-axis for volume
+            marker=dict(color=[colors[0] if close >= open else colors[1] for close, open in zip(df['close'], df['open'])]),  # Match volume color to candle color
+        )
+
+        fig.add_trace(volume_trace)
+
+    # Add Moving Averages (MA) lines if specified
+    if ma_periods:
+        for period in ma_periods:
+            ma_name = f'{period}-day MA'
+            df[ma_name] = df['close'].rolling(period).mean()
+
+            ma_trace = go.Scatter(
+                x=df['time'],
+                y=df[ma_name],
+                mode='lines',
+                name=ma_name,
+            )
+
+            fig.add_trace(ma_trace)
+
+    # Add straight reference lines for the highest high and lowest low
+    if reference_period:
+        df['lowest_low'] = df['low'].rolling(reference_period).min()
+        df['highest_high'] = df['high'].rolling(reference_period).max()
+
+        lowest_low_trace = go.Scatter(
+            x=df['time'],
+            y=[df['lowest_low'].iloc[-1]] * len(df),  # Create a straight line for lowest low
+            mode='lines',
+            name=f'Lowest Low ({reference_period} days)',
+            line=dict(color=reference_colors[0], dash='dot'),
+        )
+
+        highest_high_trace = go.Scatter(
+            x=df['time'],
+            y=[df['highest_high'].iloc[-1]] * len(df),  # Create a straight line for highest high
+            mode='lines',
+            name=f'Highest High ({reference_period} days)',
+            line=dict(color=reference_colors[1], dash='dot'),
+        )
+
+        fig.add_trace(lowest_low_trace)
+        fig.add_trace(highest_high_trace)
+
+    # Customize the chart appearance
+    fig.update_layout(
+        title=title,
+        xaxis_title=x_label,
+        yaxis_title=y_label,
+        xaxis_rangeslider_visible=True,
+        yaxis2=dict(
+            title='Volume',
+            overlaying='y',
+            side='right',
+        ),
+        width=figure_size[0] * 100,  # Convert short form to a larger size for better readability
+        height=figure_size[1] * 100,
+        margin=dict(l=50, r=50, t=70, b=50),  # Adjust margins for space between title and legend
+    )
+
+    return fig
+
+# BOLLINGER BANDS
+
+def bollinger_bands(df, window=20, num_std_dev=2):
+    """
+    Calculate Bollinger Bands for a DataFrame.
+
+    Parameters:
+    - df: DataFrame with OHLC data ('time', 'open', 'high', 'low', 'close', 'volume', 'ticker').
+    - window: The rolling window size for calculating the moving average and standard deviation.
+    - num_std_dev: The number of standard deviations to use for the Bollinger Bands.
+
+    Returns:
+    - DataFrame with Bollinger Bands ('time', 'upper_band', 'middle_band', 'lower_band').
+    """
+    df['middle_band'] = df['close'].rolling(window=window).mean()
+    df['rolling_std'] = df['close'].rolling(window=window).std()
+    df['upper_band'] = df['middle_band'] + (num_std_dev * df['rolling_std'])
+    df['lower_band'] = df['middle_band'] - (num_std_dev * df['rolling_std'])
+    df.drop(columns=['rolling_std'], inplace=True)
+    return df
+
+def bollinger_bands_chart(df, use_candlestick=True, show_volume=True, fig_size=(15, 8), chart_title='Bollinger Bands Chart', xaxis_title='Date', yaxis_title='Price', bollinger_band_colors=('gray', 'orange', 'gray'), volume_colors=('#00F4B0', '#FF3747')):
+    """
+    Visualize a candlestick chart or close price chart with Bollinger Bands and volume using Plotly.
+
+    Parameters:
+    - df: DataFrame with Bollinger Bands data ('time', 'open', 'high', 'low', 'close', 'volume', 'ticker', 'upper_band', 'middle_band', 'lower_band').
+    - use_candlestick: Boolean to indicate whether to use candlestick chart (default) or close price chart.
+    - show_volume: Boolean to indicate whether to display volume data on the main chart.
+    - fig_size: Tuple specifying the figure size in short form, e.g., (15, 8) equals to (1500, 800) in actual.
+    - chart_title: Title for the chart.
+    - xaxis_title: Title for the x-axis.
+    - yaxis_title: Title for the y-axis.
+    - bollinger_band_colors: Tuple of color codes for the Bollinger Bands (upper, middle, lower).
+    - volume_colors: Tuple of color codes for volume bars on up and down days.
+
+    Returns:
+    - Plotly figure object.
+    """
+    fig = go.Figure()
+
+    if use_candlestick:
+        # Create the candlestick chart
+        candlestick_trace = go.Candlestick(
+            x=df['time'],
+            open=df['open'],
+            high=df['high'],
+            low=df['low'],
+            close=df['close'],
+            name='Candlestick',
+        )
+
+        fig.add_trace(candlestick_trace)
+    else:
+        # Create a chart using close prices
+        close_price_trace = go.Scatter(
+            x=df['time'],
+            y=df['close'],
+            mode='lines',
+            name='Close Price',
+        )
+
+        fig.add_trace(close_price_trace)
+
+    # Create the Bollinger Bands traces
+    upper_band_trace = go.Scatter(
+        x=df['time'],
+        y=df['upper_band'],
+        mode='lines',
+        line=dict(color=bollinger_band_colors[0]),
+        name='Upper Bollinger Band',
+    )
+
+    middle_band_trace = go.Scatter(
+        x=df['time'],
+        y=df['middle_band'],
+        mode='lines',
+        line=dict(color=bollinger_band_colors[1]),
+        name='Middle Bollinger Band',
+    )
+
+    lower_band_trace = go.Scatter(
+        x=df['time'],
+        y=df['lower_band'],
+        mode='lines',
+        line=dict(color=bollinger_band_colors[2]),
+        name='Lower Bollinger Band',
+    )
+
+    fig.add_trace(upper_band_trace)
+    fig.add_trace(middle_band_trace)
+    fig.add_trace(lower_band_trace)
+
+    if show_volume:
+        # Create the volume bars with different colors for up and down days
+        volume_color = [volume_colors[0] if close >= open else volume_colors[1] for close, open in zip(df['close'], df['open'])]
+
+        volume_trace = go.Bar(
+            x=df['time'],
+            y=df['volume'],
+            name='Volume',
+            marker=dict(color=volume_color),
+            yaxis='y2',
+        )
+
+        fig.add_trace(volume_trace)
+
+    # Customize the chart appearance
+    fig.update_layout(
+        title=chart_title,
+        xaxis_title=xaxis_title,
+        yaxis_title=yaxis_title,
+        xaxis_rangeslider_visible=True,
+        # legend=dict(orientation="h", y=1.05),
+        yaxis2=dict(title='Volume', overlaying='y', side='right'),
+        width=fig_size[0] * 100,  # Convert short form width to full width
+        height=fig_size[1] * 100,  # Convert short form height to full height
+    )
+
+    return fig

quant_agent/config.py

@@ -0,0 +1,60 @@
+
+"""
+Date/time helpers used across quant_agent as default values for `start_date`/
+`end_date` parameters, plus a re-export hub: every other module in this
+package does `from .config import *` and expects headers (ssi_headers,
+vci_headers, ...) and HTTP helpers (fetch_json, ...) to be
+available from here. Those actually live in the `sources` subpackage (one
+file per data source, so adding a new source never means editing a shared
+file) - re-exporting them here keeps every module's existing import line
+working unchanged.
+"""
+
+import json
+import time
+from datetime import datetime, timedelta
+
+import pandas as pd
+import requests
+from pandas import json_normalize
+
+# Re-exported for backward compatibility - see the `sources` subpackage.
+from .sources import *
+
+
+def api_request(url, headers=ssi_headers):
+    r = requests.get(url, headers).json()
+    return r
+
+
+# TRADING INTELLIGENT
+today_val = datetime.now()
+
+def today():
+    return today_val.strftime('%Y-%m-%d')
+
+def last_xd (day_num): # return the date of last x days
+    """
+    This function returns the date that X days ago from today in the format of YYYY-MM-DD.
+    Args:
+        day_num (:obj:`int`, required): numer of days.
+    Returns:
+        :obj:`str`:
+            2022-02-22
+    Raises:
+        ValueError: raised whenever any of the introduced arguments is not valid.
+    """
+    return (today_val - timedelta(day_num)).strftime('%Y-%m-%d')
+
+def start_xm (period): # return the start date of x months
+    """
+    This function returns the start date of X months ago from today in the format of YYYY-MM-DD.
+    Args:
+        period (:obj:`int`, required): numer of months (period).
+    Returns:
+        :obj:`str`:
+            2022-01-01
+    Raises:
+        ValueError: raised whenever any of the introduced arguments is not valid.
+    """
+    return pd.date_range(end=today(), periods=period+1, freq='MS')[0].strftime('%Y-%m-%d')

quant_agent/economics.py

@@ -0,0 +1 @@
+# To be updated soon