pybinbot 2.1.0__tar.gz → 2.1.2__tar.gz

{pybinbot-2.1.0/pybinbot.egg-info → pybinbot-2.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pybinbot
-Version: 2.1.0
+Version: 2.1.2
 Summary: Utility functions for the binbot project.
 Author-email: Carlos Wu <carkodw@gmail.com>
 Requires-Python: >=3.15
@@ -11,7 +11,7 @@ Requires-Dist: numpy==2.5.4
 Requires-Dist: pandas==3.1.1
 Requires-Dist: pandas-stubs==3.1.0.261029
 Requires-Dist: requests>=2.32.5
-Requires-Dist: kucoin-universal-sdk>=1.3.0
+Requires-Dist: kucoin-universal-sdk>=1.3.2
 Requires-Dist: aiohttp<3.15,>=3.14.1
 Requires-Dist: websocket-client>=1.9.0
 Requires-Dist: python-dotenv>=1.2.1
@@ -54,6 +54,22 @@ uv sync --extra dev
 
 `--extra dev` also installs development tools like ruff and mypy
 
+## Futures order triggers
+
+`KucoinFutures.place_futures_order()` defaults every conditional order to KuCoin's
+last traded price (`stopPriceType=TP`) when `stop_price_type` is omitted or `None`.
+This applies to both buy and sell orders, stop-market and stop-limit orders, and
+opening and reducing orders. Explicit mark/index trigger types remain supported.
+Orders without `stop` do not send a trigger-price type. Trigger levels, limit
+prices, quantities, leverage, and fill handling are unchanged.
+
+Last price can fluctuate more than mark price, but selecting it does not guarantee
+the highest selling price or lowest buying price; fills depend on the order book.
+
+`KucoinFutures.get_ticker_price(symbol)` returns the last traded contract price
+from the futures ticker. The spot client exposes the same method for spot prices;
+`KucoinFutures.get_mark_price(symbol)` remains available for mark prices.
+
 ## Telegram delivery
 
 Import `TelegramDelivery` from `pybinbot.shared.telegram_delivery`. Initialization

{pybinbot-2.1.0 → pybinbot-2.1.2}/README.md

@@ -25,6 +25,22 @@ uv sync --extra dev
 
 `--extra dev` also installs development tools like ruff and mypy
 
+## Futures order triggers
+
+`KucoinFutures.place_futures_order()` defaults every conditional order to KuCoin's
+last traded price (`stopPriceType=TP`) when `stop_price_type` is omitted or `None`.
+This applies to both buy and sell orders, stop-market and stop-limit orders, and
+opening and reducing orders. Explicit mark/index trigger types remain supported.
+Orders without `stop` do not send a trigger-price type. Trigger levels, limit
+prices, quantities, leverage, and fill handling are unchanged.
+
+Last price can fluctuate more than mark price, but selecting it does not guarantee
+the highest selling price or lowest buying price; fills depend on the order book.
+
+`KucoinFutures.get_ticker_price(symbol)` returns the last traded contract price
+from the futures ticker. The spot client exposes the same method for spot prices;
+`KucoinFutures.get_mark_price(symbol)` remains available for mark prices.
+
 ## Telegram delivery
 
 Import `TelegramDelivery` from `pybinbot.shared.telegram_delivery`. Initialization

{pybinbot-2.1.0 → pybinbot-2.1.2}/pybinbot/__init__.py

@@ -38,6 +38,7 @@ from pybinbot.shared.enums import (
     BinanceOrderModel,
     CloseConditions,
     DealType,
+    EntryMode,
     ExchangeId,
     KucoinKlineIntervals,
     MarketDominance,
@@ -282,6 +283,7 @@ __all__ = [
     # enums
     "CloseConditions",
     "DealType",
+    "EntryMode",
     "BinanceOrderModel",
     "Status",
     "Position",

{pybinbot-2.1.0 → pybinbot-2.1.2}/pybinbot/apis/kucoin/futures.py

@@ -1,5 +1,6 @@
 import logging
 from decimal import Decimal
+from math import isfinite
 from pybinbot import KucoinRest, KucoinKlineIntervals, OrderType, OrderStatus, DealType
 from requests import HTTPError, request
 from uuid import uuid4
@@ -27,6 +28,7 @@ from kucoin_universal_sdk.generate.futures.market import (
     GetMarkPriceReqBuilder,
     GetSymbolReqBuilder,
     GetSymbolResp,
+    GetTickerReqBuilder,
 )
 from kucoin_universal_sdk.generate.futures.fundingfees import (
     GetPublicFundingHistoryReqBuilder,
@@ -204,6 +206,23 @@ class KucoinFutures(KucoinRest):
             if item.funding_rate is not None
         ]
 
+    def get_ticker_price(self, symbol: str) -> float:
+        """Return the last traded futures price from the contract ticker."""
+        req = GetTickerReqBuilder().set_symbol(symbol).build()
+        response = self.futures_market_api.get_ticker(req)
+        if response is None:
+            raise ValueError(f"KuCoin futures ticker returned no response for {symbol}")
+        if response.price is None:
+            raise ValueError(
+                f"KuCoin futures ticker returned no price for {symbol}: {response!r}"
+            )
+        price = float(response.price)
+        if not isfinite(price) or price <= 0:
+            raise ValueError(
+                f"KuCoin futures ticker returned an invalid price for {symbol}"
+            )
+        return price
+
     def get_mark_price(self, symbol: str) -> float:
         req = GetMarkPriceReqBuilder().set_symbol(symbol).build()
         response = self.futures_market_api.get_mark_price(req)
@@ -573,11 +592,11 @@ class KucoinFutures(KucoinRest):
             margin_mode: Optional margin mode, "ISOLATED" or "CROSS".
             reduce_only: Optional reduce-only flag.
             close_order: Optional close-position flag.
-            stop: Optional stop direction (DOWN/UP). If provided, stop_price and
-                stop_price_type must also be set.
+            stop: Optional stop direction (DOWN/UP). Requires stop_price.
             stop_price: Optional stop trigger price. Required when stop is set.
-            stop_price_type: Optional stop price type (TP/MP/IP). Required when
-                stop is set.
+            stop_price_type: Optional stop price type (TP/MP/IP). Defaults to
+                last traded price (TP) for all conditional orders. An explicit
+                value overrides the default. Has no effect without stop.
             post_only: Whether a limit order must rest as maker liquidity.
             client_oid: Caller-owned idempotency key; generated when omitted.
         """
@@ -627,10 +646,10 @@ class KucoinFutures(KucoinRest):
 
         # Optional stop-loss / take-profit trigger parameters
         if stop is not None:
-            if stop_price is None or stop_price_type is None:
-                raise ValueError(
-                    "stop_price and stop_price_type must be provided when stop is set"
-                )
+            if stop_price is None:
+                raise ValueError("stop_price must be provided when stop is set")
+            if stop_price_type is None:
+                stop_price_type = AddOrderReq.StopPriceTypeEnum.TRADE_PRICE
             builder = builder.set_stop(stop)
             builder = builder.set_stop_price(str(stop_price))
             builder = builder.set_stop_price_type(stop_price_type)

{pybinbot-2.1.0 → pybinbot-2.1.2}/pybinbot/models/bot_base.py

@@ -1,11 +1,12 @@
 from typing import Literal
 from uuid import UUID
 
-from pydantic import BaseModel, Field, field_validator, model_validator
+from pydantic import BaseModel, Field, ValidationInfo, field_validator, model_validator
 
 from pybinbot.shared.enums import (
     BinanceKlineIntervals,
     CloseConditions,
+    EntryMode,
     MarketType,
     Position,
     QuoteAssets,
@@ -46,6 +47,14 @@ class BotBase(BaseModel):
     )
     created_at: float = Field(default_factory=timestamp)
     updated_at: float = Field(default_factory=timestamp)
+    entry_mode: EntryMode = Field(default=EntryMode.immediate, validate_default=True)
+    entry_price: float | None = Field(default=None, ge=0, allow_inf_nan=False)
+    entry_expires_at: float = Field(
+        default_factory=lambda data: data["created_at"] + 6 * 60 * 60 * 1000,
+        gt=0,
+        allow_inf_nan=False,
+        description="Absolute entry deadline in Unix milliseconds; defaults to creation + 6 hours",
+    )
     dynamic_trailing: bool = Field(default=False)
     dynamic_position_sizing: bool = Field(default=False)
     logs: list = Field(default=[])
@@ -104,6 +113,27 @@ class BotBase(BaseModel):
         },
     }
 
+    @field_validator("entry_mode", mode="before")
+    @classmethod
+    def default_entry_mode(cls, value):
+        return EntryMode.immediate if value is None else value
+
+    @field_validator("entry_expires_at", mode="before")
+    @classmethod
+    def default_entry_expiry(cls, value, info: ValidationInfo):
+        return info.data["created_at"] + 6 * 60 * 60 * 1000 if value is None else value
+
+    @model_validator(mode="after")
+    def validate_conditional_entry(self):
+        if self.entry_mode == EntryMode.conditional_limit:
+            if self.entry_price is None or self.entry_price <= 0:
+                raise ValueError(
+                    "Conditional limit entry requires a positive entry_price"
+                )
+            if self.market_type != MarketType.FUTURES:
+                raise ValueError("Conditional limit entry currently requires futures")
+        return self
+
     @model_validator(mode="after")
     def validate_dynamic_position_sizing(self):
         if self.dynamic_position_sizing:

{pybinbot-2.1.0 → pybinbot-2.1.2}/pybinbot/shared/enums.py

@@ -60,6 +60,11 @@ class Status(str, Enum):
     error = "error"
 
 
+class EntryMode(str, Enum):
+    immediate = "immediate"
+    conditional_limit = "conditional_limit"
+
+
 class Position(str, Enum):
     long = "long"
     short = "short"

{pybinbot-2.1.0 → pybinbot-2.1.2}/pybinbot/streaming/binance/socket_manager.py

@@ -1,7 +1,7 @@
 import json
 import logging
-import threading
 import time
+from threading import Thread
 
 from websocket import (
     ABNF,
@@ -11,7 +11,7 @@ from websocket import (
 )
 
 
-class BinanceSocketManager(threading.Thread):
+class BinanceSocketManager(Thread):
     def __init__(
         self,
         stream_url,
@@ -23,7 +23,7 @@ class BinanceSocketManager(threading.Thread):
         on_pong=None,
         logger=None,
     ):
-        threading.Thread.__init__(self)
+        Thread.__init__(self)
         if not logger:
             logger = logging.getLogger(__name__)
         self.logger = logger

{pybinbot-2.1.0 → pybinbot-2.1.2/pybinbot.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pybinbot
-Version: 2.1.0
+Version: 2.1.2
 Summary: Utility functions for the binbot project.
 Author-email: Carlos Wu <carkodw@gmail.com>
 Requires-Python: >=3.15
@@ -11,7 +11,7 @@ Requires-Dist: numpy==2.5.4
 Requires-Dist: pandas==3.1.1
 Requires-Dist: pandas-stubs==3.1.0.261029
 Requires-Dist: requests>=2.32.5
-Requires-Dist: kucoin-universal-sdk>=1.3.0
+Requires-Dist: kucoin-universal-sdk>=1.3.2
 Requires-Dist: aiohttp<3.15,>=3.14.1
 Requires-Dist: websocket-client>=1.9.0
 Requires-Dist: python-dotenv>=1.2.1
@@ -54,6 +54,22 @@ uv sync --extra dev
 
 `--extra dev` also installs development tools like ruff and mypy
 
+## Futures order triggers
+
+`KucoinFutures.place_futures_order()` defaults every conditional order to KuCoin's
+last traded price (`stopPriceType=TP`) when `stop_price_type` is omitted or `None`.
+This applies to both buy and sell orders, stop-market and stop-limit orders, and
+opening and reducing orders. Explicit mark/index trigger types remain supported.
+Orders without `stop` do not send a trigger-price type. Trigger levels, limit
+prices, quantities, leverage, and fill handling are unchanged.
+
+Last price can fluctuate more than mark price, but selecting it does not guarantee
+the highest selling price or lowest buying price; fills depend on the order book.
+
+`KucoinFutures.get_ticker_price(symbol)` returns the last traded contract price
+from the futures ticker. The spot client exposes the same method for spot prices;
+`KucoinFutures.get_mark_price(symbol)` remains available for mark prices.
+
 ## Telegram delivery
 
 Import `TelegramDelivery` from `pybinbot.shared.telegram_delivery`. Initialization

{pybinbot-2.1.0 → pybinbot-2.1.2}/pybinbot.egg-info/SOURCES.txt

@@ -57,6 +57,7 @@ tests/test_bot_futures_leverage.py
 tests/test_breadth.py
 tests/test_candles.py
 tests/test_coingecko.py
+tests/test_conditional_entry.py
 tests/test_conditional_futures_orders.py
 tests/test_deal_model.py
 tests/test_derivatives_api.py

{pybinbot-2.1.0 → pybinbot-2.1.2}/pybinbot.egg-info/requires.txt

@@ -3,7 +3,7 @@ numpy==2.5.4
 pandas==3.1.1
 pandas-stubs==3.1.0.261029
 requests>=2.32.5
-kucoin-universal-sdk>=1.3.0
+kucoin-universal-sdk>=1.3.2
 aiohttp<3.15,>=3.14.1
 websocket-client>=1.9.0
 python-dotenv>=1.2.1

{pybinbot-2.1.0 → pybinbot-2.1.2}/pyproject.toml

@@ -22,7 +22,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pybinbot"
-version = "2.1.0"
+version = "2.1.2"
 description = "Utility functions for the binbot project."
 authors = [
     { name="Carlos Wu", email="carkodw@gmail.com" }
@@ -35,7 +35,7 @@ dependencies = [
     "pandas==3.1.1",
     "pandas-stubs==3.1.0.261029",
     "requests>=2.32.5",
-    "kucoin-universal-sdk>=1.3.0",
+    "kucoin-universal-sdk>=1.3.2",
     "aiohttp>=3.14.1,<3.15",
     "websocket-client>=1.9.0",
     "python-dotenv>=1.2.1",

pybinbot-2.1.2/tests/test_conditional_entry.py

@@ -0,0 +1,45 @@
+import pytest
+from pydantic import ValidationError
+
+from pybinbot import BotBase, EntryMode, MarketType
+
+
+@pytest.mark.parametrize(
+    "overrides",
+    [{}, {"entry_mode": None, "entry_expires_at": None, "entry_price": None}],
+)
+def test_omitted_or_null_entry_fields_default_to_immediate_and_six_hours(overrides):
+    bot = BotBase(pair="XBTUSDTM", created_at=1000, **overrides)
+    assert bot.entry_mode == EntryMode.immediate
+    assert bot.entry_expires_at == 21_601_000
+    assert bot.entry_price is None
+    assert bot.model_dump(mode="json")["entry_price"] is None
+
+
+def test_conditional_entry_serializes_strings_and_preserves_deadline():
+    bot = BotBase(
+        pair="XBTUSDTM",
+        market_type=MarketType.FUTURES,
+        entry_mode="conditional_limit",
+        entry_price=100,
+        entry_expires_at=9000,
+    )
+    assert bot.model_dump(mode="json")["entry_mode"] == "conditional_limit"
+    assert bot.entry_expires_at == 9000
+
+
+@pytest.mark.parametrize(
+    "values",
+    [
+        {"entry_mode": "unknown"},
+        {"entry_mode": "conditional_limit"},
+        {"entry_mode": "conditional_limit", "entry_price": None},
+        {"entry_mode": "conditional_limit", "entry_price": 0},
+        {"entry_mode": "conditional_limit", "entry_price": -1},
+        {"entry_mode": "conditional_limit", "entry_price": float("inf")},
+        {"entry_expires_at": float("nan")},
+    ],
+)
+def test_invalid_entry_configuration_is_rejected(values):
+    with pytest.raises(ValidationError):
+        BotBase(pair="XBTUSDTM", market_type=MarketType.FUTURES, **values)

{pybinbot-2.1.0 → pybinbot-2.1.2}/tests/test_futures_place_order.py

@@ -10,6 +10,7 @@ from unittest.mock import MagicMock, patch
 
 import pytest
 from kucoin_universal_sdk.generate.futures.order.model_add_order_req import AddOrderReq
+
 from pybinbot import KucoinFutures, OrderStatus, OrderType
 
 
@@ -113,3 +114,115 @@ def test_place_futures_order_marks_zero_fill_done_order_as_canceled_not_filled()
 
     assert result.status == OrderStatus.CANCELED
     assert result.qty == 0
+
+
+@pytest.mark.parametrize("order_type", [OrderType.limit, OrderType.market])
+@pytest.mark.parametrize(
+    "side,stop,reduce_only",
+    [
+        pytest.param("sell", "down", True, id="long-stop-loss"),
+        pytest.param("buy", "up", True, id="short-stop-loss"),
+        pytest.param("sell", "up", True, id="long-take-profit"),
+        pytest.param("buy", "down", True, id="short-take-profit"),
+        pytest.param("buy", "up", False, id="conditional-long-entry"),
+        pytest.param("sell", "down", False, id="conditional-short-entry"),
+    ],
+)
+def test_all_conditional_order_paths_default_to_last_trade(
+    order_type, side, stop, reduce_only
+):
+    f = _make_futures()
+    f.futures_order_api.add_order.return_value = types.SimpleNamespace(
+        order_id="conditional-order"
+    )
+    f.retrieve_order = lambda oid: types.SimpleNamespace(
+        status=types.SimpleNamespace(value="open"),
+        filled_size="0",
+        avg_deal_price="0",
+        created_at=1000000,
+        type=types.SimpleNamespace(value=order_type.value.lower()),
+        time_in_force="GTC",
+        side=types.SimpleNamespace(value=side),
+    )
+
+    with patch("pybinbot.apis.kucoin.futures.sleep"):
+        result = f.place_futures_order(
+            symbol="XBTUSDTM",
+            side=AddOrderReq.SideEnum(side),
+            size=8,
+            leverage=3,
+            order_type=order_type,
+            price=97.5 if order_type == OrderType.limit else None,
+            stop=AddOrderReq.StopEnum(stop),
+            stop_price=98,
+            reduce_only=reduce_only,
+            client_oid="conditional-oid",
+        )
+
+    f.futures_order_api.add_order.assert_called_once()
+    request = f.futures_order_api.add_order.call_args.args[0]
+    assert request.stop_price_type == AddOrderReq.StopPriceTypeEnum.TRADE_PRICE
+    assert request.stop_price == "98"
+    assert request.stop.value == stop
+    assert request.side.value == side
+    assert request.type.value == order_type.value.lower()
+    assert request.price == ("97.5" if order_type == OrderType.limit else None)
+    assert request.size == 8
+    assert request.leverage == 3
+    assert request.reduce_only is reduce_only
+    assert request.client_oid == "conditional-oid"
+    assert result.stop_price == 98
+    assert result.status == OrderStatus.NEW
+
+
+@pytest.mark.parametrize(
+    "trigger_type",
+    [
+        None,
+        AddOrderReq.StopPriceTypeEnum.MARK_PRICE,
+        AddOrderReq.StopPriceTypeEnum.INDEX_PRICE,
+    ],
+)
+def test_conditional_trigger_uses_last_trade_for_none_and_respects_explicit_types(
+    trigger_type,
+):
+    f = _make_futures()
+    f.futures_order_api.add_order.return_value = None
+
+    with pytest.raises(RuntimeError, match="not acknowledged"):
+        f.place_futures_order(
+            symbol="XBTUSDTM",
+            side=AddOrderReq.SideEnum.SELL,
+            size=8,
+            order_type=OrderType.market,
+            stop=AddOrderReq.StopEnum.DOWN,
+            stop_price=98,
+            stop_price_type=trigger_type,
+        )
+
+    request = f.futures_order_api.add_order.call_args.args[0]
+    assert request.stop_price_type == (
+        trigger_type
+        if trigger_type is not None
+        else AddOrderReq.StopPriceTypeEnum.TRADE_PRICE
+    )
+
+
+@pytest.mark.parametrize("order_type", [OrderType.limit, OrderType.market])
+def test_ordinary_orders_do_not_send_conditional_trigger_fields(order_type):
+    f = _make_futures()
+    f.futures_order_api.add_order.return_value = None
+
+    with pytest.raises(RuntimeError, match="not acknowledged"):
+        f.place_futures_order(
+            symbol="XBTUSDTM",
+            side=AddOrderReq.SideEnum.BUY,
+            size=8,
+            order_type=order_type,
+            price=100 if order_type == OrderType.limit else None,
+        )
+
+    request = f.futures_order_api.add_order.call_args.args[0]
+    assert request.stop is None
+    assert request.stop_price is None
+    assert request.stop_price_type is None

{pybinbot-2.1.0 → pybinbot-2.1.2}/tests/test_kucoin_api.py

@@ -1,4 +1,5 @@
 from types import SimpleNamespace
+from unittest.mock import Mock
 
 import pytest
 
@@ -27,6 +28,56 @@ def test_get_ticker_price_returns_float_when_price_is_available():
     assert api.get_ticker_price("BTC-USDT") == 12.34
 
 
+def test_futures_ticker_returns_last_trade_instead_of_spot_mark_or_book():
+    api = object.__new__(KucoinFutures)
+    ticker = Mock(
+        return_value=SimpleNamespace(
+            price="101.5", best_bid_price="101", best_ask_price="102"
+        )
+    )
+    api.futures_market_api = SimpleNamespace(
+        get_ticker=ticker, get_mark_price=Mock(return_value=100)
+    )
+    spot_ticker = Mock(return_value=SimpleNamespace(price="99"))
+    api.spot_api = SimpleNamespace(get_ticker=spot_ticker)
+
+    assert api.get_ticker_price("XBTUSDTM") == 101.5
+
+    ticker.assert_called_once()
+    assert ticker.call_args.args[0].symbol == "XBTUSDTM"
+    api.futures_market_api.get_mark_price.assert_not_called()
+    spot_ticker.assert_not_called()
+
+
+def test_futures_ticker_raises_clear_error_when_response_is_missing():
+    api = object.__new__(KucoinFutures)
+    api.futures_market_api = SimpleNamespace(get_ticker=Mock(return_value=None))
+
+    with pytest.raises(ValueError, match="KuCoin futures ticker returned no response"):
+        api.get_ticker_price("XBTUSDTM")
+
+
+def test_futures_ticker_raises_clear_error_when_price_is_missing():
+    api = object.__new__(KucoinFutures)
+    api.futures_market_api = SimpleNamespace(
+        get_ticker=Mock(return_value=SimpleNamespace(price=None))
+    )
+
+    with pytest.raises(ValueError, match="KuCoin futures ticker returned no price"):
+        api.get_ticker_price("XBTUSDTM")
+
+
+@pytest.mark.parametrize("price", ["0", "-1", "nan", "inf", "invalid"])
+def test_futures_ticker_rejects_invalid_last_trade_prices(price):
+    api = object.__new__(KucoinFutures)
+    api.futures_market_api = SimpleNamespace(
+        get_ticker=Mock(return_value=SimpleNamespace(price=price))
+    )
+
+    with pytest.raises(ValueError):
+        api.get_ticker_price("XBTUSDTM")
+
+
 def test_get_mark_price_raises_clear_error_when_value_is_missing():
     api = object.__new__(KucoinFutures)
     api.futures_market_api = SimpleNamespace(