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

x10/perpetual/order_object.py

@@ -0,0 +1,201 @@
+import math
+from datetime import datetime, timedelta
+from decimal import Decimal
+from typing import Callable, Optional, Tuple
+
+from fast_stark_crypto import get_order_msg_hash
+
+from x10.perpetual.accounts import StarkPerpetualAccount
+from x10.perpetual.amounts import (
+    ROUNDING_BUY_CONTEXT,
+    ROUNDING_FEE_CONTEXT,
+    ROUNDING_SELL_CONTEXT,
+    HumanReadableAmount,
+    StarkAmount,
+)
+from x10.perpetual.configuration import StarknetDomain
+from x10.perpetual.fees import DEFAULT_FEES, TradingFeeModel
+from x10.perpetual.markets import MarketModel
+from x10.perpetual.orders import (
+    OrderSide,
+    OrderType,
+    PerpetualOrderModel,
+    SelfTradeProtectionLevel,
+    SettlementSignatureModel,
+    StarkDebuggingOrderAmountsModel,
+    StarkSettlementModel,
+    TimeInForce,
+)
+from x10.utils import generate_nonce
+from x10.utils.date import to_epoch_millis, utc_now
+
+
+def create_order_object(
+    account: StarkPerpetualAccount,
+    market: MarketModel,
+    amount_of_synthetic: Decimal,
+    price: Decimal,
+    side: OrderSide,
+    starknet_domain: StarknetDomain,
+    post_only: bool = False,
+    previous_order_id: Optional[str] = None,
+    expire_time: Optional[datetime] = None,
+    order_external_id: Optional[str] = None,
+    time_in_force: TimeInForce = TimeInForce.GTT,
+    self_trade_protection_level: SelfTradeProtectionLevel = SelfTradeProtectionLevel.ACCOUNT,
+    nonce: Optional[int] = None,
+) -> PerpetualOrderModel:
+    """
+    Creates an order object to be placed on the exchange using the `place_order` method.
+    """
+
+    if expire_time is None:
+        expire_time = utc_now() + timedelta(hours=1)
+
+    fees = account.trading_fee.get(market.name, DEFAULT_FEES)
+
+    return __create_order_object(
+        market=market,
+        synthetic_amount=amount_of_synthetic,
+        price=price,
+        side=side,
+        collateral_position_id=account.vault,
+        fees=fees,
+        signer=account.sign,
+        public_key=account.public_key,
+        exact_only=False,
+        expire_time=expire_time,
+        post_only=post_only,
+        previous_order_external_id=previous_order_id,
+        order_external_id=order_external_id,
+        time_in_force=time_in_force,
+        self_trade_protection_level=self_trade_protection_level,
+        starknet_domain=starknet_domain,
+        nonce=nonce,
+    )
+
+
+def __create_order_object(
+    market: MarketModel,
+    synthetic_amount: Decimal,
+    price: Decimal,
+    side: OrderSide,
+    collateral_position_id: int,
+    fees: TradingFeeModel,
+    signer: Callable[[int], Tuple[int, int]],
+    public_key: int,
+    starknet_domain: StarknetDomain,
+    exact_only: bool = False,
+    expire_time: Optional[datetime] = None,
+    post_only: bool = False,
+    previous_order_external_id: Optional[str] = None,
+    order_external_id: Optional[str] = None,
+    time_in_force: TimeInForce = TimeInForce.GTT,
+    self_trade_protection_level: SelfTradeProtectionLevel = SelfTradeProtectionLevel.ACCOUNT,
+    nonce: Optional[int] = None,
+) -> PerpetualOrderModel:
+    if exact_only:
+        raise NotImplementedError("`exact_only` option is not supported yet")
+
+    if expire_time is None:
+        raise ValueError("`expire_time` must be provided")
+    if nonce is None:
+        nonce = generate_nonce()
+    is_buying_synthetic = side == OrderSide.BUY
+    rounding_context = ROUNDING_BUY_CONTEXT if is_buying_synthetic else ROUNDING_SELL_CONTEXT
+
+    collateral_amount_human = HumanReadableAmount(synthetic_amount * price, market.collateral_asset)
+    synthetic_amount_human = HumanReadableAmount(synthetic_amount, market.synthetic_asset)
+    fee_amount_human = HumanReadableAmount(
+        fees.taker_fee_rate * collateral_amount_human.value,
+        market.collateral_asset,
+    )
+    fee_rate = fees.taker_fee_rate
+
+    stark_collateral_amount: StarkAmount = collateral_amount_human.to_stark_amount(rounding_context=rounding_context)
+    stark_synthetic_amount: StarkAmount = synthetic_amount_human.to_stark_amount(rounding_context=rounding_context)
+    stark_fee_amount: StarkAmount = fee_amount_human.to_stark_amount(rounding_context=ROUNDING_FEE_CONTEXT)
+
+    if is_buying_synthetic:
+        stark_collateral_amount = stark_collateral_amount.negate()
+    else:
+        stark_synthetic_amount = stark_synthetic_amount.negate()
+
+    debugging_amounts = StarkDebuggingOrderAmountsModel(
+        collateral_amount=Decimal(stark_collateral_amount.value),
+        fee_amount=Decimal(stark_fee_amount.value),
+        synthetic_amount=Decimal(stark_synthetic_amount.value),
+    )
+
+    order_hash = hash_order(
+        amount_synthetic=stark_synthetic_amount,
+        amount_collateral=stark_collateral_amount,
+        max_fee=stark_fee_amount,
+        nonce=nonce,
+        position_id=collateral_position_id,
+        expiration_timestamp=expire_time,
+        public_key=public_key,
+        starknet_domain=starknet_domain,
+    )
+
+    (order_signature_r, order_signature_s) = signer(order_hash)
+    settlement = StarkSettlementModel(
+        signature=SettlementSignatureModel(r=order_signature_r, s=order_signature_s),
+        stark_key=public_key,
+        collateral_position=Decimal(collateral_position_id),
+    )
+
+    order_id = str(order_hash) if order_external_id is None else order_external_id
+    order = PerpetualOrderModel(
+        id=order_id,
+        market=market.name,
+        type=OrderType.LIMIT,
+        side=side,
+        qty=synthetic_amount_human.value,
+        price=price,
+        post_only=post_only,
+        time_in_force=time_in_force,
+        expiry_epoch_millis=to_epoch_millis(expire_time),
+        fee=fee_rate,
+        self_trade_protection_level=self_trade_protection_level,
+        nonce=Decimal(nonce),
+        cancel_id=previous_order_external_id,
+        settlement=settlement,
+        debugging_amounts=debugging_amounts,
+    )
+
+    return order
+
+
+def hash_order(
+    amount_synthetic: StarkAmount,
+    amount_collateral: StarkAmount,
+    max_fee: StarkAmount,
+    nonce: int,
+    position_id: int,
+    expiration_timestamp: datetime,
+    public_key: int,
+    starknet_domain: StarknetDomain,
+) -> int:
+    synthetic_asset = amount_synthetic.asset
+    collateral_asset = amount_collateral.asset
+
+    expire_time_with_buffer = expiration_timestamp + timedelta(days=14)
+    expire_time_as_seconds = math.ceil(expire_time_with_buffer.timestamp())
+
+    return get_order_msg_hash(
+        position_id=position_id,
+        base_asset_id=int(synthetic_asset.settlement_external_id, 16),
+        base_amount=amount_synthetic.value,
+        quote_asset_id=int(collateral_asset.settlement_external_id, 16),
+        quote_amount=amount_collateral.value,
+        fee_amount=max_fee.value,
+        fee_asset_id=int(collateral_asset.settlement_external_id, 16),
+        expiration=expire_time_as_seconds,
+        salt=nonce,
+        user_public_key=public_key,
+        domain_name=starknet_domain.name,
+        domain_version=starknet_domain.version,
+        domain_chain_id=starknet_domain.chain_id,
+        domain_revision=starknet_domain.revision,
+    )

