Qubx 0.5.7__cp312-cp312-manylinux_2_39_x86_64.whl

qubx/connectors/ccxt/factory.py

@@ -0,0 +1,93 @@
+import asyncio
+from threading import Thread
+from typing import Any
+
+import ccxt.pro as cxp
+
+from .customizations import BinancePortfolioMargin, BinanceQV, BinanceQVUSDM
+
+EXCHANGE_ALIASES = {
+    "binance": "binanceqv",
+    "binance.um": "binanceqv_usdm",
+    "binance.cm": "binancecoinm",
+    "binance.pm": "binancepm",
+    "kraken.f": "krakenfutures",
+}
+
+cxp.binanceqv = BinanceQV  # type: ignore
+cxp.binanceqv_usdm = BinanceQVUSDM  # type: ignore
+cxp.binancepm = BinancePortfolioMargin  # type: ignore
+
+cxp.exchanges.append("binanceqv")
+cxp.exchanges.append("binanceqv_usdm")
+cxp.exchanges.append("binancepm")
+cxp.exchanges.append("binancepm_usdm")
+
+
+def get_ccxt_exchange(
+    exchange: str,
+    api_key: str | None = None,
+    secret: str | None = None,
+    loop: asyncio.AbstractEventLoop | None = None,
+    use_testnet: bool = False,
+    **kwargs,
+) -> cxp.Exchange:
+    """
+    Get a ccxt exchange object with the given api_key and api_secret.
+    Parameters:
+        exchange (str): The exchange name.
+        api_key (str, optional): The API key. Default is None.
+        api_secret (str, optional): The API secret. Default is None.
+    Returns:
+        ccxt.Exchange: The ccxt exchange object.
+    """
+    _exchange = exchange.lower()
+    _exchange = EXCHANGE_ALIASES.get(_exchange, _exchange)
+
+    if _exchange not in cxp.exchanges:
+        raise ValueError(f"Exchange {exchange} is not supported by ccxt.")
+
+    options: dict[str, Any] = {"name": exchange}
+
+    if loop is not None:
+        options["asyncio_loop"] = loop
+    else:
+        loop = asyncio.new_event_loop()
+        thread = Thread(target=loop.run_forever, daemon=True)
+        thread.start()
+        options["thread_asyncio_loop"] = thread
+        options["asyncio_loop"] = loop
+
+    api_key, secret = _get_api_credentials(api_key, secret, kwargs)
+    if api_key and secret:
+        options["apiKey"] = api_key
+        options["secret"] = secret
+
+    ccxt_exchange = getattr(cxp, _exchange)(options | kwargs)
+
+    if use_testnet:
+        ccxt_exchange.set_sandbox_mode(True)
+
+    return ccxt_exchange
+
+
+def _get_api_credentials(
+    api_key: str | None, secret: str | None, kwargs: dict[str, Any]
+) -> tuple[str | None, str | None]:
+    if api_key is None:
+        if "apiKey" in kwargs:
+            api_key = kwargs.pop("apiKey")
+        elif "key" in kwargs:
+            api_key = kwargs.pop("key")
+        elif "API_KEY" in kwargs:
+            api_key = kwargs.get("API_KEY")
+    if secret is None:
+        if "secret" in kwargs:
+            secret = kwargs.pop("secret")
+        elif "apiSecret" in kwargs:
+            secret = kwargs.pop("apiSecret")
+        elif "API_SECRET" in kwargs:
+            secret = kwargs.get("API_SECRET")
+        elif "SECRET" in kwargs:
+            secret = kwargs.get("SECRET")
+    return api_key, secret

qubx/connectors/ccxt/utils.py

