ethereal-sdk 0.1.0a1__tar.gz

ethereal_sdk-0.1.0a1/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.2
+Name: ethereal-sdk
+Version: 0.1.0a1
+Summary: Python SDK for interacting with the Ethereal API
+Author: Meridian Labs
+License: MIT
+Project-URL: Homepage, https://github.com/meridianxyz/ethereal-py
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+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: License :: OSI Approved :: MIT License
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: eth-account>=0.13.5
+Requires-Dist: pydantic>=2.10.6
+Requires-Dist: python-dotenv>=1.0.1
+Requires-Dist: python-socketio>=5.12.1
+Requires-Dist: requests>=2.32.3
+Requires-Dist: web3>=7.8.0
+
+# ethereal-py-sdk
+
+**Welcome to ethereal-py-sdk!**
+
+Python SDK for interacting with the Ethereal API.
+
+## Getting started
+
+Before you start, make sure you have installed [uv](https://docs.astral.sh/uv/getting-started/installation/):
+
+```
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+Then you can install the SDK and run the tests:
+
+```bash
+# Clone the project
+git clone git@github.com:meridianxyz/ethereal-py-sdk.git
+
+# Install dependencies
+uv sync
+
+# Run tests
+uv run pytest
+
+# Run the linter
+uv run ruff check --fix
+
+# Run the example CLI
+uv run python -i examples/cli.py
+```
+
+## Usage
+
+Using the SDK using the REPL (example):
+
+```python
+import ethereal
+
+rc = ethereal.RESTClient()
+rc.list_products()
+```
+
+Or use the provided CLI:
+
+```bash
+cp .env.test .env
+
+uv run python -i examples/cli.py
+
+>>> rc.list_products()
+```
+
+## Generating Pydantic Type
+
+Ethereal uses an OpenAPI spec to represent the API. You can generate Pydantic models from the OpenAPI spec using the `datamodel-codegen` tool:
+
+```bash
+# place a `spec.json` in the root of the project
+uv run datamodel-codegen --input /path/to/api_spec.json \
+  --output ethereal/models/generated.py \
+  --input-file-type openapi \
+  --openapi-scopes paths schemas parameters \
+  --output-model-type pydantic_v2.BaseModel
+```
+
+## Documentation
+
+Docs are created using [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/). To run the docs locally:
+
+```bash
+# serve
+uv run mkdocs serve
+
+# build
+uv run mkdocs build
+```

ethereal_sdk-0.1.0a1/README.md

@@ -0,0 +1,78 @@
+# ethereal-py-sdk
+
+**Welcome to ethereal-py-sdk!**
+
+Python SDK for interacting with the Ethereal API.
+
+## Getting started
+
+Before you start, make sure you have installed [uv](https://docs.astral.sh/uv/getting-started/installation/):
+
+```
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+Then you can install the SDK and run the tests:
+
+```bash
+# Clone the project
+git clone git@github.com:meridianxyz/ethereal-py-sdk.git
+
+# Install dependencies
+uv sync
+
+# Run tests
+uv run pytest
+
+# Run the linter
+uv run ruff check --fix
+
+# Run the example CLI
+uv run python -i examples/cli.py
+```
+
+## Usage
+
+Using the SDK using the REPL (example):
+
+```python
+import ethereal
+
+rc = ethereal.RESTClient()
+rc.list_products()
+```
+
+Or use the provided CLI:
+
+```bash
+cp .env.test .env
+
+uv run python -i examples/cli.py
+
+>>> rc.list_products()
+```
+
+## Generating Pydantic Type
+
+Ethereal uses an OpenAPI spec to represent the API. You can generate Pydantic models from the OpenAPI spec using the `datamodel-codegen` tool:
+
+```bash
+# place a `spec.json` in the root of the project
+uv run datamodel-codegen --input /path/to/api_spec.json \
+  --output ethereal/models/generated.py \
+  --input-file-type openapi \
+  --openapi-scopes paths schemas parameters \
+  --output-model-type pydantic_v2.BaseModel
+```
+
+## Documentation
+
+Docs are created using [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/). To run the docs locally:
+
+```bash
+# serve
+uv run mkdocs serve
+
+# build
+uv run mkdocs build
+```

ethereal_sdk-0.1.0a1/ethereal/__init__.py

@@ -0,0 +1,4 @@
+from ethereal.rest_client import RESTClient
+from ethereal.ws_client import WSClient
+
+__all__ = ["RESTClient", "WSClient"]

ethereal_sdk-0.1.0a1/ethereal/__version__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0a1"

ethereal_sdk-0.1.0a1/ethereal/base_client.py

@@ -0,0 +1,44 @@
+import logging
+from typing import Union, Dict, Any
+from ethereal.models.config import BaseConfig
+
+
+def get_logger(name):
+    """Get a configured logger instance.
+
+    Args:
+        name (str): Name for the logger
+
+    Returns:
+        Logger: Configured logging instance
+    """
+    logger = logging.getLogger(name)
+    logger.setLevel(logging.INFO)
+
+    handler = logging.StreamHandler()
+    formatter = logging.Formatter(
+        "%(asctime)s - %(name)s - %(levelname)s - %(message)s", "%Y-%m-%d %H:%M:%S"
+    )
+    handler.setFormatter(formatter)
+    logger.addHandler(handler)
+
+    return logger
+
+
+class BaseClient:
+    """Base client with common functionality.
+
+    Args:
+        config (Union[Dict[str, Any], BaseConfig]): Base configuration
+    """
+
+    def __init__(self, config: Union[Dict[str, Any], BaseConfig]):
+        self.config = BaseConfig.model_validate(config)
+        self._setup_logging()
+
+    def _setup_logging(self):
+        """Set up logging for the client."""
+        self.logger = get_logger(self.__class__.__name__)
+        if self.config.verbose:
+            self.logger.setLevel(logging.DEBUG)
+        pass

ethereal_sdk-0.1.0a1/ethereal/chain_client.py

@@ -0,0 +1,278 @@
+import os
+import json
+
+from typing import Optional, Dict, Any, Union
+from ethereal.base_client import BaseClient
+from ethereal.models.config import ChainConfig
+from ethereal.models.rest import RpcConfigDto
+from web3 import Web3
+from web3.exceptions import Web3Exception
+from web3.types import TxParams
+from eth_account import Account
+from eth_account.messages import encode_typed_data
+from eth_utils import encode_hex
+
+
+# constants
+USDE_ADDRESSES = {996353: "0xa1623E0AA40B142Cf755938b325321fB2c61Cf05"}
+
+
+def read_contract(contract_name: str):
+    contract_dir = os.path.join(
+        os.path.dirname(os.path.abspath(__file__)),
+        "contracts",
+        f"{contract_name}.json",
+    )
+    with open(contract_dir) as f:
+        return json.load(f)
+
+
+class ChainClient(BaseClient):
+    """Client for interacting with the blockchain using Web3 functionality.
+
+    Args:
+        config (Union[Dict[str, Any], ChainConfig]): Chain configuration
+        rpc_config (RpcConfigDto, optional): RPC configuration. Defaults to None.
+
+    Raises:
+        Exception: If RPC URL or private key is not specified in the configuration
+    """
+
+    def __init__(
+        self,
+        config: Union[Dict[str, Any], ChainConfig],
+        rpc_config: RpcConfigDto = None,
+    ):
+        super().__init__(config)
+        self.config = ChainConfig.model_validate(config)
+        self.provider = self._setup_provider()
+        self.account = self._setup_account()
+        self.address = self.account.address
+        self.private_key = self.config.private_key
+
+        self.chain_id = self.provider.eth.chain_id
+        self.usde = self.provider.eth.contract(
+            address=USDE_ADDRESSES[self.chain_id], abi=read_contract("ERC20")
+        )
+        self.rpc_config = rpc_config
+
+    def _setup_provider(self):
+        """Set up the Web3 provider.
+
+        Returns:
+            Web3: The Web3 provider instance
+
+        Raises:
+            Exception: If RPC URL is not specified in the configuration
+        """
+        # TODO: Support other provider types (e.g. WebSocket)
+        if self.config.rpc_url is None:
+            raise Exception("RPC URL must be specified in the configuration")
+        return Web3(Web3.HTTPProvider(self.config.rpc_url))
+
+    def _setup_account(self):
+        """Set up the account.
+
+        Returns:
+            Account: The Web3 account instance
+
+        Raises:
+            Exception: If private key is not specified in the configuration
+        """
+        if self.config.private_key is None:
+            raise Exception("Private key must be specified in the configuration")
+        return self.provider.eth.account.from_key(self.config.private_key)
+
+    def _get_tx(self, value=0, to=None) -> TxParams:
+        """Get default transaction parameters.
+
+        Args:
+            value (int, optional): The value to send. Defaults to 0.
+            to (str, optional): The recipient address. Defaults to None.
+
+        Returns:
+            TxParams: The transaction parameters
+        """
+        params: TxParams = {
+            "from": self.address,
+            "chainId": self.chain_id,
+            "value": value,
+            "nonce": self.get_nonce(self.address),
+        }
+        if to is not None:
+            params["to"] = to
+        return params
+
+    def add_gas_fees(self, tx: TxParams) -> TxParams:
+        """Add gas fee parameters to a transaction.
+
+        Args:
+            tx (TxParams): The transaction parameters
+
+        Returns:
+            TxParams: The transaction parameters with gas fee parameters added
+        """
+        if "maxFeePerGas" in tx and "maxPriorityFeePerGas" in tx:
+            return tx
+        try:
+            gas_price = self.provider.eth.gas_price
+            max_priority_fee = self.provider.eth.max_priority_fee
+            tx["maxFeePerGas"] = gas_price
+            tx["maxPriorityFeePerGas"] = max_priority_fee
+            return tx
+        except Web3Exception as e:
+            self.logger.error(f"Failed to add gas: {e}")
+            return tx
+
+    def add_gas_limit(self, tx: TxParams) -> TxParams:
+        """Add gas limit to a transaction.
+
+        Args:
+            tx (TxParams): The transaction parameters
+
+        Returns:
+            TxParams: The transaction parameters with gas limit added
+        """
+        if "gas" in tx:
+            return tx
+        try:
+            gas = self.provider.eth.estimate_gas(tx)
+            tx["gas"] = gas
+            return tx
+        except Web3Exception as e:
+            self.logger.error(f"Failed to add gas limit: {e}")
+            return
+
+    def submit_tx(self, tx: TxParams) -> str:
+        """Submit a transaction.
+
+        Args:
+            tx (TxParams): The transaction parameters
+
+        Returns:
+            str: The transaction hash
+        """
+        tx = self.add_gas_fees(tx)
+        tx = self.add_gas_limit(tx)
+        try:
+            signed_tx = self.provider.eth.account.sign_transaction(
+                tx, private_key=self.private_key
+            )
+            tx_hash = self.provider.eth.send_raw_transaction(signed_tx.raw_transaction)
+            return encode_hex(tx_hash)
+        except Web3Exception as e:
+            self.logger.error(f"Failed to submit transaction: {e}")
+            return
+
+    def get_nonce(self, address: str) -> int:
+        """Get the nonce for a given address.
+
+        Args:
+            address (str): The address to get the nonce for
+
+        Returns:
+            int: The nonce, or -1 if failed
+        """
+        try:
+            return self.provider.eth.get_transaction_count(address)
+        except Web3Exception as e:
+            self.logger.error(f"Failed to get nonce: {e}")
+            return -1
+
+    def get_balance(self, address: str) -> int:
+        """Get the balance for a given address.
+
+        Args:
+            address (str): The address to get the balance for
+
+        Returns:
+            int: The balance, or -1 if failed
+        """
+        try:
+            return self.provider.eth.get_balance(address)
+        except Web3Exception as e:
+            self.logger.error(f"Failed to get balance: {e}")
+            return -1
+
+    def get_token_balance(self, address: str, token_address: str) -> int:
+        """Get the token balance for a given address.
+
+        Args:
+            address (str): The address to get the token balance for
+            token_address (str): The token address
+
+        Returns:
+            int: The token balance, or -1 if failed
+        """
+        try:
+            contract = self.provider.eth.contract(
+                address=token_address, abi=read_contract("ERC20")
+            )
+            return contract.functions.balanceOf(address).call()
+        except Web3Exception as e:
+            self.logger.error(f"Failed to get token balance: {e}")
+            return -1
+
+    def sign_message(self, private_key, domain, types, primary_type, message):
+        # A type fix for the domain
+        domain["chainId"] = int(domain["chainId"])
+
+        # Preparing the full message as per EIP-712
+        full_message = {
+            "types": types,
+            "primaryType": primary_type,
+            "domain": domain,
+            "message": message,
+        }
+
+        encoded_message = encode_typed_data(full_message=full_message)
+
+        # Signing the message
+        signed_message = Account.sign_message(encoded_message, private_key)
+        return "0x" + signed_message.signature.hex()
+
+    def deposit_usde(
+        self,
+        amount: float,
+        address: Optional[str] = None,
+        submit: Optional[bool] = False,
+        account_name: Optional[str] = "primary",
+    ) -> Union[TxParams, str]:
+        """Submit a deposit transaction.
+
+        Args:
+            amount (float): The amount to deposit
+            address (str, optional): The address to deposit to. Defaults to None.
+            submit (bool, optional): Whether to submit the transaction. Defaults to False.
+
+        Returns:
+            Union[TxParams, str]: The transaction parameters or transaction hash if submit=True
+        """
+        if address is None:
+            address = self.address
+        try:
+            contract_address = self.rpc_config.domain.verifyingContract
+            contract = self.provider.eth.contract(
+                address=contract_address, abi=read_contract("EtherealProxy")
+            )
+
+            # params
+            subaccount = self.provider.to_hex(text=account_name).ljust(66, "0")
+            deposit_token = self.usde.address
+            amount = self.provider.to_wei(amount, "ether")
+            referral_code = self.provider.to_hex(0).ljust(66, "0")
+
+            # prepare the tx
+            tx = self._get_tx(to=contract_address)
+            tx["data"] = contract.encode_abi(
+                "deposit", args=[subaccount, deposit_token, amount, referral_code]
+            )
+
+            if submit:
+                return self.submit_tx(tx)
+            else:
+                return tx
+
+        except Web3Exception as e:
+            self.logger.error(f"Failed to get token balance: {e}")
+            return -1

ethereal_sdk-0.1.0a1/ethereal/constants.py

@@ -0,0 +1,24 @@
+from ethereal.__version__ import __version__
+
+USER_AGENT = f"ethereal-py-sdk/{__version__}"
+PRIVATE_KEY = "PRIVATE_KEY"
+RPC_URL = "RPC_URL"
+
+BASE_URL = "https://api.etherealtest.net"
+API_PREFIX = "/v1"
+
+WS_BASE_URL = "wss://ws.etherealtest.net"
+WS_NAMESPACES = [
+    "/",
+    "/v1/stream",
+]
+
+X_RATELIMIT_LIMIT = "x-ratelimit-limit"
+X_RATELIMIT_REMAINING = "x-ratelimit-remaining"
+RETRY_AFTER = "retry-after"
+RATE_LIMIT_HEADERS = {X_RATELIMIT_LIMIT, X_RATELIMIT_REMAINING, RETRY_AFTER}
+REST_COMMON_FIELDS = {
+    X_RATELIMIT_LIMIT: "rate_limit_limit",
+    X_RATELIMIT_REMAINING: "rate_limit_remaining",
+    RETRY_AFTER: "retry_after",
+}

ethereal_sdk-0.1.0a1/ethereal/rest_client.py

@@ -0,0 +1,285 @@
+from pydantic import BaseModel
+from typing import Union, Dict, Any, Optional
+from functools import cached_property
+from ethereal.constants import API_PREFIX
+from ethereal.rest.http_client import HTTPClient
+from ethereal.chain_client import ChainClient
+from ethereal.models.config import RESTConfig, ChainConfig
+from ethereal.models.rest import (
+    TimeInForce,
+    RpcConfigDto,
+)
+
+
+class RESTClient(HTTPClient):
+    """REST client for interacting with the Ethereal API.
+
+    Args:
+        config (Union[Dict[str, Any], RESTConfig]): Configuration dictionary or RESTConfig object.
+            Optional fields include:
+            - private_key (str): The private key
+            - base_url (str): Base URL for REST requests, defaults to "https://api.etherealtest.net"
+            - timeout (int): Timeout in seconds for REST requests
+            - verbose (bool): Enables debug logging, defaults to False
+            - rate_limit_headers (bool): Enables rate limit headers, defaults to False
+    """
+
+    from ethereal.rest.funding import list_funding_rates
+    from ethereal.rest.linked_signer import (
+        get_active_signer,
+        get_signer,
+        get_signer_quota,
+        list_signers,
+        link_signer,
+    )
+    from ethereal.rest.order import (
+        get_order,
+        list_fills,
+        list_orders,
+        list_trades,
+        submit_order as _submit_order,
+        cancel_order,
+    )
+    from ethereal.rest.position import list_positions, get_position
+    from ethereal.rest.product import (
+        get_market_liquidity,
+        list_market_prices,
+        list_products,
+    )
+    from ethereal.rest.rpc import get_rpc_config
+    from ethereal.rest.subaccount import (
+        list_subaccounts,
+        get_subaccount,
+        get_subaccount_balances,
+    )
+    from ethereal.rest.token import (
+        get_token,
+        list_token_withdraws,
+        list_tokens,
+        list_token_transfers,
+        withdraw_token,
+    )
+
+    def __init__(self, config: Union[Dict[str, Any], RESTConfig] = {}):
+        super().__init__(config)
+        self.config = RESTConfig.model_validate(config)
+
+        # fetch RPC configuration
+        self.rpc_config = self.get_rpc_config()
+
+        self.chain = None
+        if self.config.chain_config:
+            self._init_chain_client(self.config.chain_config, self.rpc_config)
+            self.private_key = self.chain.private_key
+            self.provider = self.chain.provider
+        else:
+            self.private_key = None
+            self.provider = None
+
+        # TODO: Find a better way to set these default
+        self.default_time_in_force = TimeInForce.IOC
+        self.default_post_only = False
+
+    def _init_chain_client(
+        self,
+        config: Union[Dict[str, Any], ChainConfig],
+        rpc_config: RpcConfigDto = None,
+    ):
+        """Initialize the ChainClient.
+
+        Args:
+            config (Union[Dict[str, Any], ChainConfig]): The chain configuration.
+            rpc_config (RpcConfigDto, optional): RPC configuration. Defaults to None.
+        """
+        config = ChainConfig.model_validate(config)
+        try:
+            self.chain = ChainClient(config, rpc_config)
+            self.logger.info("Chain client initialized successfully")
+        except Exception as e:
+            self.logger.warning(f"Failed to initialize chain client: {e}")
+
+    def _get_pages(
+        self,
+        endpoint: str,
+        request_model: BaseModel,
+        response_model: BaseModel,
+        paginate: bool = False,
+        **kwargs,
+    ) -> BaseModel:
+        """Make a GET request with validated parameters and response and handling for pagination.
+
+        Args:
+            endpoint (str): API endpoint path (e.g. "order" will be appended to the base URL and prefix to form "/v1/order")
+            request_model (BaseModel): Pydantic model for request validation
+            response_model (BaseModel): Pydantic model for response validation
+            paginate (bool): Whether to fetch additional pages of data
+            **kwargs: Parameters to validate and include in the request
+
+        Returns:
+            response (BaseModel): Validated response object
+
+        Example:
+            orders = client.validated_get(
+                endpoint="order",
+                request_model=V1OrderGetParametersQuery,
+                response_model=ListOfOrderDtos,
+                subaccountId="abc123",
+                limit=50
+            )
+        """
+        result = self.get_validated(
+            url_path=f"{API_PREFIX}/{endpoint}",
+            request_model=request_model,
+            response_model=response_model,
+            **kwargs,
+        )
+
+        # If pagination is requested, fetch additional pages
+        is_paginated = all(
+            [
+                hasattr(result, "data"),
+                hasattr(result, "hasNext"),
+                hasattr(result, "nextCursor"),
+            ]
+        )
+        if not is_paginated:
+            raise ValueError("Response does not support pagination")
+        elif paginate:
+            all_data = list(result.data)
+
+            # Continue fetching while there are more pages
+            current_result = result
+            while current_result.hasNext and current_result.nextCursor:
+                current_result = self.get_validated(
+                    url_path=f"{API_PREFIX}/{endpoint}",
+                    request_model=request_model,
+                    response_model=response_model,
+                    cursor=current_result.nextCursor,
+                    **kwargs,
+                )
+                # Add data from this page
+                all_data.extend(current_result.data)
+
+            # Update the result with the combined data
+            result.data = all_data
+            result.hasNext = False
+            result.nextCursor = None
+        return result.data
+
+    @cached_property
+    def subaccounts(self):
+        """Get the list of subaccounts.
+
+        Returns:
+            subaccounts (List): List of subaccount objects.
+        """
+        return self.list_subaccounts(self.chain.address)
+
+    @cached_property
+    def products(self):
+        """Get the list of products.
+
+        Returns:
+            products (List): List of product objects.
+        """
+        return self.list_products()
+
+    @cached_property
+    def products_by_ticker(self):
+        """Get the products indexed by ticker.
+
+        Returns:
+            products_by_ticker (Dict[str, ProductDto]): Dictionary of products keyed by ticker.
+        """
+        return {p.ticker: p for p in self.products}
+
+    @cached_property
+    def products_by_id(self):
+        """Get the products indexed by ID.
+
+        Returns:
+            products_by_id (Dict[str, ProductDto]): Dictionary of products keyed by ID.
+        """
+        return {p.id: p for p in self.products}
+
+    def create_order(
+        self,
+        order_type: str,
+        quantity: float,
+        side: int,
+        price: Optional[float] = None,
+        ticker: Optional[str] = None,
+        product_id: Optional[str] = None,
+        sender: Optional[str] = None,
+        subaccount: Optional[str] = None,
+        time_in_force: Optional[str] = None,
+        post_only: Optional[bool] = None,
+    ):
+        """Create and submit an order.
+
+        Args:
+            order_type (str): The type of order (market or limit)
+            quantity (float): The quantity of the order
+            side (int): The side of the order (0 = BUY, 1 = SELL)
+            price (float, optional): The price of the order (for limit orders)
+            ticker (str, optional): The ticker of the product
+            product_id (str, optional): The ID of the product
+            sender (str, optional): The sender address
+            subaccount (str, optional): The subaccount name
+            time_in_force (str, optional): The time in force for limit orders
+            post_only (bool, optional): Whether the order is post-only (for limit orders)
+
+        Returns:
+            order (OrderDto): The response data from the API
+
+        Raises:
+            ValueError: If neither product_id nor ticker is provided or if order type is invalid
+        """
+        # get the sender and account info
+        if sender is None:
+            sender = self.chain.address
+        if subaccount is None:
+            subaccount = self.subaccounts[0].name
+
+        # get the product info
+        if product_id is not None:
+            onchain_id = self.products_by_id[product_id].onchainId
+        elif ticker is not None:
+            onchain_id = self.products_by_ticker[ticker].onchainId
+        else:
+            raise ValueError("Either product_id or ticker must be provided")
+
+        # prepare the order params
+        quantity = str(quantity)
+        if order_type == "MARKET":
+            order_params = {
+                "sender": sender,
+                "subaccount": subaccount,
+                "side": side,
+                "price": "0",
+                "quantity": quantity,
+                "onchainId": onchain_id,
+                "orderType": order_type,
+            }
+        elif order_type == "LIMIT":
+            time_in_force = (
+                self.default_time_in_force if time_in_force is None else time_in_force
+            )
+            post_only = self.default_post_only if post_only is None else post_only
+            price = "{:.9f}".format(price)
+
+            order_params = {
+                "sender": sender,
+                "subaccount": subaccount,
+                "side": side,
+                "price": price,
+                "quantity": quantity,
+                "onchainId": onchain_id,
+                "orderType": order_type,
+                "timeInForce": time_in_force,
+                "postOnly": post_only,
+            }
+        else:
+            raise ValueError("Invalid order type")
+
+        return self._submit_order(**order_params)

ethereal_sdk-0.1.0a1/ethereal/ws_client.py

@@ -0,0 +1,79 @@
+from typing import Union, Dict, Any, Callable, Optional
+
+from ethereal.models.config import WSConfig
+from ethereal.ws.ws_base import WSBase
+
+
+class WSClient(WSBase):
+    """Ethereal websocket client.
+
+    Args:
+        config (Union[Dict[str, Any], WSConfig]): Configuration dictionary or WSConfig object.
+            Required fields include:
+            - base_url (str): Base URL for websocket requests
+            Optional fields include:
+            - verbose (bool): Enables debug logging, defaults to False
+    """
+
+    def __init__(self, config: Union[Dict[str, Any], WSConfig]):
+        super().__init__(config)
+
+    def subscribe(
+        self,
+        stream_type: str,
+        product_id: str,
+        subaccount_id: Optional[str] = None,
+        callback: Optional[Callable[[Dict[str, Any]], None]] = None,
+        namespace: Optional[str] = "/v1/stream",
+    ) -> Dict[str, Any]:
+        """Subscribe to a specific stream.
+
+        Args:
+            stream_type (str): Type of stream to subscribe to
+            product_id (str): Product ID to subscribe to
+            subaccount_id (Optional[str]): Subaccount ID, optional
+            callback (Optional[Callable]): Callback function to handle incoming messages
+
+        Returns:
+            Dict[str, Any]: Subscription response
+        """
+        subscription_data = {"type": stream_type, "productId": product_id}
+
+        if subaccount_id:
+            subscription_data["subaccountId"] = subaccount_id
+
+        # Register callback if provided
+        if callback:
+            event_key = stream_type
+            if event_key not in self.callbacks:
+                self.callbacks[event_key] = []
+
+            self.callbacks[event_key].append(callback)
+
+        # Send subscription request
+        return self._emit("subscribe", subscription_data, namespace=namespace)
+
+    def unsubscribe(
+        self,
+        stream_type: str,
+        product_id: str,
+        subaccount_id: Optional[str] = None,
+        namespace: Optional[str] = "/v1/stream",
+    ) -> Dict[str, Any]:
+        """Unsubscribe from a specific stream.
+
+        Args:
+            stream_type (str): Type of stream to unsubscribe from
+            product_id (str): Product ID to unsubscribe from
+            subaccount_id (Optional[str]): Subaccount ID, optional
+
+        Returns:
+            Dict[str, Any]: Unsubscription response
+        """
+        unsubscription_data = {"type": stream_type, "productId": product_id}
+
+        if subaccount_id:
+            unsubscription_data["subaccountId"] = subaccount_id
+
+        # Send unsubscription request
+        return self._emit("unsubscribe", unsubscription_data, namespace=namespace)

ethereal_sdk-0.1.0a1/ethereal_sdk.egg-info/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.2
+Name: ethereal-sdk
+Version: 0.1.0a1
+Summary: Python SDK for interacting with the Ethereal API
+Author: Meridian Labs
+License: MIT
+Project-URL: Homepage, https://github.com/meridianxyz/ethereal-py
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+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: License :: OSI Approved :: MIT License
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: eth-account>=0.13.5
+Requires-Dist: pydantic>=2.10.6
+Requires-Dist: python-dotenv>=1.0.1
+Requires-Dist: python-socketio>=5.12.1
+Requires-Dist: requests>=2.32.3
+Requires-Dist: web3>=7.8.0
+
+# ethereal-py-sdk
+
+**Welcome to ethereal-py-sdk!**
+
+Python SDK for interacting with the Ethereal API.
+
+## Getting started
+
+Before you start, make sure you have installed [uv](https://docs.astral.sh/uv/getting-started/installation/):
+
+```
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+Then you can install the SDK and run the tests:
+
+```bash
+# Clone the project
+git clone git@github.com:meridianxyz/ethereal-py-sdk.git
+
+# Install dependencies
+uv sync
+
+# Run tests
+uv run pytest
+
+# Run the linter
+uv run ruff check --fix
+
+# Run the example CLI
+uv run python -i examples/cli.py
+```
+
+## Usage
+
+Using the SDK using the REPL (example):
+
+```python
+import ethereal
+
+rc = ethereal.RESTClient()
+rc.list_products()
+```
+
+Or use the provided CLI:
+
+```bash
+cp .env.test .env
+
+uv run python -i examples/cli.py
+
+>>> rc.list_products()
+```
+
+## Generating Pydantic Type
+
+Ethereal uses an OpenAPI spec to represent the API. You can generate Pydantic models from the OpenAPI spec using the `datamodel-codegen` tool:
+
+```bash
+# place a `spec.json` in the root of the project
+uv run datamodel-codegen --input /path/to/api_spec.json \
+  --output ethereal/models/generated.py \
+  --input-file-type openapi \
+  --openapi-scopes paths schemas parameters \
+  --output-model-type pydantic_v2.BaseModel
+```
+
+## Documentation
+
+Docs are created using [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/). To run the docs locally:
+
+```bash
+# serve
+uv run mkdocs serve
+
+# build
+uv run mkdocs build
+```

ethereal_sdk-0.1.0a1/ethereal_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+README.md
+pyproject.toml
+ethereal/__init__.py
+ethereal/__version__.py
+ethereal/base_client.py
+ethereal/chain_client.py
+ethereal/constants.py
+ethereal/rest_client.py
+ethereal/ws_client.py
+ethereal_sdk.egg-info/PKG-INFO
+ethereal_sdk.egg-info/SOURCES.txt
+ethereal_sdk.egg-info/dependency_links.txt
+ethereal_sdk.egg-info/requires.txt
+ethereal_sdk.egg-info/top_level.txt
+tests/test_chain.py
+tests/test_clients.py

ethereal_sdk-0.1.0a1/ethereal_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

ethereal_sdk-0.1.0a1/ethereal_sdk.egg-info/requires.txt

@@ -0,0 +1,6 @@
+eth-account>=0.13.5
+pydantic>=2.10.6
+python-dotenv>=1.0.1
+python-socketio>=5.12.1
+requests>=2.32.3
+web3>=7.8.0

ethereal_sdk-0.1.0a1/ethereal_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+ethereal

ethereal_sdk-0.1.0a1/pyproject.toml

@@ -0,0 +1,52 @@
+[project]
+name = "ethereal-sdk"
+dynamic = ["version", "readme"]
+description = "Python SDK for interacting with the Ethereal API"
+authors = [{ name = "Meridian Labs" }]
+license = { text = "MIT" }
+requires-python = ">=3.8"
+classifiers = [
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "License :: OSI Approved :: MIT License",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "eth-account>=0.13.5",
+    "pydantic>=2.10.6",
+    "python-dotenv>=1.0.1",
+    "python-socketio>=5.12.1",
+    "requests>=2.32.3",
+    "web3>=7.8.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/meridianxyz/ethereal-py"
+
+[tool.setuptools]
+packages = ["ethereal"]
+
+[tool.setuptools.dynamic]
+version = { attr = "ethereal.__version__.__version__" }
+readme = { file = ["README.md"], content-type = "text/markdown" }
+dependencies = { file = ["requirements.txt"] }
+
+[tool.uv]
+dev-dependencies = [
+    "datamodel-code-generator>=0.27.3",
+    "ipykernel>=6.29.5",
+    "mkdocs-material>=9.6.4",
+    "mkdocstrings-python>=1.11.1",
+    "pytest>=8.3.4",
+    "pytest-asyncio>=0.24.0",
+    "ruff>=0.9.3",
+]
+
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"

ethereal_sdk-0.1.0a1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ethereal_sdk-0.1.0a1/tests/test_chain.py

@@ -0,0 +1,73 @@
+from web3 import Web3
+
+
+def test_provider(rc):
+    rc.logger.info(f"Chain ID: {rc.chain.chain_id}")
+    assert rc.provider is not None
+    assert isinstance(rc.provider, Web3)
+
+
+def test_block(rc):
+    """Test block method."""
+    block = rc.provider.eth.get_block("latest")
+    assert block is not None
+    assert block.get("number") is not None
+    assert block.get("hash") is not None
+
+
+def test_nonce(rc):
+    """Test nonce method."""
+    nonce = rc.chain.get_nonce(rc.chain.address)
+    rc.logger.info(f"Nonce: {nonce}")
+    assert nonce is not None
+
+
+def test_gas(rc):
+    """Test gas methods."""
+    gas_price = rc.provider.eth.gas_price
+    rc.logger.info(f"Gas Price: {gas_price}")
+    assert gas_price is not None
+    assert gas_price > 0
+
+    max_priority_fee = rc.provider.eth.max_priority_fee
+    rc.logger.info(f"Max Priority Fee: {max_priority_fee}")
+    assert max_priority_fee is not None
+    assert max_priority_fee > 0
+
+    gas_limit = rc.provider.eth.estimate_gas(
+        {"from": rc.chain.address, "to": rc.chain.address, "value": 1}
+    )
+    rc.logger.info(f"Gas Limit: {gas_limit}")
+    assert gas_limit is not None
+    assert gas_limit > 0
+
+
+def test_eth_balance(rc):
+    """Test eth balance method."""
+    balance = rc.chain.get_balance(rc.chain.address)
+    rc.logger.info(f"Balance: {balance}")
+    assert balance is not None
+    assert balance >= 0
+
+
+def test_usde_balance(rc):
+    """Test token balance method."""
+    balance = rc.chain.get_token_balance(rc.chain.address, rc.chain.usde.address)
+    rc.logger.info(f"Balance: {balance}")
+    assert balance is not None
+    assert balance >= 0
+
+
+def test_deposit_usde(rc):
+    """Test USDe deposit."""
+    deposit_tx = rc.chain.deposit_usde(100)
+    rc.logger.info(f"Deposit Tx: {deposit_tx}")
+
+    assert deposit_tx is not None
+    assert deposit_tx.get("data") is not None
+    assert rc.provider.is_checksum_address(deposit_tx.get("from"))
+    assert rc.provider.is_checksum_address(deposit_tx.get("to"))
+
+    # submit the transaction
+    # tx_hash = rc.chain.submit_tx(deposit_tx)
+    # rc.logger.info(f"Tx Hash: {tx_hash}")

ethereal_sdk-0.1.0a1/tests/test_clients.py

@@ -0,0 +1,125 @@
+from web3 import Web3
+from ethereal.models.config import (
+    BaseConfig,
+    HTTPConfig,
+    WSConfig,
+    ChainConfig,
+    RESTConfig,
+)
+from ethereal.base_client import BaseClient
+from ethereal.rest.http_client import HTTPClient
+from ethereal.ws.ws_base import WSBase
+from ethereal.chain_client import ChainClient
+from ethereal.rest_client import RESTClient
+
+BASE_URL = "https://api.etherealtest.net"
+RPC_URL = "https://rpc.etherealtest.net"
+WS_URL = "wss://ws.etherealtest.net"
+
+
+def test_base_client_with_dict():
+    bc = BaseClient({"verbose": True})
+    assert bc is not None
+
+
+def test_base_client_with_class():
+    config = BaseConfig(verbose=True)
+    bc = BaseClient(config)
+    assert bc is not None
+
+
+def test_http_client_with_dict():
+    hc = HTTPClient({"base_url": BASE_URL, "verbose": True})
+    assert hc is not None
+
+
+def test_ws_client_with_class():
+    config = WSConfig(base_url=WS_URL, verbose=True)
+    hc = WSBase(config)
+    assert hc is not None
+
+
+def test_ws_client_with_dict():
+    wsc = WSBase({"base_url": WS_URL, "verbose": True})
+    assert wsc is not None
+
+
+def test_http_client_with_class():
+    config = HTTPConfig(base_url=BASE_URL, timeout=60, verbose=True)
+    wsc = HTTPClient(config)
+    assert wsc is not None
+
+
+def test_chain_client_with_dict():
+    test_account = Web3().eth.account.create()
+    private_key = test_account.key.hex()
+
+    cc = ChainClient(
+        {
+            "rpc_url": RPC_URL,
+            "private_key": private_key,
+        }
+    )
+    assert cc is not None
+    assert cc.chain_id == 996353
+
+
+def test_chain_client_with_class():
+    test_account = Web3().eth.account.create()
+    private_key = test_account.key.hex()
+
+    config = ChainConfig(
+        rpc_url=RPC_URL,
+        private_key=private_key,
+    )
+    cc = ChainClient(config)
+    assert cc is not None
+    assert cc.chain_id == 996353
+
+
+def test_rest_chain_client_with_dict():
+    test_account = Web3().eth.account.create()
+    private_key = test_account.key.hex()
+
+    rc = RESTClient(
+        {
+            "base_url": BASE_URL,
+            "chain_config": {
+                "private_key": private_key,
+                "rpc_url": RPC_URL,
+            },
+        }
+    )
+    assert rc is not None
+    assert rc.chain.chain_id == 996353
+
+
+def test_rest_chain_client_with_class():
+    test_account = Web3().eth.account.create()
+    private_key = test_account.key.hex()
+
+    chain_config = ChainConfig(
+        rpc_url=RPC_URL,
+        private_key=private_key,
+    )
+
+    config = RESTConfig(
+        base_url=BASE_URL,
+        chain_config=chain_config,
+    )
+    rc = RESTClient(config)
+    assert rc is not None
+    assert rc.chain.chain_id == 996353
+
+
+def test_rest_client_with_dict():
+    rc = RESTClient()
+    assert rc is not None
+    assert rc.chain is None
+
+
+def test_rest_client_with_class():
+    config = RESTConfig()
+    rc = RESTClient(config)
+    assert rc is not None
+    assert rc.chain is None