x10/perpetual/orderbook.py

@@ -0,0 +1,211 @@
+import asyncio
+import dataclasses
+import decimal
+from typing import Callable, Iterable, Tuple
+
+from sortedcontainers import SortedDict  # type: ignore[import-untyped]
+
+from x10.perpetual.configuration import EndpointConfig
+from x10.perpetual.orderbooks import OrderbookUpdateModel
+from x10.perpetual.stream_client.stream_client import PerpetualStreamClient
+from x10.utils.http import StreamDataType
+
+
+@dataclasses.dataclass
+class OrderBookEntry:
+    price: decimal.Decimal
+    amount: decimal.Decimal
+
+    def __repr__(self) -> str:
+        return f"OrderBookEntry(price={self.price}, amount={self.amount})"
+
+
+@dataclasses.dataclass
+class ImpactDetails:
+    price: decimal.Decimal
+    amount: decimal.Decimal
+
+
+class OrderBook:
+    @staticmethod
+    async def create(
+        endpoint_config: EndpointConfig,
+        market_name: str,
+        best_ask_change_callback: Callable[[OrderBookEntry], None] | None = None,
+        best_bid_change_callback: Callable[[OrderBookEntry], None] | None = None,
+        start=False,
+    ) -> "OrderBook":
+        ob = OrderBook(
+            endpoint_config,
+            market_name,
+            best_ask_change_callback,
+            best_bid_change_callback,
+        )
+        if start:
+            await ob.start_orderbook()
+        return ob
+
+    def __init__(
+        self,
+        endpoint_config: EndpointConfig,
+        market_name: str,
+        best_ask_change_callback: Callable[[OrderBookEntry], None] | None = None,
+        best_bid_change_callback: Callable[[OrderBookEntry], None] | None = None,
+    ) -> None:
+        self.__stream_client = PerpetualStreamClient(api_url=endpoint_config.stream_url)
+        self.__market_name = market_name
+        self.__task: asyncio.Task | None = None
+        self._bid_prices: SortedDict[decimal.Decimal, OrderBookEntry] = SortedDict()
+        self._ask_prices: SortedDict[decimal.Decimal, OrderBookEntry] = SortedDict()
+        self.best_ask_change_callback = best_ask_change_callback
+        self.best_bid_change_callback = best_bid_change_callback
+
+    def update_orderbook(self, data: OrderbookUpdateModel):
+        best_bid_before_update = self.best_bid()
+        for bid in data.bid:
+            if bid.price in self._bid_prices:
+                existing_bid_entry: OrderBookEntry = self._bid_prices.get(bid.price)
+                existing_bid_entry.amount = existing_bid_entry.amount + bid.qty
+                if existing_bid_entry.amount == 0:
+                    del self._bid_prices[bid.price]
+            else:
+                self._bid_prices[bid.price] = OrderBookEntry(
+                    price=bid.price,
+                    amount=bid.qty,
+                )
+        now_best_bid = self.best_bid()
+        if now_best_bid and best_bid_before_update != now_best_bid:
+            if self.best_bid_change_callback:
+                self.best_bid_change_callback(now_best_bid)
+
+        best_ask_before_update = self.best_ask()
+        for ask in data.ask:
+            if ask.price in self._ask_prices:
+                existing_ask_entry: OrderBookEntry = self._ask_prices.get(ask.price)
+                existing_ask_entry.amount = existing_ask_entry.amount + ask.qty
+                if existing_ask_entry.amount == 0:
+                    del self._ask_prices[ask.price]
+            else:
+                self._ask_prices[ask.price] = OrderBookEntry(
+                    price=ask.price,
+                    amount=ask.qty,
+                )
+        now_best_ask = self.best_ask()
+        if now_best_ask and best_ask_before_update != now_best_ask:
+            if self.best_ask_change_callback:
+                self.best_ask_change_callback(now_best_ask)
+
+    def init_orderbook(self, data: OrderbookUpdateModel):
+        for bid in data.bid:
+            self._bid_prices[bid.price] = OrderBookEntry(
+                price=bid.price,
+                amount=bid.qty,
+            )
+        for ask in data.ask:
+            self._ask_prices[ask.price] = OrderBookEntry(
+                price=ask.price,
+                amount=ask.qty,
+            )
+
+    async def start_orderbook(self) -> asyncio.Task:
+        loop = asyncio.get_running_loop()
+
+        async def inner():
+            async with self.__stream_client.subscribe_to_orderbooks(self.__market_name) as stream:
+                async for event in stream:
+                    if event.type == StreamDataType.SNAPSHOT.value:
+                        self.init_orderbook(event.data)
+                    elif event.type == StreamDataType.DELTA.value:
+                        self.update_orderbook(event.data)
+
+        self.__task = loop.create_task(inner())
+        return self.__task
+
+    def stop_orderbook(self):
+        if self.__task:
+            self.__task.cancel()
+            self.__task = None
+
+    def best_bid(self) -> OrderBookEntry | None:
+        try:
+            entry = self._bid_prices.peekitem(-1)
+            return entry[1]
+        except IndexError:
+            return None
+
+    def best_ask(self) -> OrderBookEntry | None:
+        try:
+            entry = self._ask_prices.peekitem(0)
+            return entry[1]
+        except IndexError:
+            return None
+
+    def __price_impact_notional(
+        self, notional: decimal.Decimal, levels: Iterable[Tuple[decimal.Decimal, OrderBookEntry]]
+    ):
+        remaining_to_spend = notional
+        total_amount = decimal.Decimal(0)
+        weighted_sum = decimal.Decimal(0)
+        for price, entry in levels:
+            available_at_price = entry.amount
+            amount_to_purchase = min(remaining_to_spend / price, available_at_price)
+            if remaining_to_spend <= 0:
+                break
+            if available_at_price <= 0:
+                continue
+            take = amount_to_purchase
+            spent = take * price
+            weighted_sum += take * price
+            total_amount += take
+            remaining_to_spend -= spent
+
+        if remaining_to_spend > 0:
+            return None
+        average_price = weighted_sum / total_amount
+        return ImpactDetails(price=average_price, amount=total_amount)
+
+    def __price_impact_qty(self, qty: decimal.Decimal, levels: Iterable[Tuple[decimal.Decimal, OrderBookEntry]]):
+        remaining_qty = qty
+        total_amount = decimal.Decimal(0)
+        total_spent = decimal.Decimal(0)
+        for price, entry in levels:
+            available_at_price = entry.amount
+            take = min(remaining_qty, available_at_price)
+            if remaining_qty <= 0:
+                break
+            if available_at_price <= 0:
+                continue
+            total_spent += take * price
+            total_amount += take
+            remaining_qty -= take
+
+        if remaining_qty > 0:
+            return None
+        average_price = total_spent / total_amount
+        return ImpactDetails(price=average_price, amount=total_amount)
+
+    def calculate_price_impact_notional(self, notional: decimal.Decimal, side: str) -> ImpactDetails | None:
+        if notional <= 0:
+            return None
+        if side == "SELL":
+            if not self._bid_prices:
+                return None
+            return self.__price_impact_notional(notional, reversed(self._bid_prices.items()))
+        elif side == "BUY":
+            if not self._ask_prices:
+                return None
+            return self.__price_impact_notional(notional, self._ask_prices.items())
+        return None
+
+    def calculate_price_impact_qty(self, qty: decimal.Decimal, side: str) -> ImpactDetails | None:
+        if qty <= 0:
+            return None
+        if side == "SELL":
+            if not self._bid_prices:
+                return None
+            return self.__price_impact_qty(qty, reversed(self._bid_prices.items()))
+        elif side == "BUY":
+            if not self._ask_prices:
+                return None
+            return self.__price_impact_qty(qty, self._ask_prices.items())
+        return None

