x10-python-trading-starknet 0.0.1__py3-none-any.whl

x10/config.py

@@ -0,0 +1,13 @@
+import importlib.metadata
+
+TRADING_API_URL_DEV = "http://api.testnet.extended.exchange/api/v1"
+STREAM_API_URL_DEV = "wss://api.testnet.extended.exchange/stream.extended.exchange/v1"
+
+BTC_USD_MARKET = "BTC-USD"
+SOL_USD_MARKET = "SOL-USD"
+ADA_USD_MARKET = "ADA-USD"
+ETH_USD_MARKET = "ETH-USD"
+
+DEFAULT_REQUEST_TIMEOUT_SECONDS = 500
+SDK_VERSION = importlib.metadata.version("x10-python-trading")
+USER_AGENT = f"X10PythonTradingClient/{SDK_VERSION}"

x10/errors.py

@@ -0,0 +1,2 @@
+class X10Error(Exception):
+    pass

x10/perpetual/accounts.py

@@ -0,0 +1,86 @@
+from decimal import Decimal
+from typing import Dict, List, Optional, Tuple
+
+from fast_stark_crypto import sign
+from pydantic import AliasChoices, Field
+
+from x10.perpetual.balances import BalanceModel
+from x10.perpetual.fees import TradingFeeModel
+from x10.perpetual.orders import OpenOrderModel
+from x10.perpetual.positions import PositionModel
+from x10.perpetual.trades import AccountTradeModel
+from x10.utils.model import X10BaseModel
+from x10.utils.string import is_hex_string
+
+
+class StarkPerpetualAccount:
+    __vault: int
+    __private_key: int
+    __public_key: int
+    __trading_fee: Dict[str, TradingFeeModel]
+
+    def __init__(self, vault: int | str, private_key: str, public_key: str, api_key: str):
+        assert is_hex_string(private_key)
+        assert is_hex_string(public_key)
+
+        if isinstance(vault, str):
+            vault = int(vault)
+        elif isinstance(vault, int):
+            self.__vault = vault
+        else:
+            raise ValueError("Invalid vault type")
+
+        self.__vault = vault
+        self.__private_key = int(private_key, base=16)
+        self.__public_key = int(public_key, base=16)
+        self.__api_key = api_key
+        self.__trading_fee = {}
+
+    @property
+    def vault(self):
+        return self.__vault
+
+    @property
+    def public_key(self):
+        return self.__public_key
+
+    @property
+    def api_key(self):
+        return self.__api_key
+
+    @property
+    def trading_fee(self):
+        return self.__trading_fee
+
+    def sign(self, msg_hash: int) -> Tuple[int, int]:
+        return sign(private_key=self.__private_key, msg_hash=msg_hash)
+
+
+class AccountStreamDataModel(X10BaseModel):
+    orders: Optional[List[OpenOrderModel]] = None
+    positions: Optional[List[PositionModel]] = None
+    trades: Optional[List[AccountTradeModel]] = None
+    balance: Optional[BalanceModel] = None
+
+
+class AccountLeverage(X10BaseModel):
+    market: str
+    leverage: Decimal
+
+
+class AccountModel(X10BaseModel):
+    id: int = Field(validation_alias=AliasChoices("accountId", "id"), serialization_alias="id")
+    description: str
+    account_index: int
+    status: str
+    l2_key: str
+    l2_vault: int
+    api_keys: Optional[List[str]] = None
+
+
+class ApiKeyResponseModel(X10BaseModel):
+    key: str
+
+
+class ApiKeyRequestModel(X10BaseModel):
+    description: str

x10/perpetual/amounts.py