@@ -0,0 +1,307 @@
+import re
+from typing import Any, Dict, List
+
+import numpy as np
+import pandas as pd
+
+import ccxt.pro as cxp
+from ccxt import BadSymbol
+from qubx import logger
+from qubx.core.basics import (
+    AssetBalance,
+    Deal,
+    FundingRate,
+    Instrument,
+    Liquidation,
+    Order,
+    Position,
+)
+from qubx.core.series import OrderBook, Quote, Trade, time_as_nsec
+from qubx.utils.marketdata.ccxt import (
+    ccxt_symbol_to_instrument,
+)
+from qubx.utils.orderbook import build_orderbook_snapshots
+
+from .exceptions import (
+    CcxtLiquidationParsingError,
+    CcxtSymbolNotRecognized,
+)
+
+EXCH_SYMBOL_PATTERN = re.compile(r"(?P<base>[^/]+)/(?P<quote>[^:]+)(?::(?P<margin>.+))?")
+
+
+def ccxt_convert_order_info(instrument: Instrument, raw: dict[str, Any]) -> Order:
+    """
+    Convert CCXT excution record to Order object
+    """
+    ri = raw["info"]
+    amnt = float(ri.get("origQty", raw.get("amount")))
+    price = raw["price"]
+    status = raw["status"]
+    side = raw["side"].upper()
+    _type = ri.get("type", raw.get("type")).upper()
+    if status == "open":
+        status = ri.get("status", status)  # for filled / part_filled ?
+
+    return Order(
+        id=raw["id"],
+        type=_type,
+        instrument=instrument,
+        time=pd.Timestamp(raw["timestamp"], unit="ms"),  # type: ignore
+        quantity=amnt,
+        price=float(price) if price is not None else 0.0,
+        side=side,
+        status=status.upper(),
+        time_in_force=raw["timeInForce"],
+        client_id=raw["clientOrderId"],
+        cost=float(raw["cost"] or 0),  # cost can be None
+    )
+
+
+def ccxt_convert_deal_info(raw: Dict[str, Any]) -> Deal:
+    fee_amount = None
+    fee_currency = None
+    if "fee" in raw:
+        fee_amount = float(raw["fee"]["cost"])
+        fee_currency = raw["fee"]["currency"]
+    return Deal(
+        id=raw["id"],
+        order_id=raw["order"],
+        time=pd.Timestamp(raw["timestamp"], unit="ms"),  # type: ignore
+        amount=float(raw["amount"]) * (-1 if raw["side"] == "sell" else +1),
+        price=float(raw["price"]),
+        aggressive=raw["takerOrMaker"] == "taker",
+        fee_amount=fee_amount,
+        fee_currency=fee_currency,
+    )
+
+
+def ccxt_extract_deals_from_exec(report: Dict[str, Any]) -> List[Deal]:
+    """
+    Small helper for extracting deals (trades) from CCXT execution report
+    """
+    deals = list()
+    if trades := report.get("trades"):
+        for t in trades:
+            deals.append(ccxt_convert_deal_info(t))
+    return deals
+
+
+def ccxt_restore_position_from_deals(
+    pos: Position, current_volume: float, deals: List[Deal], reserved_amount: float = 0.0
+) -> Position:
+    if current_volume != 0:
+        instr = pos.instrument
+        _last_deals = []
+
+        # - try to find last deals that led to this position
+        for d in sorted(deals, key=lambda x: x.time, reverse=True):
+            current_volume -= d.amount
+            # - spot case when fees may be deducted from the base coin
+            #   that may decrease total amount
+            if d.fee_amount is not None:
+                if instr.base == d.fee_currency:
+                    current_volume += d.fee_amount
+            # print(d.amount, current_volume)
+            _last_deals.insert(0, d)
+
+            # - take in account reserves
+            if abs(current_volume) - abs(reserved_amount) < instr.lot_size:
+                break
+
+        # - reset to 0
+        pos.reset()
+
+        if abs(current_volume) - abs(reserved_amount) > instr.lot_size:
+            # - - - TODO - - - !!!!
+            logger.warning(
+                f"Couldn't restore full deals history for {instr.symbol} symbol. Qubx will use zero position !"
+            )
+        else:
+            fees_in_base = 0.0
+            for d in _last_deals:
+                pos.update_position_by_deal(d)
+                if d.fee_amount is not None:
+                    if instr.base == d.fee_currency:
+                        fees_in_base += d.fee_amount
+            # - we round fees up in case of fees in base currency
+            pos.quantity -= pos.instrument.round_size_up(fees_in_base)
+    return pos
+
+
+def ccxt_convert_trade(trade: dict[str, Any]) -> Trade:
+    t_ns = trade["timestamp"] * 1_000_000  # this is trade time
+    info, price, amnt = trade["info"], trade["price"], trade["amount"]
+    m = info["m"]
+    return Trade(t_ns, price, amnt, int(not m), int(trade["id"]))
+
+
+def ccxt_convert_positions(
+    pos_infos: list[dict], ccxt_exchange_name: str, markets: dict[str, dict[str, Any]]
+) -> list[Position]:
+    positions = []
+    for info in pos_infos:
+        symbol = info["symbol"]
+        if symbol not in markets:
+            logger.warning(f"Could not find symbol {symbol}, skipping position...")
+            continue
+        instr = ccxt_symbol_to_instrument(
+            ccxt_exchange_name,
+            markets[symbol],
+        )
+        pos = Position(
+            instrument=instr,
+            quantity=info["contracts"] * (-1 if info["side"] == "short" else 1),
+            pos_average_price=info["entryPrice"],
+        )
+        pos.update_market_price(pd.Timestamp(info["timestamp"], unit="ms").asm8, info["markPrice"], 1)
+        positions.append(pos)
+    return positions
+
+
+def ccxt_convert_orderbook(
+    ob: dict, instr: Instrument, levels: int = 50, tick_size_pct: float = 0.01, sizes_in_quoted: bool = False
+) -> OrderBook | None:
+    """
+    Convert a ccxt order book to an OrderBook object with a fixed tick size percentage.
+    Parameters:
+        ob (dict): The order book dictionary from ccxt.
+        instr (Instrument): The instrument object containing market-specific details.
+        levels (int, optional): The number of levels to include in the order book. Default is 50.
+        tick_size_pct (float, optional): The tick size percentage. Default is 0.01%.
+        sizes_in_quoted (bool, optional): Whether the size is in the quoted currency. Default is False.
+    Returns:
+        OrderBook: The converted OrderBook object.
+    """
+    _dt = pd.Timestamp(ob["datetime"]).replace(tzinfo=None).asm8
+    _prev_dt = _dt - pd.Timedelta("1ms").asm8
+
+    updates = [
+        *[(_prev_dt, update[0], update[1], True) for update in ob["bids"]],
+        *[(_prev_dt, update[0], update[1], False) for update in ob["asks"]],
+    ]
+    # add an artificial update to trigger the snapshot building
+    updates.append((_dt, 0, 0, True))
+
+    try:
+        snapshots = build_orderbook_snapshots(
+            updates,
+            levels=levels,
+            tick_size_pct=tick_size_pct,
+            min_tick_size=instr.tick_size,
+            min_size_step=instr.lot_size,
+            sizes_in_quoted=sizes_in_quoted,
+        )
+    except Exception as e:
+        logger.error(f"Failed to build order book snapshots: {e}")
+        snapshots = None
+
+    if not snapshots:
+        return None
+
+    (dt, _bids, _asks, top_bid, top_ask, tick_size) = snapshots[-1]
+    bids = np.array([s for _, s in _bids[::-1]])
+    asks = np.array([s for _, s in _asks])
+
+    return OrderBook(
+        time=time_as_nsec(dt),
+        top_bid=top_bid,
+        top_ask=top_ask,
+        tick_size=tick_size,
+        bids=bids,
+        asks=asks,
+    )
+
+
+def ccxt_convert_liquidation(liq: dict[str, Any]) -> Liquidation:
+    try:
+        _dt = pd.Timestamp(liq["datetime"]).replace(tzinfo=None).asm8
+        return Liquidation(
+            time=_dt,
+            price=liq["price"],
+            quantity=liq["contracts"],
+            side=(1 if liq["info"]["S"] == "BUY" else -1),
+        )
+    except Exception as e:
+        raise CcxtLiquidationParsingError(f"Failed to parse liquidation: {e}")
+
+
+def ccxt_convert_ticker(ticker: dict[str, Any]) -> Quote:
+    """
+    Convert a ccxt ticker to a Quote object.
+    Parameters:
+        ticker (dict): The ticker dictionary from ccxt.
+        instr (Instrument): The instrument object containing market-specific details.
+    Returns:
+        Quote: The converted Quote object.
+    """
+    return Quote(
+        time=pd.Timestamp(ticker["datetime"]).replace(tzinfo=None).asm8,
+        bid=ticker["bid"],
+        ask=ticker["ask"],
+        bid_size=ticker["bidVolume"],
+        ask_size=ticker["askVolume"],
+    )
+
+
+def ccxt_convert_funding_rate(info: dict[str, Any]) -> FundingRate:
+    return FundingRate(
+        time=pd.Timestamp(info["timestamp"], unit="ms").asm8,
+        rate=info["fundingRate"],
+        interval=info["interval"],
+        next_funding_time=pd.Timestamp(info["nextFundingTime"], unit="ms").asm8,
+        mark_price=info.get("markPrice"),
+        index_price=info.get("indexPrice"),
+    )
+
+
+def ccxt_convert_balance(d: dict[str, Any]) -> dict[str, AssetBalance]:
+    balances = {}
+    for currency, data in d["total"].items():
+        if not data:
+            continue
+        total = float(d["total"].get(currency, 0) or 0)
+        locked = float(d["used"].get(currency, 0) or 0)
+        balances[currency] = AssetBalance(free=total - locked, locked=locked, total=total)
+    return balances
+
+
+def find_instrument_for_exch_symbol(exch_symbol: str, symbol_to_instrument: Dict[str, Instrument]) -> Instrument:
+    match = EXCH_SYMBOL_PATTERN.match(exch_symbol)
+    if not match:
+        raise CcxtSymbolNotRecognized(f"Invalid exchange symbol {exch_symbol}")
+    base = match.group("base")
+    quote = match.group("quote")
+    symbol = f"{base}{quote}"
+    if symbol not in symbol_to_instrument:
+        raise CcxtSymbolNotRecognized(f"Unknown symbol {symbol}")
+    return symbol_to_instrument[symbol]
+
+
+def instrument_to_ccxt_symbol(instr: Instrument) -> str:
+    return f"{instr.base}/{instr.quote}:{instr.settle}" if instr.is_futures() else f"{instr.base}/{instr.quote}"
+
+
+def ccxt_find_instrument(
+    symbol: str, exchange: cxp.Exchange, symbol_to_instrument: Dict[str, Instrument] | None = None
+) -> Instrument:
+    instrument = None
+    if symbol_to_instrument is not None:
+        instrument = symbol_to_instrument.get(symbol)
+        if instrument is not None:
+            return instrument
+        try:
+            instrument = find_instrument_for_exch_symbol(symbol, symbol_to_instrument)
+        except CcxtSymbolNotRecognized:
+            pass
+    if instrument is None:
+        try:
+            symbol_info = exchange.market(symbol)
+        except BadSymbol:
+            raise CcxtSymbolNotRecognized(f"Unknown symbol {symbol}")
+        exchange_name = exchange.name
+        assert exchange_name is not None
+        instrument = ccxt_symbol_to_instrument(exchange_name, symbol_info)
+    if symbol_to_instrument is not None and symbol not in symbol_to_instrument:
+        symbol_to_instrument[symbol] = instrument
+    return instrument

