ssi-sdk 3.0.0__py3-none-any.whl

ssi_sdk/__init__.py

@@ -0,0 +1,24 @@
+"""SSI Python SDK."""
+
+from ssi_sdk._version import __version__
+from ssi_sdk.client import AsyncSSIClient, SSIClient
+from ssi_sdk.config import Config
+from ssi_sdk.exceptions import (
+    APIError,
+    AuthenticationError,
+    SSIError,
+    RateLimitError,
+    ValidationError,
+    WebSocketError,
+)
+__all__ = [
+    "APIError",
+    "AsyncSSIClient",
+    "AuthenticationError",
+    "Config",
+    "SSIClient",
+    "SSIError",
+    "RateLimitError",
+    "ValidationError",
+    "WebSocketError",
+]

ssi_sdk/_version.py

@@ -0,0 +1,3 @@
+"""Single source of truth for the SSI SDK version."""
+
+__version__ = "3.0.0"

ssi_sdk/client.py

@@ -0,0 +1,188 @@
+"""Main SSI client — unified entry point for the SDK (async and sync)."""
+
+from __future__ import annotations
+
+import logging
+
+from ssi_sdk.config import Config
+from ssi_sdk.services.account import AccountService, AsyncAccountService
+from ssi_sdk.services.market_data import AsyncMarketDataService, MarketDataService
+from ssi_sdk.services.portfolio import AsyncPortfolioService, PortfolioService
+from ssi_sdk.services.streaming import AsyncStreamingService, StreamingService
+from ssi_sdk.services.token_manager import AsyncTokenManager, TokenManager
+from ssi_sdk.services.trading import AsyncTradingService, TradingService
+from ssi_sdk.transport.rest_client import AsyncRestClient, RestClient
+from ssi_sdk.transport.websocket_client import AsyncWebSocketClient, WebSocketClient
+from ssi_sdk.utils.logger import get_logger
+
+logger = logging.getLogger("ssi_sdk")
+
+
+class AsyncSSIClient:
+    """Async unified client for the SSI trading platform.
+
+    Provides access to all SDK services:
+
+    - ``token_manager``: Authentication & OTP
+    - ``trading``: Place/cancel/modify orders & condition orders
+    - ``account``: Account info, positions, portfolio, order history
+    - ``market_data``: OHLC, index, security info, FA, TA, download
+    - ``streaming``: Real-time data & portfolio via single WebSocket
+
+    Example::
+
+        from ssi_sdk import AsyncSSIClient, Config
+
+        config = Config(
+            api_key="your_id",
+            api_secret="your_secret",
+        )
+
+        async with AsyncSSIClient(config) as client:
+            ohlc = await client.market_data.get_ohlc("VNM")
+    """
+
+    def __init__(self, config: Config | None = None, **kwargs: object) -> None:
+        if config is None:
+            config = Config(**kwargs)  # type: ignore[arg-type]
+        elif kwargs:
+            for key, value in kwargs.items():
+                if hasattr(config, key):
+                    setattr(config, key, value)
+        self._config = config
+
+        get_logger(level=config.log_level)
+
+        # Transport layer
+        self._rest_client = AsyncRestClient(config)
+        self._ws_client = AsyncWebSocketClient(config)
+
+        # Business services
+        self.token_manager = AsyncTokenManager(self._rest_client, config)
+        self.account = AsyncAccountService(self._rest_client)
+        self.portfolio = AsyncPortfolioService(self._rest_client, config)
+        self.market_data = AsyncMarketDataService(self._rest_client)
+        self.trading = AsyncTradingService(self._rest_client)
+        self.streaming = AsyncStreamingService(self._ws_client)
+
+    async def authenticate(self, otp: str | None = None) -> None:
+        """Authenticate with OTP and distribute token to all transports."""
+        token = await self.token_manager.authenticate(otp)
+        self._ws_client.set_token(token.access_token)
+        logger.info("AsyncSSIClient authenticated")
+
+    async def connect(self) -> None:
+        """Connect WebSocket (must call authenticate first)."""
+        await self._ws_client.connect()
+        logger.info("AsyncSSIClient WebSocket connected")
+
+    async def connect_rest_only(self) -> None:
+        """Authenticate via REST without connecting WebSocket.
+
+        .. deprecated:: Use authenticate(otp) instead.
+        """
+        logger.warning("connect_rest_only is deprecated, use authenticate(otp) instead")
+
+    async def disconnect(self) -> None:
+        """Close all connections and release resources."""
+        await self._ws_client.disconnect()
+        await self._rest_client.close()
+        logger.info("AsyncSSIClient disconnected")
+
+    async def __aenter__(self) -> AsyncSSIClient:
+        """Enter async context manager."""
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: object,
+    ) -> None:
+        """Exit async context manager; disconnects automatically."""
+        await self.disconnect()
+
+
+class SSIClient:
+    """Synchronous unified client for the SSI trading platform.
+
+    Provides access to REST-based SDK services:
+
+    - ``token_manager``: Authentication & OTP
+    - ``trading``: Place/cancel/modify orders & condition orders
+    - ``account``: Account info, positions, portfolio, order history
+    - ``market_data``: OHLC, index, security info, FA, TA, download
+    - ``streaming``: Real-time data & portfolio via single WebSocket
+
+    Example::
+
+        from ssi_sdk import SSIClient, Config
+
+        config = Config(
+            api_key="your_id",
+            api_secret="your_secret",
+        )
+
+        with SSIClient(config) as client:
+            ohlc = client.market_data.get_ohlc("VNM")
+    """
+
+    def __init__(self, config: Config | None = None, **kwargs: object) -> None:
+        if config is None:
+            config = Config(**kwargs)  # type: ignore[arg-type]
+        elif kwargs:
+            for key, value in kwargs.items():
+                if hasattr(config, key):
+                    setattr(config, key, value)
+        self._config = config
+
+        get_logger(level=config.log_level)
+
+        # Transport layer
+        self._rest_client = RestClient(config)
+        self._ws_client = WebSocketClient(config)
+
+        # Business services
+        self.token_manager = TokenManager(self._rest_client, config)
+        self.account = AccountService(self._rest_client)
+        self.portfolio = PortfolioService(self._rest_client, config)
+        self.market_data = MarketDataService(self._rest_client)
+        self.trading = TradingService(self._rest_client)
+        self.streaming = StreamingService(self._ws_client)
+
+    def authenticate(self, otp: str | None = None) -> None:
+        """Authenticate with OTP and distribute token to all transports."""
+        token = self.token_manager.authenticate(otp)
+        self._ws_client.set_token(token.access_token)
+        logger.info("SSIClient authenticated")
+
+    def connect(self) -> None:
+        """Connect WebSocket (must call authenticate first)."""
+        self._ws_client.connect()
+        logger.info("SSIClient WebSocket connected")
+
+    def connect_rest_only(self) -> None:
+        """Authenticate via REST without connecting WebSocket.
+
+        .. deprecated:: Use authenticate(otp) instead.
+        """
+        logger.warning("connect_rest_only is deprecated, use authenticate(otp) instead")
+
+    def disconnect(self) -> None:
+        """Close all connections and release resources."""
+        self._ws_client.disconnect()
+        self._rest_client.close()
+        logger.info("SSIClient disconnected")
+
+    def __enter__(self) -> SSIClient:
+        """Enter context manager."""
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: object,
+    ) -> None:
+        """Exit context manager; disconnects automatically."""
+        self.disconnect()