@@ -0,0 +1,55 @@
+import decimal
+from dataclasses import dataclass
+from decimal import Decimal
+
+from x10.perpetual.assets import Asset
+
+ROUNDING_SELL_CONTEXT = decimal.Context(rounding=decimal.ROUND_DOWN)
+ROUNDING_BUY_CONTEXT = decimal.Context(rounding=decimal.ROUND_UP)
+ROUNDING_FEE_CONTEXT = decimal.Context(rounding=decimal.ROUND_UP)
+
+
+@dataclass
+class HumanReadableAmount:
+    value: Decimal
+    asset: Asset
+
+    def to_l1_amount(self) -> "L1Amount":
+        converted_value = self.asset.convert_internal_quantity_to_l1_quantity(self.value)
+        return L1Amount(converted_value, self.asset)
+
+    def to_stark_amount(self, rounding_context: decimal.Context) -> "StarkAmount":
+        converted_value = self.asset.convert_human_readable_to_stark_quantity(self.value, rounding_context)
+        return StarkAmount(converted_value, self.asset)
+
+
+@dataclass
+class L1Amount:
+    value: int
+    asset: Asset
+
+    def to_internal_amount(self) -> HumanReadableAmount:
+        converted_value = self.asset.convert_l1_quantity_to_internal_quantity(self.value)
+        return HumanReadableAmount(converted_value, self.asset)
+
+
+@dataclass
+class StarkAmount:
+    value: int
+    asset: Asset
+
+    def to_internal_amount(self) -> HumanReadableAmount:
+        converted_value = self.asset.convert_stark_to_internal_quantity(self.value)
+        return HumanReadableAmount(converted_value, self.asset)
+
+    def negate(self) -> "StarkAmount":
+        return StarkAmount(-self.value, self.asset)
+
+
+@dataclass
+class StarkOrderAmounts:
+    collateral_amount_internal: HumanReadableAmount
+    synthetic_amount_internal: HumanReadableAmount
+    fee_amount_internal: HumanReadableAmount
+    fee_rate: Decimal
+    rounding_context: decimal.Context

x10/perpetual/assets.py

@@ -0,0 +1,71 @@
+from dataclasses import dataclass
+from decimal import Context, Decimal
+from enum import Enum
+from typing import Optional
+
+from x10.utils.model import HexValue, X10BaseModel
+
+
+@dataclass
+class Asset:
+    id: int
+    name: str
+    precision: int
+    active: bool
+    is_collateral: bool
+    settlement_external_id: str
+    settlement_resolution: int
+    l1_external_id: str
+    l1_resolution: int
+
+    def convert_human_readable_to_stark_quantity(self, internal: Decimal, rounding_context: Context) -> int:
+        return int(
+            rounding_context.multiply(internal, Decimal(self.settlement_resolution)).to_integral(
+                context=rounding_context
+            )
+        )
+
+    def convert_stark_to_internal_quantity(self, stark: int) -> Decimal:
+        return Decimal(stark) / Decimal(self.settlement_resolution)
+
+    def convert_l1_quantity_to_internal_quantity(self, l1: int) -> Decimal:
+        return Decimal(l1) / Decimal(self.l1_resolution)
+
+    def convert_internal_quantity_to_l1_quantity(self, internal: Decimal) -> int:
+        if not self.is_collateral:
+            raise ValueError("Only collateral assets have an L1 representation")
+        return int(internal * Decimal(self.l1_resolution))
+
+
+class AssetOperationType(str, Enum):
+    CLAIM = "CLAIM"
+    DEPOSIT = "DEPOSIT"
+    FAST_WITHDRAWAL = "FAST_WITHDRAWAL"
+    SLOW_WITHDRAWAL = "SLOW_WITHDRAWAL"
+    TRANSFER = "TRANSFER"
+
+
+class AssetOperationStatus(Enum):
+    # Technical status
+    UNKNOWN = "UNKNOWN"
+
+    CREATED = "CREATED"
+    IN_PROGRESS = "IN_PROGRESS"
+    REJECTED = "REJECTED"
+    READY_FOR_CLAIM = "READY_FOR_CLAIM"
+    COMPLETED = "COMPLETED"
+
+
+class AssetOperationModel(X10BaseModel):
+    id: str
+    type: AssetOperationType
+    status: AssetOperationStatus
+    amount: Decimal
+    fee: Decimal
+    asset: int
+    time: int
+    account_id: int
+
+    # When operation type is `TRANSFER`
+    counterparty_account_id: Optional[int] = None
+    transaction_hash: Optional[HexValue] = None