qubx/core/account.py

@@ -0,0 +1,251 @@
+from collections import defaultdict
+
+import numpy as np
+
+from qubx import logger
+from qubx.core.basics import (
+    ZERO_COSTS,
+    AssetBalance,
+    Deal,
+    Instrument,
+    ITimeProvider,
+    Order,
+    Position,
+    TransactionCostsCalculator,
+    dt_64,
+)
+from qubx.core.interfaces import IAccountProcessor
+
+
+class BasicAccountProcessor(IAccountProcessor):
+    account_id: str
+    time_provider: ITimeProvider
+    base_currency: str
+    commissions: str
+    _tcc: TransactionCostsCalculator
+    _balances: dict[str, AssetBalance]
+    _active_orders: dict[str, Order]
+    _processed_trades: dict[str, list[str | int]]
+    _positions: dict[Instrument, Position]
+    _locked_capital_by_order: dict[str, float]
+
+    def __init__(
+        self,
+        account_id: str,
+        time_provider: ITimeProvider,
+        base_currency: str,
+        tcc: TransactionCostsCalculator = ZERO_COSTS,
+        initial_capital: float = 100_000,
+    ) -> None:
+        self.account_id = account_id
+        self.time_provider = time_provider
+        self.base_currency = base_currency.upper()
+        self._tcc = tcc
+        self._processed_trades = defaultdict(list)
+        self._active_orders = dict()
+        self._positions = {}
+        self._locked_capital_by_order = dict()
+        self._balances = defaultdict(lambda: AssetBalance())
+        self._balances[self.base_currency] += initial_capital
+
+    def get_base_currency(self) -> str:
+        return self.base_currency
+
+    ########################################################
+    # Balance and position information
+    ########################################################
+    def get_capital(self) -> float:
+        return self.get_available_margin()
+
+    def get_total_capital(self) -> float:
+        # sum of cash + market value of all positions
+        _cash_amount = self._balances[self.base_currency].total
+        _positions_value = sum([p.market_value_funds for p in self._positions.values()])
+        return _cash_amount + _positions_value
+
+    def get_balances(self) -> dict[str, AssetBalance]:
+        return self._balances
+
+    def get_positions(self) -> dict[Instrument, Position]:
+        return self._positions
+
+    def get_position(self, instrument: Instrument) -> Position:
+        _pos = self._positions.get(instrument)
+        if _pos is None:
+            _pos = Position(instrument)
+            self._positions[instrument] = _pos
+        return _pos
+
+    def get_orders(self, instrument: Instrument | None = None) -> dict[str, Order]:
+        orders = self._active_orders.copy()
+        if instrument is not None:
+            orders = dict(filter(lambda x: x[1].instrument == instrument, orders.items()))
+        return orders
+
+    def position_report(self) -> dict:
+        rep = {}
+        for p in self._positions.values():
+            rep[p.instrument.symbol] = {
+                "Qty": p.quantity,
+                "Price": p.position_avg_price_funds,
+                "PnL": p.pnl,
+                "MktValue": p.market_value_funds,
+                "Leverage": self.get_leverage(p.instrument),
+            }
+        return rep
+
+    ########################################################
+    # Leverage information
+    ########################################################
+    def get_leverage(self, instrument: Instrument) -> float:
+        pos = self._positions.get(instrument)
+        if pos is not None:
+            return pos.notional_value / self.get_total_capital()
+        return 0.0
+
+    def get_leverages(self) -> dict[Instrument, float]:
+        return {s: self.get_leverage(s) for s in self._positions.keys()}
+
+    def get_net_leverage(self) -> float:
+        return sum(self.get_leverages().values())
+
+    def get_gross_leverage(self) -> float:
+        return sum(map(abs, self.get_leverages().values()))
+
+    ########################################################
+    # Margin information
+    # Used for margin, swap, futures, options trading
+    ########################################################
+    def get_total_required_margin(self) -> float:
+        # sum of margin required for all positions
+        return sum([p.maint_margin for p in self._positions.values()])
+
+    def get_available_margin(self) -> float:
+        # total capital - total required margin
+        return self.get_total_capital() - self.get_total_required_margin()
+
+    def get_margin_ratio(self) -> float:
+        # total capital / total required margin
+        return self.get_total_capital() / self.get_total_required_margin()
+
+    ########################################################
+    # Order and trade processing
+    ########################################################
+    def update_balance(self, currency: str, total: float, locked: float):
+        # create new asset balance if doesn't exist, otherwise update existing
+        if currency not in self._balances:
+            self._balances[currency] = AssetBalance(free=total - locked, locked=locked, total=total)
+        else:
+            self._balances[currency].free = total - locked
+            self._balances[currency].locked = locked
+            self._balances[currency].total = total
+
+    def attach_positions(self, *position: Position) -> IAccountProcessor:
+        for p in position:
+            if p.instrument not in self._positions:
+                self._positions[p.instrument] = p
+            else:
+                self._positions[p.instrument].reset_by_position(p)
+        return self
+
+    def add_active_orders(self, orders: dict[str, Order]):
+        for oid, od in orders.items():
+            self._active_orders[oid] = od
+
+    def update_position_price(self, time: dt_64, instrument: Instrument, price: float) -> None:
+        if instrument in self._positions:
+            p = self._positions[instrument]
+            p.update_market_price(time, price, 1)
+
+    def process_order(self, order: Order, update_locked_value: bool = True) -> None:
+        _new = order.status == "NEW"
+        _open = order.status == "OPEN"
+        _closed = order.status == "CLOSED"
+        _cancel = order.status == "CANCELED"
+
+        if _open or _new:
+            self._active_orders[order.id] = order
+
+            # - calculate amount locked by this order
+            if update_locked_value and order.type == "LIMIT":
+                self._lock_limit_order_value(order)
+
+        if _closed or _cancel:
+            if order.id in self._processed_trades:
+                self._processed_trades.pop(order.id)
+
+            if order.id in self._active_orders:
+                self._active_orders.pop(order.id)
+
+        # - calculate amount to unlock after canceling
+        if _cancel and update_locked_value and order.type == "LIMIT":
+            self._unlock_limit_order_value(order)
+
+        logger.debug(
+            f"  [<y>{self.__class__.__name__}</y>(<g>{order.instrument}</g>)] :: New status for order <r>{order.id}</r> -> <y>{order.status}</y> ({order.type} {order.side} {order.quantity}"
+            f"{(' @ ' + str(order.price)) if order.price else ''})"
+        )
+
+    def process_deals(self, instrument: Instrument, deals: list[Deal]) -> None:
+        self._fill_missing_fee_info(instrument, deals)
+        pos = self._positions.get(instrument)
+
+        if pos is not None:
+            conversion_rate = 1
+            traded_amnt, realized_pnl, deal_cost = 0, 0, 0
+
+            # - process deals
+            for d in deals:
+                if d.id not in self._processed_trades[d.order_id]:
+                    self._processed_trades[d.order_id].append(d.id)
+                    r_pnl, fee_in_base = pos.update_position_by_deal(d, conversion_rate)
+                    realized_pnl += r_pnl
+                    deal_cost += d.amount * d.price / conversion_rate
+                    traded_amnt += d.amount
+                    total_cost = deal_cost + fee_in_base
+                    logger.debug(
+                        f"  [<y>{self.__class__.__name__}</y>(<g>{instrument}</g>)] :: traded {d.amount} @ {d.price} -> {realized_pnl:.2f} {self.base_currency} realized profit"
+                    )
+                    if not instrument.is_futures():
+                        self._balances[self.base_currency] -= total_cost
+                        self._balances[instrument.base] += d.amount
+                    else:
+                        self._balances[self.base_currency] -= fee_in_base
+                        self._balances[instrument.settle] += realized_pnl
+
+    def _fill_missing_fee_info(self, instrument: Instrument, deals: list[Deal]) -> None:
+        for d in deals:
+            if d.fee_amount is None:
+                d.fee_amount = self._tcc.get_execution_fees(
+                    instrument=instrument, exec_price=d.price, amount=d.amount, crossed_market=d.aggressive
+                )
+                # this is only true for linear contracts
+                d.fee_currency = instrument.quote
+
+    def _lock_limit_order_value(self, order: Order) -> float:
+        pos = self._positions.get(order.instrument)
+        excess = 0.0
+        # - we handle only instruments it;s subscribed to
+        if pos:
+            sgn = -1 if order.side == "SELL" else +1
+            pos_change = sgn * order.quantity
+            direction = np.sign(pos_change)
+            prev_direction = np.sign(pos.quantity)
+            # how many shares are closed/open
+            qty_closing = min(abs(pos.quantity), abs(pos_change)) * direction if prev_direction != direction else 0
+            qty_opening = pos_change if prev_direction == direction else pos_change - qty_closing
+            excess = abs(qty_opening) * order.price
+
+            # TODO: locking likely doesn't work correctly for spot accounts (Account)
+            # Example: if we have 1 BTC at price 100k and set a limit order for 0.1 BTC at 110k
+            # it will not lock 0.1 BTC
+            if excess > 0:
+                self._balances[self.base_currency].lock(excess)
+                self._locked_capital_by_order[order.id] = excess
+
+        return excess
+
+    def _unlock_limit_order_value(self, order: Order):
+        if order.id in self._locked_capital_by_order:
+            excess = self._locked_capital_by_order.pop(order.id)
+            self._balances[self.base_currency].lock(-excess)