ssi_sdk/config.py

@@ -0,0 +1,48 @@
+"""Configuration for SSI SDK."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ssi_sdk.constant import (
+    DEFAULT_API_URL,
+    DEFAULT_STREAMING_URL,
+    DEFAULT_TIMEOUT,
+    DEFAULT_RETRY_DELAY,
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_RATE_LIMIT_PER_SECOND,
+)
+
+
+@dataclass
+class Config:
+    """SDK configuration.
+
+    Attributes:
+        client_id: Client ID for API authentication (optional, can be set via env var).
+        api_url: Base URL for the SSI REST API.
+        streaming_url: URL for the SSI WebSocket streaming endpoint.
+        api_key: API key for API authentication.
+        api_secret: API secret for API authentication.
+        private_key: Private key for API authentication.
+        timeout: Request timeout in seconds.
+        max_retries: Maximum number of retry attempts for failed requests.
+        retry_delay: Base delay in seconds between retries (exponential backoff).
+        rate_limit_per_second: Maximum requests per second (0 = unlimited).
+        cache_ttl: Default cache TTL in seconds (0 = no cache).
+        log_level: Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL).
+        proxy: Proxy URL (e.g. 'http://user:pass@host:port' or 'socks5://host:port').
+    """
+    client_id: str
+    api_url: str = DEFAULT_API_URL
+    streaming_url: str = DEFAULT_STREAMING_URL
+    api_key: str = ""
+    api_secret: str = ""
+    private_key: str = ""
+    timeout: int = DEFAULT_TIMEOUT
+    max_retries: int = DEFAULT_MAX_RETRIES
+    retry_delay: float = DEFAULT_RETRY_DELAY
+    rate_limit_per_second: int = DEFAULT_RATE_LIMIT_PER_SECOND
+    cache_ttl: int = 0
+    log_level: str = "INFO"
+    proxy: str | None = None

ssi_sdk/constant.py

@@ -0,0 +1,81 @@
+"""Protocol constants for SSI SDK (fixed by server/spec, not user-configurable)."""
+
+# ---------------------------------------------------------------------------
+# Pagination
+# ---------------------------------------------------------------------------
+DEFAULT_SIZE = 1000
+DEFAULT_PAGE = 1
+# ---------------------------------------------------------------------------
+# Rate Limiting & Retries
+# ---------------------------------------------------------------------------
+DEFAULT_TIMEOUT = 60  # seconds
+DEFAULT_MAX_RETRIES = 5
+DEFAULT_RETRY_DELAY = 2 # seconds (base for exponential backoff)
+DEFAULT_RATE_LIMIT_PER_SECOND = 10
+RATE_LIMITER_SLEEP_INTERVAL = 2  # seconds
+WS_THREAD_JOIN_TIMEOUT = 5  # seconds
+
+# ---------------------------------------------------------------------------
+# HTTP Headers & Auth
+# ---------------------------------------------------------------------------
+HEADER_CONTENT_TYPE = "Content-Type"
+HEADER_ACCEPT = "Accept"
+HEADER_AUTHORIZATION = "Authorization"
+HEADER_RETRY_AFTER = "Retry-After"
+HEADER_SIGNATURE = "X-Signature"
+CONTENT_TYPE_JSON = "application/json"
+AUTH_SCHEME_BEARER = "Bearer "
+
+# ---------------------------------------------------------------------------
+# HTTP Status Codes
+# ---------------------------------------------------------------------------
+HTTP_STATUS_UNAUTHORIZED = 401
+HTTP_STATUS_FORBIDDEN = 403
+HTTP_STATUS_RATE_LIMIT = 429
+HTTP_STATUS_BAD_REQUEST = 400
+HTTP_STATUS_NO_CONTENT = 204
+HTTP_STATUS_ERROR_THRESHOLD = 400
+
+# ---------------------------------------------------------------------------
+# API Endpoints — Authentication
+# ---------------------------------------------------------------------------
+DEFAULT_API_URL = "https://api.ssi.com.vn"
+DEFAULT_STREAMING_URL = "wss://api.ssi.com.vn/ws/v3"
+
+# ---------------------------------------------------------------------------
+# API Endpoints — Authentication
+# ---------------------------------------------------------------------------
+EP_ACCESS_TOKEN = "/api/v3/auth/token"
+EP_REFRESH_TOKEN = "/api/v3/auth/refresh"
+EP_REQUEST_OTP = "/api/v3/auth/requestOtp"
+
+# ---------------------------------------------------------------------------
+# API Endpoints — Market Data
+# ---------------------------------------------------------------------------
+EP_DATA_OHLC = "/api/v3/data/ohlc"
+EP_DATA_OHLC_DOWNLOAD = "/api/v3/data/ohlc/download"
+EP_DATA_INDEX_LIST = "/api/v3/data/indexList"
+EP_DATA_INDEX_SUMMARY = "/api/v3/data/indexSummary"
+EP_DATA_SECURITIES_BY_BOARD = "/api/v3/data/securitiesByBoard"
+EP_DATA_SECURITIES_SUMMARY = "/api/v3/data/securitiesSummary"
+
+# ---------------------------------------------------------------------------
+# API Endpoints — Trading
+# ---------------------------------------------------------------------------
+EP_TRADING_ORDER = "/api/v3/trading/order"
+EP_TRADING_MAX_BUY_SELL = "/api/v3/trading/maxBuySell"
+
+# ---------------------------------------------------------------------------
+# API Endpoints — Portfolio & Account
+# ---------------------------------------------------------------------------
+EP_ACCOUNT_INFO = "/api/v3/account/info"
+EP_ACCOUNT_BALANCE = "/api/v3/trading/accountBalance"
+EP_ACCOUNT_PPMMR = "/api/v3/trading/ppmmrAccount"
+EP_POSITIONS = "/api/v3/trading/position"
+EP_ORDER_HISTORY = "/api/v3/trading/orderBook"
+
+# ---------------------------------------------------------------------------
+# WebSocket Constants
+# ---------------------------------------------------------------------------
+WS_THREAD_NAME = "SSIWebSocketThread"
+WS_KEY_CHANNEL = "channel"

ssi_sdk/enums/__init__.py

@@ -0,0 +1,26 @@
+""" Enums for SSI. """
+from ssi_sdk.enums.account import AccountType
+from ssi_sdk.enums.streaming import (
+    StreamingType,
+    StreamingChannel,
+    StreamingMethod,
+    DataTopic,
+    DataType,
+)
+from ssi_sdk.enums.market_data import Board
+from ssi_sdk.enums.timeframe import Timeframe
+from ssi_sdk.enums.trading import OrderSide, OrderType, OrderStatus
+
+__all__ = [
+    "AccountType",
+    "Board",
+    "OrderSide",
+    "OrderType",
+    "OrderStatus",
+    "Timeframe",
+    "StreamingType",
+    "StreamingChannel",
+    "StreamingMethod",
+    "DataTopic",
+    "DataType",
+]

ssi_sdk/enums/account.py

@@ -0,0 +1,10 @@
+"""Enums for SSI API."""
+
+from enum import Enum
+
+
+class AccountType(Enum):
+    """Enum representing different account types."""
+    EQUITY = "Cash"
+    EQUITY_MARGIN = "Margin"
+    DERIVATIVE = "Derivative"

ssi_sdk/enums/market_data.py

@@ -0,0 +1,10 @@
+"""Enums for SSI API."""
+
+from enum import Enum
+
+
+class Board(Enum):
+    """Enum representing different stock exchange boards."""
+    HOSE = "HOSE"
+    HNX = "HNX"
+    UPCOM = "UPCOM"

ssi_sdk/enums/streaming.py

@@ -0,0 +1,42 @@
+""" Streaming enum for SSI."""
+from enum import Enum
+
+
+class StreamingMethod(Enum):
+    """Enum representing different streaming methods for SSI."""
+    SUBSCRIBE = "subscribe"
+    UNSUBSCRIBE = "unsubscribe"
+    PING_PONG = "ping_pong"
+    LIST_SUBSCRIPTION = "list_subscription"
+
+
+class StreamingChannel(Enum):
+    """Enum representing different streaming channels for SSI."""
+    DATA = "DATA"
+    HEARTBEAT = "HEARTBEAT"
+    TRADING = "TRADING"
+
+
+class StreamingType(Enum):
+    """Enum representing different streaming types for SSI."""
+    ORDER = "orderEvent"
+    ORDER_MATCH = "orderMatchEvent"
+    PORTFOLIO = "clientPortfolioEvent"
+
+class DataTopic(Enum):
+    """Enum representing different data topics for SSI."""
+    QUOTE = "quote."
+    TRADE = "trade."
+    ODD_LOT = "oddlot."
+    MARKET = "market."
+    ROOM = "room."
+    PUT = "put."
+
+class DataType(Enum):
+    """Enum representing different data types for SSI."""
+    QUOTE = "quote"
+    TRADE = "trade"
+    ODD_LOT = "oddlot"
+    MARKET = "market"
+    ROOM = "room"
+    PUT = "put"

ssi_sdk/enums/timeframe.py

@@ -0,0 +1,14 @@
+""" Timeframe enum for SSI. """
+from enum import Enum
+
+
+class Timeframe(Enum):
+    """Enum representing different timeframes for SSI."""
+    MINUTE_1 = "1m"
+    MINUTE_3 = "3m"
+    MINUTE_5 = "5m"
+    MINUTE_15 = "15m"
+    HOUR_1 = "1h"
+    DAY_1 = "1d"
+    WEEK_1 = "1w"
+    MONTH_1 = "1M"

ssi_sdk/enums/trading.py

@@ -0,0 +1,35 @@
+""" Trading enum for SSI. """
+from enum import Enum
+
+
+class OrderSide(Enum):
+    """Enum representing order sides for SSI."""
+    BUY = "B"
+    SELL = "S"
+
+class OrderType(Enum):
+    """Enum representing different order types for SSI."""
+    ATO = "ATO"
+    ATC = "ATC"
+    LO = "LO"
+    MTL = "MTL"
+    MP = "MP"
+    MOK = "MOK"
+    MAK = "MAK"
+    PLO = "PLO"
+
+class OrderStatus(Enum):
+    """Enum representing order statuses for SSI."""
+    PENDING_APPROVAL = "WA"
+    READY = "RS"
+    SENT = "SD"
+    QUEUED = "QU"
+    FILLED = "FF"
+    PARTIAL_FILLED = "PF"
+    PARTIAL_CANCELLED = "FFPC"
+    PENDING_MODIFY = "WM"
+    PENDING_CANCEL = "WC"
+    CANCELLED = "CL"
+    REJECTED = "RJ"
+    EXPIRED = "EX"
+    PRE_SESSION = "IAV"

ssi_sdk/exceptions.py

@@ -0,0 +1,45 @@
+"""Custom exceptions for SSI SDK."""
+
+
+class SSIError(Exception):
+    """Base exception for all SSI SDK errors."""
+
+    def __init__(self, message: str = "", code: str | None = None):
+        self.message = message
+        self.code = code
+        super().__init__(self.message)
+
+
+class AuthenticationError(SSIError):
+    """Raised when authentication fails (invalid credentials, expired token, etc.)."""
+
+
+class APIError(SSIError):
+    """Raised when the SSI API returns an error response."""
+
+    def __init__(
+        self,
+        message: str = "",
+        code: str | None = None,
+        status_code: int | None = None,
+        response_body: dict | None = None,
+    ):
+        self.status_code = status_code
+        self.response_body = response_body
+        super().__init__(message, code)
+
+
+class WebSocketError(SSIError):
+    """Raised when a WebSocket connection or communication error occurs."""
+
+
+class ValidationError(SSIError):
+    """Raised when input validation fails."""
+
+
+class RateLimitError(SSIError):
+    """Raised when API rate limit is exceeded."""
+
+    def __init__(self, message: str = "", retry_after: float | None = None):
+        self.retry_after = retry_after
+        super().__init__(message, code="RATE_LIMITED")

ssi_sdk/models/__init__.py

@@ -0,0 +1,133 @@
+"""Data models for SSI SDK."""
+
+from ssi_sdk.models.account import Account
+from ssi_sdk.models.portfolio import (
+    AccountBalanceRequest,
+    AccountBalance,
+    EquityAccountBalance,
+    DerivativeAccountBalance,
+    PositionsRequest,
+    Position,
+    DerivativePosition,
+    AllDerivativePosition,
+    EquityPosition,
+    PPMMRRequest,
+    PPMMR,
+    EquityPPMMR,
+    DerivativePPMMR,
+
+    OrderBookRequest,
+    OrderBook,
+)
+from ssi_sdk.models.auth import Token, TokenRequest, OTPRequest, RefreshTokenRequest
+from ssi_sdk.models.market_data import (
+    DownloadData,
+    DownloadDataRequest,
+
+    OHLCRequest,
+    OHLCData,
+
+    MarketIndexes,
+    MarketIndexesRequest,
+
+    MarketIndexSummaryRequest,
+    MarketIndexSummary,
+
+    SecuritiesInfoRequest,
+    SecuritiesInfo,
+)
+from ssi_sdk.models.trading import (
+    PlaceOrderRequest,
+    ModifyOrderRequest,
+    CancelOrderRequest,
+    MaxBuySellRequest,
+    MaxBuySellResponse,
+)
+from ssi_sdk.models.streaming import (
+    RequestMessage,
+
+    HeartbeatMessage,
+
+    ForeignRoomMessage,
+    MarketStatusMessage,
+    OddLotMessage,
+    PutMessage,
+    QuoteMessage,
+    TradeMessage,
+
+    OrderStatusMessage,
+    PortfolioMessage,
+
+)
+
+__all__ = [
+    # -------------------------------------------------------------------------
+    # Authentication models
+    # -------------------------------------------------------------------------
+    "Token",
+    "TokenRequest",
+    "OTPRequest",
+    "RefreshTokenRequest",
+    # -------------------------------------------------------------------------
+    # Account models
+    # -------------------------------------------------------------------------
+    "Account",
+    # -------------------------------------------------------------------------
+    # Market data models
+    # -------------------------------------------------------------------------
+    "DownloadData",
+    "DownloadDataRequest",
+    "OHLCRequest",
+    "OHLCData",
+    "MarketIndexes",
+    "MarketIndexesRequest",
+    "MarketIndexSummary",
+    "MarketIndexSummaryRequest",
+    "SecuritiesInfo",
+    "SecuritiesInfoRequest",
+    # -------------------------------------------------------------------------
+    # Portfolio models
+    # -------------------------------------------------------------------------
+    "AccountBalanceRequest",
+    "AccountBalance",
+    "EquityAccountBalance",
+    "DerivativeAccountBalance",
+    "PositionsRequest",
+    "Position",
+    "DerivativePosition",
+    "AllDerivativePosition",
+    "EquityPosition",
+    # -------------------------------------------------------------------------
+    # PPMMR models
+    # -------------------------------------------------------------------------
+    "PPMMRRequest",
+    "PPMMR",
+    "EquityPPMMR",
+    "DerivativePPMMR",
+    # -------------------------------------------------------------------------
+    # Trading models
+    # -------------------------------------------------------------------------
+    "PlaceOrderRequest",
+    "ModifyOrderRequest",
+    "CancelOrderRequest",
+    "MaxBuySellRequest",
+    "MaxBuySellResponse",
+    # -------------------------------------------------------------------------
+    # Streaming models
+    # -------------------------------------------------------------------------
+    "RequestMessage",
+    "HeartbeatMessage",
+    "TradeMessage",
+    "QuoteMessage",
+    "MarketStatusMessage",
+    "ForeignRoomMessage",
+    "PutMessage",
+    "OddLotMessage",
+    "OrderStatusMessage",
+    "PortfolioMessage",
+    # -------------------------------------------------------------------------
+    # Order book models (not implemented yet)
+    # -------------------------------------------------------------------------
+    "OrderBookRequest",
+    "OrderBook",
+]