x10/perpetual/balances.py

@@ -0,0 +1,15 @@
+from decimal import Decimal
+
+from x10.utils.model import X10BaseModel
+
+
+class BalanceModel(X10BaseModel):
+    collateral_name: str
+    balance: Decimal
+    equity: Decimal
+    available_for_trade: Decimal
+    available_for_withdrawal: Decimal
+    unrealised_pnl: Decimal
+    initial_margin: Decimal
+    margin_ratio: Decimal
+    updated_time: int

x10/perpetual/candles.py

@@ -0,0 +1,18 @@
+from decimal import Decimal
+from typing import Literal
+
+from pydantic import AliasChoices, Field
+
+from x10.utils.model import X10BaseModel
+
+CandleType = Literal["trades", "mark-prices", "index-prices"]
+CandleInterval = Literal["PT1M", "PT5M", "PT15M", "PT30M", "PT1H", "PT2H", "PT4H", "P1D"]
+
+
+class CandleModel(X10BaseModel):
+    open: Decimal = Field(validation_alias=AliasChoices("open", "o"), serialization_alias="o")
+    low: Decimal = Field(validation_alias=AliasChoices("low", "l"), serialization_alias="l")
+    high: Decimal = Field(validation_alias=AliasChoices("high", "h"), serialization_alias="h")
+    close: Decimal = Field(validation_alias=AliasChoices("close", "c"), serialization_alias="c")
+    volume: Decimal = Field(validation_alias=AliasChoices("volume", "v"), serialization_alias="v")
+    timestamp: int = Field(validation_alias=AliasChoices("timestamp", "T"), serialization_alias="T")

x10/perpetual/configuration.py