x10/perpetual/orderbooks.py

@@ -0,0 +1,17 @@
+from decimal import Decimal
+from typing import List
+
+from pydantic import AliasChoices, Field
+
+from x10.utils.model import X10BaseModel
+
+
+class OrderbookQuantityModel(X10BaseModel):
+    qty: Decimal = Field(validation_alias=AliasChoices("qty", "q"), serialization_alias="q")
+    price: Decimal = Field(validation_alias=AliasChoices("price", "p"), serialization_alias="p")
+
+
+class OrderbookUpdateModel(X10BaseModel):
+    market: str = Field(validation_alias=AliasChoices("market", "m"), serialization_alias="m")
+    bid: List[OrderbookQuantityModel] = Field(validation_alias=AliasChoices("bid", "b"), serialization_alias="b")
+    ask: List[OrderbookQuantityModel] = Field(validation_alias=AliasChoices("ask", "a"), serialization_alias="a")

x10/perpetual/orders.py

@@ -0,0 +1,179 @@
+from decimal import Decimal
+from enum import Enum
+from typing import Optional
+
+from x10.utils.model import HexValue, SettlementSignatureModel, X10BaseModel
+
+
+class TimeInForce(Enum):
+    GTT = "GTT"
+    IOC = "IOC"
+    FOK = "FOK"
+
+
+class OrderSide(Enum):
+    BUY = "BUY"
+    SELL = "SELL"
+
+
+class OrderType(Enum):
+    LIMIT = "LIMIT"
+    CONDITIONAL = "CONDITIONAL"
+    MARKET = "MARKET"
+    TPSL = "TPSL"
+
+
+class OrderTpslType(Enum):
+    ORDER = "ORDER"
+    POSITION = "POSITION"
+
+
+class OrderStatus(Enum):
+    # Technical status
+    UNKNOWN = "UNKNOWN"
+
+    NEW = "NEW"
+    UNTRIGGERED = "UNTRIGGERED"
+    PARTIALLY_FILLED = "PARTIALLY_FILLED"
+    FILLED = "FILLED"
+    CANCELLED = "CANCELLED"
+    EXPIRED = "EXPIRED"
+    REJECTED = "REJECTED"
+
+
+class OrderStatusReason(Enum):
+    # Technical status
+    UNKNOWN = "UNKNOWN"
+
+    NONE = "NONE"
+    UNKNOWN_MARKET = "UNKNOWN_MARKET"
+    DISABLED_MARKET = "DISABLED_MARKET"
+    NOT_ENOUGH_FUNDS = "NOT_ENOUGH_FUNDS"
+    NO_LIQUIDITY = "NO_LIQUIDITY"
+    INVALID_FEE = "INVALID_FEE"
+    INVALID_QTY = "INVALID_QTY"
+    INVALID_PRICE = "INVALID_PRICE"
+    INVALID_VALUE = "INVALID_VALUE"
+    UNKNOWN_ACCOUNT = "UNKNOWN_ACCOUNT"
+    SELF_TRADE_PROTECTION = "SELF_TRADE_PROTECTION"
+    POST_ONLY_FAILED = "POST_ONLY_FAILED"
+    REDUCE_ONLY_FAILED = "REDUCE_ONLY_FAILED"
+    INVALID_EXPIRE_TIME = "INVALID_EXPIRE_TIME"
+    POSITION_TPSL_CONFLICT = "POSITION_TPSL_CONFLICT"
+    INVALID_LEVERAGE = "INVALID_LEVERAGE"
+    PREV_ORDER_NOT_FOUND = "PREV_ORDER_NOT_FOUND"
+    PREV_ORDER_TRIGGERED = "PREV_ORDER_TRIGGERED"
+    TPSL_OTHER_SIDE_FILLED = "TPSL_OTHER_SIDE_FILLED"
+    PREV_ORDER_CONFLICT = "PREV_ORDER_CONFLICT"
+    ORDER_REPLACED = "ORDER_REPLACED"
+    POST_ONLY_MODE = "POST_ONLY_MODE"
+    REDUCE_ONLY_MODE = "REDUCE_ONLY_MODE"
+    TRADING_OFF_MODE = "TRADING_OFF_MODE"
+
+
+class OrderTriggerPriceType(Enum):
+    # Technical status
+    UNKNOWN = "UNKNOWN"
+
+    MARK = "MARK"
+    INDEX = "INDEX"
+    LAST = "LAST"
+
+
+class OrderTriggerDirection(Enum):
+    # Technical status
+    UNKNOWN = "UNKNOWN"
+
+    UP = "UP"
+    DOWN = "DOWN"
+
+
+class OrderPriceType(Enum):
+    # Technical status
+    UNKNOWN = "UNKNOWN"
+
+    MARKET = "MARKET"
+    LIMIT = "LIMIT"
+
+
+class SelfTradeProtectionLevel(Enum):
+    DISABLED = "DISABLED"
+    ACCOUNT = "ACCOUNT"
+    CLIENT = "CLIENT"
+
+
+class StarkSettlementModel(X10BaseModel):
+    signature: SettlementSignatureModel
+    stark_key: HexValue
+    collateral_position: Decimal
+
+
+class StarkDebuggingOrderAmountsModel(X10BaseModel):
+    collateral_amount: Decimal
+    fee_amount: Decimal
+    synthetic_amount: Decimal
+
+
+class CreateOrderConditionalTriggerModel(X10BaseModel):
+    trigger_price: Decimal
+    trigger_price_type: OrderTriggerPriceType
+    direction: OrderTriggerDirection
+    execution_price_type: OrderPriceType
+
+
+class CreateOrderTpslTriggerModel(X10BaseModel):
+    trigger_price: Decimal
+    trigger_price_type: OrderTriggerPriceType
+    price: Decimal
+    price_type: OrderPriceType
+    settlement: StarkSettlementModel
+    debugging_amounts: Optional[StarkDebuggingOrderAmountsModel] = None
+
+
+class PerpetualOrderModel(X10BaseModel):
+    id: str
+    market: str
+    type: OrderType
+    side: OrderSide
+    qty: Decimal
+    price: Decimal
+    reduce_only: bool = False
+    post_only: bool = False
+    time_in_force: TimeInForce
+    expiry_epoch_millis: int
+    fee: Decimal
+    nonce: Decimal
+    self_trade_protection_level: SelfTradeProtectionLevel
+    cancel_id: Optional[str] = None
+    settlement: Optional[StarkSettlementModel] = None
+    trigger: Optional[CreateOrderConditionalTriggerModel] = None
+    tp_sl_type: Optional[OrderTpslType] = None
+    take_profit: Optional[CreateOrderTpslTriggerModel] = None
+    stop_loss: Optional[CreateOrderTpslTriggerModel] = None
+    debugging_amounts: Optional[StarkDebuggingOrderAmountsModel] = None
+
+
+class PlacedOrderModel(X10BaseModel):
+    id: int
+    external_id: str
+
+
+class OpenOrderModel(X10BaseModel):
+    id: int
+    account_id: int
+    external_id: str
+    market: str
+    type: OrderType
+    side: OrderSide
+    status: OrderStatus
+    status_reason: Optional[OrderStatusReason] = None
+    price: Decimal
+    average_price: Optional[Decimal] = None
+    qty: Decimal
+    filled_qty: Optional[Decimal] = None
+    reduce_only: bool
+    post_only: bool
+    payed_fee: Optional[Decimal] = None
+    created_time: int
+    updated_time: int
+    expiry_time: Optional[int] = None

