alphasec-py 0.1.0__tar.gz

alphasec_py-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alphasec
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

alphasec_py-0.1.0/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: alphasec-py
+Version: 0.1.0
+Summary: trading sdk for alphasec orderbook dex
+License-Expression: MIT
+License-File: LICENSE
+Author: Alphasec
+Author-email: dev@alphasec.trade
+Requires-Python: >=3.9,<4
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: eth-account (>=0.10.0,<0.14.0)
+Requires-Dist: eth-utils (>=2.1.0,<6.0.0)
+Requires-Dist: httpx (>=0.27.0,<1.0.0)
+Requires-Dist: msgpack (>=1.0.5,<2.0.0)
+Requires-Dist: pydantic (>=2.6.0,<3.0.0)
+Requires-Dist: requests (>=2.31.0,<3.0.0)
+Requires-Dist: web3 (>=7.13.0,<8.0.0)
+Requires-Dist: websocket-client (>=1.5.1,<2.0.0)
+Requires-Dist: websockets (>=13.0,<16.0)
+Description-Content-Type: text/markdown
+
+# Alphasec Python SDK
+
+A trading SDK for the Alphasec orderbook DEX.
+
+[![PyPI version](https://badge.fury.io/py/alphasec.svg)](https://badge.fury.io/py/alphasec)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+
+## 🚀 Quick Start
+
+### Install (Not yet deployed)
+```bash
+pip install alphasec
+```
+
+### Configure (required for examples)
+```bash
+cd examples
+cp config/config.json.example config/config.json
+# Then edit config.json and fill your values
+```
+
+### Minimal config.json
+```json
+{
+  "network": "kairos",
+  "api_url": "https://api.alphasec.trade",
+  "l1_address": "0x...your_L1_address",
+  "l1_wallet": "0x...your_L1_private_key",
+  "l2_wallet": "0x...your_L2_private_key",
+  "session_enabled": false
+}
+```
+
+### Run an example
+```bash
+python examples/market_data/basic_tickers.py
+```
+
+
+## 🌐 Network Information
+
+### Kairos Testnet
+- **API URL**: `https://api-testnet.alphasec.trade`
+- **Websocket URL**: `wss://api-testnet.alphasec.trade/ws`
+- **Network**: `kairos`
+- **L1 Chain ID**: 1001 (Kaia Kairos)
+- **L2 Chain ID**: 41001 (AlphaSec L2)
+
+### Mainnet
+- **API URL**: `https://api.alphasec.trade`
+- **Websocket URL**: `wss://api.alphasec.trade/ws`
+- **Network**: `mainnet`
+- **L1 Chain ID**: 8217 (Kaia Mainnet)
+- **L2 Chain ID**: 48217 (AlphaSec L2)
+
+## 🔐 Security
+
+⚠️ **Important Security Notes:**
+
+- Never commit private keys to version control
+- Use environment variables or secure key management
+- Always test on kairos testnet before mainnet
+- Verify transaction details before signing
+- Blockchain transactions are irreversible
+
+## ⚠️ Disclaimer
+
+This SDK is provided as-is. Trading cryptocurrencies involves substantial risk and may result in significant losses. Always do your own research and never invest more than you can afford to lose. The developers are not responsible for any trading losses incurred while using this SDK.

alphasec_py-0.1.0/README.md

@@ -0,0 +1,69 @@
+# Alphasec Python SDK
+
+A trading SDK for the Alphasec orderbook DEX.
+
+[![PyPI version](https://badge.fury.io/py/alphasec.svg)](https://badge.fury.io/py/alphasec)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+
+## 🚀 Quick Start
+
+### Install (Not yet deployed)
+```bash
+pip install alphasec
+```
+
+### Configure (required for examples)
+```bash
+cd examples
+cp config/config.json.example config/config.json
+# Then edit config.json and fill your values
+```
+
+### Minimal config.json
+```json
+{
+  "network": "kairos",
+  "api_url": "https://api.alphasec.trade",
+  "l1_address": "0x...your_L1_address",
+  "l1_wallet": "0x...your_L1_private_key",
+  "l2_wallet": "0x...your_L2_private_key",
+  "session_enabled": false
+}
+```
+
+### Run an example
+```bash
+python examples/market_data/basic_tickers.py
+```
+
+
+## 🌐 Network Information
+
+### Kairos Testnet
+- **API URL**: `https://api-testnet.alphasec.trade`
+- **Websocket URL**: `wss://api-testnet.alphasec.trade/ws`
+- **Network**: `kairos`
+- **L1 Chain ID**: 1001 (Kaia Kairos)
+- **L2 Chain ID**: 41001 (AlphaSec L2)
+
+### Mainnet
+- **API URL**: `https://api.alphasec.trade`
+- **Websocket URL**: `wss://api.alphasec.trade/ws`
+- **Network**: `mainnet`
+- **L1 Chain ID**: 8217 (Kaia Mainnet)
+- **L2 Chain ID**: 48217 (AlphaSec L2)
+
+## 🔐 Security
+
+⚠️ **Important Security Notes:**
+
+- Never commit private keys to version control
+- Use environment variables or secure key management
+- Always test on kairos testnet before mainnet
+- Verify transaction details before signing
+- Blockchain transactions are irreversible
+
+## ⚠️ Disclaimer
+
+This SDK is provided as-is. Trading cryptocurrencies involves substantial risk and may result in significant losses. Always do your own research and never invest more than you can afford to lose. The developers are not responsible for any trading losses incurred while using this SDK.

alphasec_py-0.1.0/alphasec/__init__.py

@@ -0,0 +1,10 @@
+from .exceptions import AlphasecAPIError
+from .transaction.utils import load_config
+from .transaction.sign import AlphasecSigner
+from .agent import Agent
+from .async_agent import AsyncAgent
+from .api.api import API
+from .api.async_api import AsyncAPI
+from .websocket.ws import WebsocketManager
+from .websocket.async_ws import AsyncWebsocketManager
+from .perp import decode_perp_event, PerpEvent, PerpAgent, AsyncPerpAgent

alphasec_py-0.1.0/alphasec/agent.py

@@ -0,0 +1,191 @@
+from typing import Any, Callable, Optional
+
+from alphasec.api.api import API
+from alphasec.websocket.ws import WebsocketManager
+from alphasec.transaction.sign import AlphasecSigner
+from alphasec.api.utils import market_to_market_id
+from alphasec.perp.agent import PerpAgent
+
+import logging
+# logging.basicConfig(level=logging.DEBUG)
+
+class Agent:
+    def __init__(self, base_url: str, signer: Optional[AlphasecSigner] = None, timeout: Optional[int] = None):
+        self.api = API(base_url, timeout=timeout, signer=signer)
+        self.ws = WebsocketManager(base_url)
+        self.perp = PerpAgent(self)
+
+    # WebSocket lifecycle
+    def start(self) -> None:
+        self.ws.start()
+
+    def stop(self) -> None:
+        self.ws.stop()
+
+    # WebSocket subscriptions
+    def subscribe(self, channel: str, callback: Callable[[Any], None], timeout: Optional[int] = None) -> int:
+        """
+        Subscribe to WebSocket channels with user-friendly channel format.
+        
+        Parameters
+        ----------
+        channel : str
+            Channel in format 'type@target':
+            - 'trade@KAIA/USDT' for trade data
+            - 'ticker@BTC/USDT' for ticker data  
+            - 'depth@ETH/USDT' for order book
+            - 'userEvent@0x123...' for user events
+        callback : Callable
+            Function to handle received messages
+        timeout : int, optional
+            Timeout in seconds
+            
+        Returns
+        -------
+        int
+            Subscription ID for later unsubscribing
+            
+        Examples
+        --------
+        agent.subscribe('trade@KAIA/USDT', print_trades)
+        agent.subscribe('userEvent@0x123...', print_events)
+        """
+        if '@' not in channel:
+            raise ValueError(f"Channel format should be 'type@target', got: {channel}")
+            
+        channel_type, target = channel.split('@', 1)
+        
+        if channel_type in ['trade', 'ticker', 'depth']:
+            # Convert market name to market_id (lazy-load token metadata first)
+            self.api._ensure_initialized()
+            market_id = market_to_market_id(target, self.api.symbol_token_id_map)
+            actual_channel = f"{channel_type}@{market_id}"
+        elif channel_type == 'userEvent':
+            # Use address directly
+            actual_channel = f"{channel_type}@{target}"
+        else:
+            raise ValueError(f"Unsupported channel type: {channel_type}. Use 'trade', 'ticker', 'depth', or 'userEvent'")
+            
+        return self.ws.subscribe(actual_channel, callback, timeout=timeout)
+
+    def unsubscribe(self, channel: str, subscription_id: int, timeout: Optional[int] = None) -> bool:
+        """
+        Unsubscribe from WebSocket channels with user-friendly channel format.
+        
+        Parameters
+        ----------
+        channel : str
+            Channel in format 'type@target' (same as used in subscribe)
+        subscription_id : int
+            ID returned from subscribe()
+        timeout : int, optional
+            Timeout in seconds
+            
+        Examples
+        --------
+        agent.unsubscribe('trade@KAIA/USDT', sub_id)
+        agent.unsubscribe('userEvent@0x123...', sub_id)
+        """
+        if '@' not in channel:
+            raise ValueError(f"Channel format should be 'type@target', got: {channel}")
+            
+        channel_type, target = channel.split('@', 1)
+        
+        if channel_type in ['trade', 'ticker', 'depth']:
+            # Convert market name to market_id (lazy-load token metadata first)
+            self.api._ensure_initialized()
+            market_id = market_to_market_id(target, self.api.symbol_token_id_map)
+            actual_channel = f"{channel_type}@{market_id}"
+        elif channel_type == 'userEvent':
+            # Use address directly
+            actual_channel = f"{channel_type}@{target}"
+        else:
+            raise ValueError(f"Unsupported channel type: {channel_type}. Use 'trade', 'ticker', 'depth', or 'userEvent'")
+            
+        return self.ws.unsubscribe(actual_channel, subscription_id, timeout=timeout)
+
+    # API helpers (commonly used)
+    def order(self, market: str, side: int, price: float, quantity: float, order_type: int, order_mode: int, tp_limit: Optional[float] = None, sl_trigger: Optional[float] = None, sl_limit: Optional[float] = None) -> dict:
+        return self.api.order(market, side, price, quantity, order_type, order_mode, tp_limit, sl_trigger, sl_limit)
+
+    def cancel(self, order_id: str) -> dict:
+        return self.api.cancel(order_id)
+
+    def cancel_all(self) -> dict:
+        return self.api.cancel_all()
+
+    def modify(self, order_id: str, new_price: Optional[float] = None, new_qty: Optional[float] = None, order_mode: Optional[int] = None) -> dict:
+        return self.api.modify(order_id, new_price, new_qty, order_mode)
+
+    def value_transfer(self, to: str, value: float) -> dict:
+        return self.api.value_transfer(to, value)
+
+    def token_transfer(self, to: str, value: float, token: str) -> dict:
+        return self.api.token_transfer(to, value, token)
+
+    def withdraw(self, token: str, value: float) -> dict:
+        return self.api.withdraw_to_kaia(token, value)
+
+    def deposit(self, token: str, value: float) -> dict:
+        return self.api.deposit_to_alphasec(token, value)
+
+    # State accessors
+    @property
+    def l1_address(self):
+        return self.api.signer.l1_address if self.api.signer else None
+
+    def is_session_enabled(self) -> bool:
+        return bool(self.api.signer and self.api.signer.session_enabled)
+
+    # Market data helpers
+    def get_depth(self, market: str, limit: int = 100) -> dict:
+        return self.api.get_depth(market, limit)
+
+    def get_ticker(self, market: str) -> dict:
+        return self.api.get_ticker(market)
+
+    def get_tickers(self) -> list[dict]:
+        return self.api.get_tickers()
+
+    def get_market_list(self) -> list[dict]:
+        return self.api.get_market_list()
+
+    def get_trades(self, market: str, limit: int = 100) -> list[dict]:
+        return self.api.get_trades(market, limit)
+
+    def get_tokens(self) -> list[dict]:
+        return self.api.get_tokens()
+
+    # Order history helpers
+    def get_open_orders(self, addr: str, market: str, limit: int = 100, from_msec: Optional[int] = None, end_msec: Optional[int] = None) -> list[dict]:
+        return self.api.get_open_orders(addr, market, limit, from_msec, end_msec)
+
+    def get_filled_canceled_orders(self, addr: str, market: str, limit: int = 100, from_msec: Optional[int] = None, end_msec: Optional[int] = None) -> list[dict]:
+        return self.api.get_filled_canceled_orders(addr, market, limit, from_msec, end_msec)
+
+    def get_order_by_id(self, order_id: str) -> dict:
+        return self.api.get_order_by_id(order_id)
+
+    # Wallet/session helpers
+    def get_balance(self, addr: str) -> dict:
+        return self.api.get_balance(addr)
+
+    def get_sessions(self, addr: str) -> list[dict]:
+        return self.api.get_sessions(addr)
+
+    def get_transfer_history(self, addr: str, token_id: Optional[int] = None, from_msec: Optional[int] = None, to_msec: Optional[int] = None, limit: int = 100) -> list[dict]:
+        return self.api.get_transfer_history(addr, token_id, from_msec, to_msec, limit)
+
+    # Session management
+    def create_session(self, session_id: str, session_wallet, expiry: int, nonce: int) -> dict:
+        return self.api.create_session(session_id, session_wallet, expiry, nonce)
+
+    def update_session(self, session_id: str, session_wallet, expiry: int, nonce: int) -> dict:
+        return self.api.update_session(session_id, session_wallet, expiry, nonce)
+
+    def delete_session(self, session_wallet) -> dict:
+        return self.api.delete_session(session_wallet)
+
+    # Additional trading helpers
+    def stop_order(self, market: str, stop_price: int, price: int, quantity: int, side: int, order_type: int, order_mode: int) -> dict:
+        return self.api.stop_order(market, stop_price, price, quantity, side, order_type, order_mode)

alphasec_py-0.1.0/alphasec/api/__init__.py

@@ -0,0 +1,25 @@
+from .constants import (
+    BUY,
+    SELL,
+    LIMIT,
+    MARKET,
+    BASE_MODE,
+    QUOTE_MODE,
+    MAINNET_URL,
+    KAIROS_URL,
+    ALPHASEC_MAINNET_URL,
+    ALPHASEC_KAIROS_URL,
+)
+
+__all__ = [
+    "BUY",
+    "SELL",
+    "LIMIT",
+    "MARKET",
+    "BASE_MODE",
+    "QUOTE_MODE",
+    "MAINNET_URL",
+    "KAIROS_URL",
+    "ALPHASEC_MAINNET_URL",
+    "ALPHASEC_KAIROS_URL",
+]