@@ -0,0 +1,86 @@
+from dataclasses import dataclass
+
+
+@dataclass
+class StarknetDomain:
+    name: str
+    version: str
+    chain_id: str
+    revision: str
+
+
+@dataclass
+class EndpointConfig:
+    chain_rpc_url: str
+    api_base_url: str
+    stream_url: str
+    onboarding_url: str
+    signing_domain: str
+    collateral_asset_contract: str
+    asset_operations_contract: str
+    collateral_asset_on_chain_id: str
+    collateral_decimals: int
+    collateral_asset_id: str
+    starknet_domain: StarknetDomain
+
+
+TESTNET_CONFIG = EndpointConfig(
+    chain_rpc_url="https://rpc.sepolia.org",
+    api_base_url="https://api.testnet.extended.exchange/api/v1",
+    stream_url="wss://api.testnet.extended.exchange/stream.extended.exchange/v1",
+    onboarding_url="https://api.testnet.extended.exchange",
+    signing_domain="testnet.extended.exchange",
+    collateral_asset_contract="0x0C9165046063B7bCD05C6924Bbe05ed535c140a1",
+    asset_operations_contract="0xe42bb60Fab4EA4905832AEbDf0f001c784dA271b",
+    collateral_asset_on_chain_id="0x31857064564ed0ff978e687456963cba09c2c6985d8f9300a1de4962fafa054",
+    collateral_decimals=6,
+    collateral_asset_id="0x1",
+    starknet_domain=StarknetDomain(name="Perpetuals", version="v0", chain_id="SN_SEPOLIA", revision="1"),
+)
+
+MAINNET_CONFIG = EndpointConfig(
+    chain_rpc_url="https://cloudflare-eth.com",
+    api_base_url="https://api.extended.exchange/api/v1",
+    stream_url="wss://api.extended.exchange/stream.extended.exchange/v1",
+    onboarding_url="https://api.extended.exchange",
+    signing_domain="extended.exchange",
+    collateral_asset_contract="0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+    asset_operations_contract="0x1cE5D7f52A8aBd23551e91248151CA5A13353C65",
+    collateral_asset_on_chain_id="0x2893294412a4c8f915f75892b395ebbf6859ec246ec365c3b1f56f47c3a0a5d",
+    collateral_decimals=6,
+    collateral_asset_id="0x1",
+    starknet_domain=StarknetDomain(name="Perpetuals", version="v0", chain_id="SN_MAINNET", revision="1"),
+)
+
+"""
+Identical to the MAINNET_CONFIG, but with a different signing domain.
+Use it for accounts that were created before the signing domain was changed.
+"""
+MAINNET_CONFIG_LEGACY_SIGNING_DOMAIN = EndpointConfig(
+    chain_rpc_url="https://cloudflare-eth.com",
+    api_base_url="https://api.extended.exchange/api/v1",
+    stream_url="wss://api.extended.exchange/stream.extended.exchange/v1",
+    onboarding_url="https://api.extended.exchange",
+    signing_domain="x10.exchange",
+    collateral_asset_contract="0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+    asset_operations_contract="0x1cE5D7f52A8aBd23551e91248151CA5A13353C65",
+    collateral_asset_on_chain_id="0x2893294412a4c8f915f75892b395ebbf6859ec246ec365c3b1f56f47c3a0a5d",
+    collateral_decimals=6,
+    collateral_asset_id="0x1",
+    starknet_domain=StarknetDomain(name="Perpetuals", version="v0", chain_id="SN_MAINNET", revision="1"),
+)
+
+
+STARKNET_TESTNET_CONFIG = EndpointConfig(
+    chain_rpc_url="https://rpc.sepolia.org",
+    api_base_url="https://api.starknet.sepolia.extended.exchange/api/v1",
+    stream_url="wss://api.starknet.sepolia.extended.exchange/stream.extended.exchange/v1",
+    onboarding_url="https://api.starknet.sepolia.extended.exchange",
+    signing_domain="starknet.sepolia.extended.exchange",
+    collateral_asset_contract="0x0C9165046063B7bCD05C6924Bbe05ed535c140a1",
+    asset_operations_contract="0xe42bb60Fab4EA4905832AEbDf0f001c784dA271b",
+    collateral_asset_on_chain_id="0x31857064564ed0ff978e687456963cba09c2c6985d8f9300a1de4962fafa054",
+    collateral_decimals=6,
+    starknet_domain=StarknetDomain(name="Perpetuals", version="v0", chain_id="SN_SEPOLIA", revision="1"),
+    collateral_asset_id="0x1",
+)

x10/perpetual/fees.py

@@ -0,0 +1,16 @@
+from decimal import Decimal
+
+from x10.utils.model import X10BaseModel
+
+
+class TradingFeeModel(X10BaseModel):
+    market: str
+    maker_fee_rate: Decimal
+    taker_fee_rate: Decimal
+
+
+DEFAULT_FEES = TradingFeeModel(
+    market="BTC-USD",
+    maker_fee_rate=(Decimal("2") / Decimal("10000")),
+    taker_fee_rate=(Decimal("5") / Decimal("10000")),
+)

x10/perpetual/funding_rates.py

@@ -0,0 +1,11 @@
+from decimal import Decimal
+
+from pydantic import AliasChoices, Field
+
+from x10.utils.model import X10BaseModel
+
+
+class FundingRateModel(X10BaseModel):
+    market: str = Field(validation_alias=AliasChoices("market", "m"), serialization_alias="m")
+    funding_rate: Decimal = Field(validation_alias=AliasChoices("funding_rate", "f"), serialization_alias="f")
+    timestamp: int = Field(validation_alias=AliasChoices("timestamp", "T"), serialization_alias="T")

x10/perpetual/markets.py

