x10-python-trading-starknet 2.0.0__tar.gz → 2.2.0__tar.gz

x10_python_trading_starknet-2.2.0/PKG-INFO

@@ -0,0 +1,186 @@
+Metadata-Version: 2.1
+Name: x10-python-trading-starknet
+Version: 2.2.0
+Summary: Python client for X10 API
+Home-page: https://github.com/x10xchange/python_sdk
+Author: X10
+Author-email: tech@ex10.org
+Requires-Python: >=3.10,<4.0
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+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: Topic :: Software Development :: Libraries :: Python Modules
+Provides-Extra: mcp
+Requires-Dist: aiohttp (>=3.10.11)
+Requires-Dist: eth-account (>=0.12.0)
+Requires-Dist: fast-stark-crypto (==0.5.0)
+Requires-Dist: mcp (>=1.28.0) ; extra == "mcp"
+Requires-Dist: pydantic (>=2.9.0)
+Requires-Dist: pyyaml (>=6.0.1)
+Requires-Dist: sortedcontainers (>=2.4.0)
+Requires-Dist: strenum (>=0.4.15)
+Requires-Dist: tenacity (>=9.1.2)
+Requires-Dist: websockets (>=12.0)
+Project-URL: Documentation, https://api.docs.extended.exchange/
+Project-URL: Repository, https://github.com/x10xchange/python_sdk
+Description-Content-Type: text/markdown
+
+# Extended Python SDK
+
+Python client for [Extended API](https://api.docs.extended.exchange/).
+
+Minimum Python version required to use this library is `3.10`
+(you can use [pyenv](https://github.com/pyenv/pyenv) to manage your Python versions easily).
+
+## Installation
+
+```shell
+pip install x10-python-trading-starknet
+```
+
+Our SDK makes use of a [Rust Library Python Wrapper](https://github.com/x10xchange/stark-crypto-wrapper-py) to speed up signing and hashing of stark components.
+Currently, this library supports the following environments (please refer to the library repository for the most up to date information):
+
+|                       | 3.9 | 3.10 | 3.11 | 3.12 | 3.13 |
+|-----------------------|:---:|:----:|:----:|:----:|:----:|
+| linux (glibc) - x86   |  ✅  |  ✅   |  ✅   |  ✅   |  ✅   |
+| linux (musl) - x86    |  ✅  |  ✅   |  ✅   |  ✅   |  ✅   |
+| linux (glibc) - arm64 |  ✅  |  ✅   |  ✅   |  ✅   |  ✅   |
+| linux (musl) - arm64  |  ✅  |  ✅   |  ✅   |  ✅   |  ✅   |
+| OSX - arm64           |  ✅  |  ✅   |  ✅   |  ✅   |  ✅   |
+| windows - x86         |  ✅  |  ✅   |  ✅   |  ✅   |  ✅   |
+| windows - arm64       | ⚠️  |  ⚠️  |  ⚠️  |  ⚠️  |  ⚠️  |
+
+## TLDR
+
+Register at [Extended Testnet](https://starknet.sepolia.extended.exchange/). 
+
+Navigate to [API Management](https://starknet.sepolia.extended.exchange/api-management):
+1. Generate an API key
+2. Show API details (you will need these details to initialize a trading client)
+
+Create an `.env` file (see below) in the examples directory root:
+```properties
+X10_API_KEY=<your_api_key>
+X10_PUBLIC_KEY=<your_public_key>
+X10_PRIVATE_KEY=<your_private_key>
+X10_VAULT_ID=<your_vault_id>
+```
+
+Refer to the [cases](examples/cases) directory for the specific examples of how to use the SDK.
+
+Each example follows the same pattern:
+```python
+from dotenv import load_dotenv
+from x10.core.env_config import EnvConfig
+from x10.core.stark_account import StarkPerpetualAccount
+from x10.config import TESTNET_CONFIG
+from x10.clients.rest import RestApiClient
+
+
+# Load environment variables from `.env` file and parse them into a `EnvConfig` object.
+load_dotenv()
+env_config = EnvConfig.parse()
+env_config.validate_private_api_credentials()
+
+# Instantiate a `StarkPerpetualAccount` object with the parsed environment variables.
+stark_account = StarkPerpetualAccount(
+    api_key=env_config.api_key,
+    public_key=env_config.public_key,
+    private_key=env_config.private_key,
+    vault=env_config.vault_id,
+)
+
+# Instantiate REST API/Streaming/etc client. `stark_account` can be omitted
+# if you don't need to make private API requests.
+rest_client = RestApiClient(TESTNET_CONFIG, stark_account)
+
+# Perform example action using the instantiated client.
+```
+
+## OpenAPI Specifications
+
+Available specifications can be found in the [specs](specs) directory.
+
+## Clients
+
+The SDK currently provides functionality using so-called clients.
+And each client is divided into feature-specific modules.
+
+### Onboarding
+
+| Module  | Description                                       |
+|---------|---------------------------------------------------|
+| auth    | Functionality related to client/account creation. |
+| account | Account API keys creation.                        |
+
+### Blocking Trading
+
+Placing orders and receiving updates in a blocking (synchronous) manner.
+
+### REST API
+
+| Module           | Description                                                                                         |
+|------------------|-----------------------------------------------------------------------------------------------------|
+| account          | Functionality related to managing an active trading account (e.g., leverage/positions/orders/etc).  |
+| builder          | Functionality related to builders-specific data.                                                    |
+| info             | Functionality related to public market data (including historical data).                            |
+| order_management | Functionality related to managing orders (place/cancel).                                            |
+| testnet          | Functionality related to TESTNET specific actions (e.g., claiming TESTNET tokens).                  |
+| vault            | Functionality related to Vault public data and user's Vault token management (deposits/withrawals). | 
+
+### Streaming
+
+Provides functionality for subscribing to real-time WebSocket updates.
+Each topic (stream) requires a separate WebSocket connection.
+
+## Onboarding via SDK
+
+The process of obtaining a Stark key pair from an Ethereum account is a cryptographic procedure
+that involves generating a private and public key pair used in the StarkWare ecosystem.
+This process leverages the Ethereum account to create a deterministic Stark key pair that can be used
+for operations on StarkWare-based systems such as StarkEx and StarkNet.
+
+### Process of Obtaining a Stark Key Pair from an Ethereum Account
+
+1. **Context and Purpose.** StarkWare-based systems require their own cryptographic keys (Stark keys)
+   separate from Ethereum keys. However, to maintain a consistent user experience, StarkWare allows users
+   to derive these keys deterministically from their existing Ethereum accounts. The process of obtaining
+   a Stark key pair from an Ethereum account involves generating a signing message that the Ethereum account
+   can sign and then using that signature to derive the Stark private key.
+2. **Generating the Signing Structure.** The first step in the process is to generate a signing structure
+   that will be signed by the Ethereum account. This structure is constructed using the EIP-712 standard,
+   which allows for typed data to be signed in a structured way on Ethereum.
+    1. **Define the Signing Structure.** The message to be signed includes: (1) account index,
+       (2) the Ethereum wallet address, (3) and whether the terms of service (TOS) are accepted.
+       Check `get_key_derivation_struct_to_sign` function implementation for more details.
+    2. **EIP-712 Typed Data.** The signing structure uses EIP-712 typed data, which consists of:
+        - **Domain.** This is a structured domain object that helps to prevent cross-domain replay attacks.
+          In this case, it typically includes the name field (which might be the name of the application or system).
+        - **Message.** This is the main data being signed, which includes the accountIndex, wallet address, and tosAccepted fields.
+        - **Types.** This describes the types of the fields in both the domain and message.
+        - **Primary Type.** This indicates the primary type being signed (in this case, `AccountCreation`).
+    3. **Encoding the Typed Data.** The structure is encoded into a format that can be signed by
+       the Ethereum account. This is done using the `encode_typed_data` function,
+       which creates a `SignableMessage`. The `SignableMessage` includes the hash of the typed data
+       according to the EIP-712 standard.
+3. **Signing the Structure with the Ethereum Account.** Once the signing structure is prepared,
+   it is signed using the Ethereum private key.
+4. **Deriving the Stark Private Key.** The signature obtained from the Ethereum account is then used to
+   derive the Stark private key. This is done by truncating the r value from the Ethereum signature and
+   using it as the basis for the Stark private key. Check `get_private_key_from_eth_signature` function
+   implementation in [Rust Library](https://github.com/x10xchange/rust-crypto-lib-base) for more details.
+
+## Breaking changes
+
+For a detailed list of breaking changes, please refer to the [MIGRATION.md](MIGRATION.md) file.
+
+## Contributing
+
+See the [CONTRIBUTING.md](CONTRIBUTING.md) file.
+

x10_python_trading_starknet-2.2.0/README.md

@@ -0,0 +1,153 @@
+# Extended Python SDK
+
+Python client for [Extended API](https://api.docs.extended.exchange/).
+
+Minimum Python version required to use this library is `3.10`
+(you can use [pyenv](https://github.com/pyenv/pyenv) to manage your Python versions easily).
+
+## Installation
+
+```shell
+pip install x10-python-trading-starknet
+```
+
+Our SDK makes use of a [Rust Library Python Wrapper](https://github.com/x10xchange/stark-crypto-wrapper-py) to speed up signing and hashing of stark components.
+Currently, this library supports the following environments (please refer to the library repository for the most up to date information):
+
+|                       | 3.9 | 3.10 | 3.11 | 3.12 | 3.13 |
+|-----------------------|:---:|:----:|:----:|:----:|:----:|
+| linux (glibc) - x86   |  ✅  |  ✅   |  ✅   |  ✅   |  ✅   |
+| linux (musl) - x86    |  ✅  |  ✅   |  ✅   |  ✅   |  ✅   |
+| linux (glibc) - arm64 |  ✅  |  ✅   |  ✅   |  ✅   |  ✅   |
+| linux (musl) - arm64  |  ✅  |  ✅   |  ✅   |  ✅   |  ✅   |
+| OSX - arm64           |  ✅  |  ✅   |  ✅   |  ✅   |  ✅   |
+| windows - x86         |  ✅  |  ✅   |  ✅   |  ✅   |  ✅   |
+| windows - arm64       | ⚠️  |  ⚠️  |  ⚠️  |  ⚠️  |  ⚠️  |
+
+## TLDR
+
+Register at [Extended Testnet](https://starknet.sepolia.extended.exchange/). 
+
+Navigate to [API Management](https://starknet.sepolia.extended.exchange/api-management):
+1. Generate an API key
+2. Show API details (you will need these details to initialize a trading client)
+
+Create an `.env` file (see below) in the examples directory root:
+```properties
+X10_API_KEY=<your_api_key>
+X10_PUBLIC_KEY=<your_public_key>
+X10_PRIVATE_KEY=<your_private_key>
+X10_VAULT_ID=<your_vault_id>
+```
+
+Refer to the [cases](examples/cases) directory for the specific examples of how to use the SDK.
+
+Each example follows the same pattern:
+```python
+from dotenv import load_dotenv
+from x10.core.env_config import EnvConfig
+from x10.core.stark_account import StarkPerpetualAccount
+from x10.config import TESTNET_CONFIG
+from x10.clients.rest import RestApiClient
+
+
+# Load environment variables from `.env` file and parse them into a `EnvConfig` object.
+load_dotenv()
+env_config = EnvConfig.parse()
+env_config.validate_private_api_credentials()
+
+# Instantiate a `StarkPerpetualAccount` object with the parsed environment variables.
+stark_account = StarkPerpetualAccount(
+    api_key=env_config.api_key,
+    public_key=env_config.public_key,
+    private_key=env_config.private_key,
+    vault=env_config.vault_id,
+)
+
+# Instantiate REST API/Streaming/etc client. `stark_account` can be omitted
+# if you don't need to make private API requests.
+rest_client = RestApiClient(TESTNET_CONFIG, stark_account)
+
+# Perform example action using the instantiated client.
+```
+
+## OpenAPI Specifications
+
+Available specifications can be found in the [specs](specs) directory.
+
+## Clients
+
+The SDK currently provides functionality using so-called clients.
+And each client is divided into feature-specific modules.
+
+### Onboarding
+
+| Module  | Description                                       |
+|---------|---------------------------------------------------|
+| auth    | Functionality related to client/account creation. |
+| account | Account API keys creation.                        |
+
+### Blocking Trading
+
+Placing orders and receiving updates in a blocking (synchronous) manner.
+
+### REST API
+
+| Module           | Description                                                                                         |
+|------------------|-----------------------------------------------------------------------------------------------------|
+| account          | Functionality related to managing an active trading account (e.g., leverage/positions/orders/etc).  |
+| builder          | Functionality related to builders-specific data.                                                    |
+| info             | Functionality related to public market data (including historical data).                            |
+| order_management | Functionality related to managing orders (place/cancel).                                            |
+| testnet          | Functionality related to TESTNET specific actions (e.g., claiming TESTNET tokens).                  |
+| vault            | Functionality related to Vault public data and user's Vault token management (deposits/withrawals). | 
+
+### Streaming
+
+Provides functionality for subscribing to real-time WebSocket updates.
+Each topic (stream) requires a separate WebSocket connection.
+
+## Onboarding via SDK
+
+The process of obtaining a Stark key pair from an Ethereum account is a cryptographic procedure
+that involves generating a private and public key pair used in the StarkWare ecosystem.
+This process leverages the Ethereum account to create a deterministic Stark key pair that can be used
+for operations on StarkWare-based systems such as StarkEx and StarkNet.
+
+### Process of Obtaining a Stark Key Pair from an Ethereum Account
+
+1. **Context and Purpose.** StarkWare-based systems require their own cryptographic keys (Stark keys)
+   separate from Ethereum keys. However, to maintain a consistent user experience, StarkWare allows users
+   to derive these keys deterministically from their existing Ethereum accounts. The process of obtaining
+   a Stark key pair from an Ethereum account involves generating a signing message that the Ethereum account
+   can sign and then using that signature to derive the Stark private key.
+2. **Generating the Signing Structure.** The first step in the process is to generate a signing structure
+   that will be signed by the Ethereum account. This structure is constructed using the EIP-712 standard,
+   which allows for typed data to be signed in a structured way on Ethereum.
+    1. **Define the Signing Structure.** The message to be signed includes: (1) account index,
+       (2) the Ethereum wallet address, (3) and whether the terms of service (TOS) are accepted.
+       Check `get_key_derivation_struct_to_sign` function implementation for more details.
+    2. **EIP-712 Typed Data.** The signing structure uses EIP-712 typed data, which consists of:
+        - **Domain.** This is a structured domain object that helps to prevent cross-domain replay attacks.
+          In this case, it typically includes the name field (which might be the name of the application or system).
+        - **Message.** This is the main data being signed, which includes the accountIndex, wallet address, and tosAccepted fields.
+        - **Types.** This describes the types of the fields in both the domain and message.
+        - **Primary Type.** This indicates the primary type being signed (in this case, `AccountCreation`).
+    3. **Encoding the Typed Data.** The structure is encoded into a format that can be signed by
+       the Ethereum account. This is done using the `encode_typed_data` function,
+       which creates a `SignableMessage`. The `SignableMessage` includes the hash of the typed data
+       according to the EIP-712 standard.
+3. **Signing the Structure with the Ethereum Account.** Once the signing structure is prepared,
+   it is signed using the Ethereum private key.
+4. **Deriving the Stark Private Key.** The signature obtained from the Ethereum account is then used to
+   derive the Stark private key. This is done by truncating the r value from the Ethereum signature and
+   using it as the basis for the Stark private key. Check `get_private_key_from_eth_signature` function
+   implementation in [Rust Library](https://github.com/x10xchange/rust-crypto-lib-base) for more details.
+
+## Breaking changes
+
+For a detailed list of breaking changes, please refer to the [MIGRATION.md](MIGRATION.md) file.
+
+## Contributing
+
+See the [CONTRIBUTING.md](CONTRIBUTING.md) file.

{x10_python_trading_starknet-2.0.0 → x10_python_trading_starknet-2.2.0}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "poetry.core.masonry.api"
 
 [tool.poetry]
 name = "x10-python-trading-starknet"
-version = "2.0.0"
+version = "2.2.0"
 description = "Python client for X10 API"
 authors = ["X10 <tech@ex10.org>"]
 repository = "https://github.com/x10xchange/python_sdk"
@@ -17,14 +17,21 @@ classifiers = [
     "Programming Language :: Python",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
     "Topic :: Software Development :: Libraries :: Python Modules",
 ]
 packages = [{ include = "x10" }]
 
+[tool.poetry.extras]
+mcp = ["mcp"]
+
 [tool.poetry.dependencies]
 aiohttp = ">=3.10.11"
 eth-account = ">=0.12.0"
 fast-stark-crypto = "==0.5.0"
+mcp = { version = ">=1.28.0", optional = true }
 pydantic = ">=2.9.0"
 python = "^3.10"
 pyyaml = ">=6.0.1"
@@ -49,7 +56,7 @@ pytest-cov = "==4.1.0"
 pytest-forked = "==1.6.0"
 pytest-mock = "==3.12.0"
 python-dotenv = "==1.0.1"
-safety = "==3.5.1"
+safety = "==3.8.1"
 tox = "==4.11.4"
 types-pyyaml = "==6.0.12.12"
 typing-extensions = "==4.15.0"

{x10_python_trading_starknet-2.0.0 → x10_python_trading_starknet-2.2.0}/x10/clients/blocking/blocking_trading_client.py

@@ -7,7 +7,7 @@ from typing import Awaitable, Dict, Optional, cast
 from x10.clients.rest.modules.info_module import InfoModule
 from x10.clients.rest.modules.order_management_module import OrderManagementModule
 from x10.clients.stream import StreamClient, StreamConnection
-from x10.config import Config
+from x10.core.client_config import ClientConfig
 from x10.core.stark_account import StarkPerpetualAccount
 from x10.errors import SdkError, ValidationError
 from x10.models.account import AccountStreamDataModel
@@ -77,7 +77,7 @@ class BlockingTradingClient:
     Waits for the confirmation from the WS stream after placing or canceling an order.
     """
 
-    def __init__(self, config: Config, account: StarkPerpetualAccount):
+    def __init__(self, config: ClientConfig, account: StarkPerpetualAccount):
         if not asyncio.get_event_loop().is_running():
             raise SdkError(
                 "BlockingTradingClient must be initialized from an async function, use BlockingTradingClient.create()"
@@ -95,7 +95,7 @@ class BlockingTradingClient:
         self.__stream_task = asyncio.create_task(self.__order_stream())
 
     @staticmethod
-    async def create(config: Config, account: StarkPerpetualAccount) -> "BlockingTradingClient":
+    async def create(config: ClientConfig, account: StarkPerpetualAccount) -> "BlockingTradingClient":
         client = BlockingTradingClient(config, account)
         await client.__stream_client.subscribe_to_account_updates(account.api_key)
         return client

{x10_python_trading_starknet-2.0.0 → x10_python_trading_starknet-2.2.0}/x10/clients/onboarding/modules/account_module.py

@@ -7,6 +7,11 @@ from x10.utils.http import RequestHeader, send_post_request
 
 class AccountModule(BaseModule):
     async def create_api_key(self, *, account_id: int, description: str) -> str:
+        """
+        Generates an API key for a specified account. You can provide an optional description
+        for the API key. It returns the newly created API key as a string.
+        """
+
         request_path = "/api/v1/user/account/api-key"
         signature = sign_api_request(request_path, self._sign_message)
         headers: dict[str, str] = {

{x10_python_trading_starknet-2.0.0 → x10_python_trading_starknet-2.2.0}/x10/clients/onboarding/modules/auth_module.py

@@ -20,6 +20,13 @@ class SubAccountExists(SdkError):
 
 class AuthModule(BaseModule):
     async def onboard_client(self, *, referral_code: str | None = None) -> OnBoardedAccount:
+        """
+        Handles the onboarding process of a user. It generates an L2 key pair from
+        the user's L1 Ethereum account, creates an onboarding payload, and sends it
+        to the onboarding endpoint. Upon successful onboarding, it returns an `OnBoardedAccount`
+        object containing the default account and the L2 key pair.
+        """
+
         l2_key_pair = get_l2_keys_from_l1_account(
             account_index=0,
             account_address=self._get_account_address(),
@@ -48,6 +55,14 @@ class AuthModule(BaseModule):
         return OnBoardedAccount(account=onboarded_client.default_account, l2_key_pair=l2_key_pair)
 
     async def onboard_subaccount(self, *, account_index: int, description: str):
+        """
+        This method onboards a subaccount associated with the user's main account.
+        It allows you to specify an `account_index` and an optional description.
+        If a subaccount with the given index already exists, it raises a `ValidationError` exception.
+        Otherwise, it creates a new subaccount and returns an `OnBoardedAccount` object with
+        the subaccount details and the associated L2 key pair.
+        """
+
         request_path = "/auth/onboard/subaccount"
         signature = sign_api_request(request_path, self._sign_message)
         headers: dict[str, str] = {

{x10_python_trading_starknet-2.0.0 → x10_python_trading_starknet-2.2.0}/x10/clients/onboarding/modules/base_module.py

@@ -5,18 +5,18 @@ from aiohttp import ClientTimeout
 from eth_account.messages import SignableMessage
 from eth_typing import ChecksumAddress
 
-from x10.config import Config
+from x10.core.client_config import ClientConfig
 from x10.signing.onboarding import SignMessageCallback
 from x10.utils.http import get_url
 
 
 class BaseModule:
-    __config: Config
+    __config: ClientConfig
     __account_address: ChecksumAddress
     __sign_message: SignMessageCallback
     __session: Optional[aiohttp.ClientSession]
 
-    def __init__(self, config: Config, *, account_address: ChecksumAddress, sign_message: SignMessageCallback):
+    def __init__(self, config: ClientConfig, *, account_address: ChecksumAddress, sign_message: SignMessageCallback):
         super().__init__()
 
         self.__config = config
@@ -27,7 +27,7 @@ class BaseModule:
     def _get_url(self, path: str, *, query: Optional[Dict] = None, **path_params) -> str:
         return get_url(f"{self.__config.endpoints.onboarding_url}{path}", query=query, **path_params)
 
-    def _get_config(self) -> Config:
+    def _get_config(self) -> ClientConfig:
         return self.__config
 
     def _get_account_address(self) -> ChecksumAddress:

{x10_python_trading_starknet-2.0.0 → x10_python_trading_starknet-2.2.0}/x10/clients/onboarding/onboarding_client.py

@@ -2,7 +2,7 @@ from eth_typing import ChecksumAddress
 
 from x10.clients.onboarding.modules.account_module import AccountModule
 from x10.clients.onboarding.modules.auth_module import AuthModule
-from x10.config import Config
+from x10.core.client_config import ClientConfig
 from x10.signing.onboarding import SignMessageCallback
 
 
@@ -20,7 +20,7 @@ class OnboardingClient:
     async def __aexit__(self, exc_type, exc_value, traceback):
         await self.close()
 
-    def __init__(self, config: Config, *, account_address: ChecksumAddress, sign_message: SignMessageCallback):
+    def __init__(self, config: ClientConfig, *, account_address: ChecksumAddress, sign_message: SignMessageCallback):
         self.__account_module = AccountModule(config, account_address=account_address, sign_message=sign_message)
         self.__auth_module = AuthModule(config, account_address=account_address, sign_message=sign_message)