x10/perpetual/positions.py

@@ -0,0 +1,51 @@
+from decimal import Decimal
+from enum import Enum
+from typing import Optional
+
+from x10.utils.model import X10BaseModel
+
+
+class ExitType(Enum):
+    TRADE = "TRADE"
+    LIQUIDATION = "LIQUIDATION"
+    ADL = "ADL"
+
+
+class PositionSide(Enum):
+    LONG = "LONG"
+    SHORT = "SHORT"
+
+
+class PositionModel(X10BaseModel):
+    id: int
+    account_id: int
+    market: str
+    side: PositionSide
+    leverage: Decimal
+    size: Decimal
+    value: Decimal
+    open_price: Decimal
+    mark_price: Decimal
+    liquidation_price: Optional[Decimal] = None
+    unrealised_pnl: Decimal
+    realised_pnl: Decimal
+    tp_price: Optional[Decimal] = None
+    sl_price: Optional[Decimal] = None
+    adl: Optional[int] = None
+    created_at: int
+    updated_at: int
+
+
+class PositionHistoryModel(X10BaseModel):
+    id: int
+    account_id: int
+    market: str
+    side: PositionSide
+    leverage: Decimal
+    size: Decimal
+    open_price: Decimal
+    exit_type: Optional[ExitType]
+    exit_price: Optional[Decimal]
+    realised_pnl: Decimal
+    created_time: int
+    closed_time: Optional[int]