@@ -0,0 +1,125 @@
+from decimal import ROUND_CEILING, Decimal
+from functools import cached_property
+from typing import List
+
+from x10.perpetual.assets import Asset
+from x10.utils.model import X10BaseModel
+
+
+class RiskFactorConfig(X10BaseModel):
+    upper_bound: Decimal
+    risk_factor: Decimal
+
+    @cached_property
+    def max_leverage(self) -> Decimal:
+        return round(Decimal(1) / self.risk_factor, 2)
+
+
+class MarketStatsModel(X10BaseModel):
+    daily_volume: Decimal
+    daily_volume_base: Decimal
+    daily_price_change: Decimal
+    daily_low: Decimal
+    daily_high: Decimal
+    last_price: Decimal
+    ask_price: Decimal
+    bid_price: Decimal
+    mark_price: Decimal
+    index_price: Decimal
+    funding_rate: Decimal
+    next_funding_rate: int
+    open_interest: Decimal
+    open_interest_base: Decimal
+
+
+class TradingConfigModel(X10BaseModel):
+    min_order_size: Decimal
+    min_order_size_change: Decimal
+    min_price_change: Decimal
+    max_market_order_value: Decimal
+    max_limit_order_value: Decimal
+    max_position_value: Decimal
+    max_leverage: Decimal
+    max_num_orders: int
+    limit_price_cap: Decimal
+    limit_price_floor: Decimal
+    risk_factor_config: List[RiskFactorConfig]
+
+    @cached_property
+    def price_precision(self) -> int:
+        return abs(int(self.min_price_change.log10().to_integral_exact(ROUND_CEILING)))
+
+    @cached_property
+    def quantity_precision(self) -> int:
+        return abs(int(self.min_order_size_change.log10().to_integral_exact(ROUND_CEILING)))
+
+    def max_leverage_for_position_value(self, position_value: Decimal) -> Decimal:
+        filtered = [x for x in self.risk_factor_config if x.upper_bound >= position_value]
+        return filtered[0].max_leverage if filtered else Decimal(0)
+
+    def max_position_value_for_leverage(self, leverage: Decimal) -> Decimal:
+        filtered = [x for x in self.risk_factor_config if x.max_leverage >= leverage]
+        return filtered[-1].upper_bound if filtered else Decimal(0)
+
+    def round_order_size(self, order_size: Decimal, rounding_direction: str = ROUND_CEILING) -> Decimal:
+        order_size = (order_size / self.min_order_size_change).to_integral_exact(
+            rounding_direction
+        ) * self.min_order_size_change
+        return order_size
+
+    def calculate_order_size_from_value(
+        self, order_value: Decimal, order_price: Decimal, rounding_direction: str = ROUND_CEILING
+    ) -> Decimal:
+        order_size = order_value / order_price
+        if order_size > 0:
+            return self.round_order_size(order_size, rounding_direction=rounding_direction)
+        else:
+            return Decimal(0)
+
+
+class L2ConfigModel(X10BaseModel):
+    type: str
+    collateral_id: str
+    collateral_resolution: int
+    synthetic_id: str
+    synthetic_resolution: int
+
+
+class MarketModel(X10BaseModel):
+    name: str
+    asset_name: str
+    asset_precision: int
+    collateral_asset_name: str
+    collateral_asset_precision: int
+    active: bool
+    market_stats: MarketStatsModel
+    trading_config: TradingConfigModel
+    l2_config: L2ConfigModel
+
+    @cached_property
+    def synthetic_asset(self) -> Asset:
+        return Asset(
+            id=1,
+            name=self.asset_name,
+            precision=self.asset_precision,
+            active=self.active,
+            is_collateral=False,
+            settlement_external_id=self.l2_config.synthetic_id,
+            settlement_resolution=self.l2_config.synthetic_resolution,
+            l1_external_id="",
+            l1_resolution=0,
+        )
+
+    @cached_property
+    def collateral_asset(self) -> Asset:
+        return Asset(
+            id=2,
+            name=self.collateral_asset_name,
+            precision=self.collateral_asset_precision,
+            active=self.active,
+            is_collateral=True,
+            settlement_external_id=self.l2_config.collateral_id,
+            settlement_resolution=self.l2_config.collateral_resolution,
+            l1_external_id="",
+            l1_resolution=0,
+        )