Fix Binance Futures trailing stop market orders

Author: cjdsellers

RELEASES.md

@@ -18,6 +18,8 @@ None
 - Fixed DataFusion streaming backend mem usage (now constant mem usage) (#1693), thanks @twitu
 - Fixed `OrderBookDeltaDataWrangler` snapshot parsing (was not prepending a `CLEAR` action), thanks for reporting @VeraLyu
 - Fixed `Instrument.make_price` and `make_qty` when increments have a lower precision (was not rounding to the minimum increment)
+- Fixed `EMACrossTrailingStop` example strategy trailing stop logic (could submit multiple trailing stops on partial fills)
+- Fixed Binance `TRAILING_STOP_MARKET` orders (callback rounding was incorrect, was also not handling updates)
 - Fixed Interactive Brokers multiple gateway clients (incorrect port handling in factory) (#1702), thanks @dodofarm
 
 ---

docs/integrations/binance.md

@@ -56,18 +56,22 @@ E.g. for Binance Futures, the said instruments symbol is `BTCUSDT-PERP` within t
 
 ### Trailing stops
 
-Binance use the concept of an *activation price* for trailing stops ([see docs](https://www.binance.com/en-AU/support/faq/what-is-a-trailing-stop-order-360042299292)).
-To get trailing stop orders working for Binance we need to use the `trigger_price` value to set the *activation price*.
+Binance uses the concept of an activation price for trailing stops, as detailed in their [documentation](https://www.binance.com/en-AU/support/faq/what-is-a-trailing-stop-order-360042299292).
+This approach is somewhat unconventional. For trailing stop orders to function on Binance, the activation price can optionally be set using the `trigger_price` value.
 
-For `TRAILING_STOP_MARKET` orders to be submitted successfully, you must define the following:
-- Specify a `trailing_offet_type` of either `DEFAULT` or `BASIS_POINTS`
-- Specify the `trailing_offset` in basis points (% * 100) e.g. for a callback rate of 1% use 100
+Note that the activation price is **not** the same as the trigger/STOP price. Binance will always calculate the trigger price for the order based on the current market price and the callback rate provided by `trailing_offset`.
+The activated price is simply the price at which the order will begin trailing based on the callback rate.
+
+When submitting trailing stop orders from your strategy, you have two options:
+
+1. Use the `trigger_price` to manually set the activation price.
+2. Leave the `trigger_price` as `None`, making the trailing action immediately "active".
 
 You must also have at least *one* of the following:
 
 - The `trigger_price` for the order is set (this will act as the Binance *activation_price*)
-- You have subscribed to quote ticks for the instrument you're submitting the order for (used to infer activation price)
-- You have subscribed to trade ticks for the instrument you're submitting the order for (used to infer activation price)
+- (or) you have subscribed to quote ticks for the instrument you're submitting the order for (used to infer activation price)
+- (or) you have subscribed to trade ticks for the instrument you're submitting the order for (used to infer activation price)
 
 ## Configuration
 

examples/live/binance/binance_futures_testnet_ema_cross_with_trailing_stop.py

@@ -40,7 +40,7 @@
 # Configure the trading node
 config_node = TradingNodeConfig(
     trader_id=TraderId("TESTER-001"),
-    logging=LoggingConfig(log_level="INFO"),
+    logging=LoggingConfig(log_level="INFO", use_pyo3=True),
     exec_engine=LiveExecEngineConfig(
         reconciliation=True,
         reconciliation_lookback_mins=1440,
@@ -80,10 +80,11 @@
 node = TradingNode(config=config_node)
 
 # Configure your strategy
+symbol = "ETHUSDT-PERP"
 strat_config = EMACrossTrailingStopConfig(
-    instrument_id=InstrumentId.from_str("ETHUSDT-PERP.BINANCE"),
-    external_order_claims=[InstrumentId.from_str("ETHUSDT-PERP.BINANCE")],
-    bar_type=BarType.from_str("ETHUSDT-PERP.BINANCE-1-MINUTE-LAST-EXTERNAL"),
+    instrument_id=InstrumentId.from_str(f"{symbol}.BINANCE"),
+    external_order_claims=[InstrumentId.from_str(f"{symbol}.BINANCE")],
+    bar_type=BarType.from_str(f"{symbol}.BINANCE-1-MINUTE-LAST-EXTERNAL"),
     fast_ema_period=10,
     slow_ema_period=20,
     atr_period=20,

nautilus_trader/adapters/binance/common/constants.py

@@ -13,9 +13,13 @@
 #  limitations under the License.
 # -------------------------------------------------------------------------------------------------
 
+from decimal import Decimal
 from typing import Final
 
 from nautilus_trader.model.identifiers import Venue
 
 
 BINANCE_VENUE: Final[Venue] = Venue("BINANCE")
+
+BINANCE_MIN_CALLBACK_RATE: Final[Decimal] = Decimal("0.1")
+BINANCE_MAX_CALLBACK_RATE: Final[Decimal] = Decimal("10.0")

nautilus_trader/adapters/binance/common/enums.py

@@ -207,7 +207,7 @@ class BinanceTimeInForce(Enum):
     GTC = "GTC"
     IOC = "IOC"
     FOK = "FOK"
-    GTX = "GTX"  # FUTURES only, Good Till Crossing (Post Only)
+    GTX = "GTX"  # FUTURES only, Good-Till-Crossing (Post Only)
     GTD = "GTD"  # FUTURES only
     GTE_GTC = "GTE_GTC"  # Undocumented
 
@@ -312,6 +312,7 @@ class BinanceErrorCode(Enum):
     INVALID_PARAMETER = -1130
     INVALID_NEW_ORDER_RESP_TYPE = -1136
 
+    INVALID_CALLBACK_RATE = -2007
     NEW_ORDER_REJECTED = -2010
     CANCEL_REJECTED = -2011
     CANCEL_ALL_FAIL = -2012

nautilus_trader/adapters/binance/common/execution.py

@@ -18,6 +18,8 @@
 
 import pandas as pd
 
+from nautilus_trader.adapters.binance.common.constants import BINANCE_MAX_CALLBACK_RATE
+from nautilus_trader.adapters.binance.common.constants import BINANCE_MIN_CALLBACK_RATE
 from nautilus_trader.adapters.binance.common.constants import BINANCE_VENUE
 from nautilus_trader.adapters.binance.common.enums import BinanceAccountType
 from nautilus_trader.adapters.binance.common.enums import BinanceEnumParser
@@ -775,16 +777,28 @@ async def _submit_trailing_stop_market_order(self, order: TrailingStopMarketOrde
             )
             return
 
+        # Convert basis points to percentage rounded to 1 decimal place
+        callback_rate = Decimal(f"{order.trailing_offset / 100:.1f}")
+
+        if callback_rate < BINANCE_MIN_CALLBACK_RATE or callback_rate > BINANCE_MAX_CALLBACK_RATE:
+            self._log.error(
+                f"Cannot submit order: invalid `order.trailing_offset`, was "
+                f"{order.trailing_offset} {trailing_offset_type_to_str(order.trailing_offset_type)} "
+                f"rounded to {callback_rate}%, "
+                f"must in range [{BINANCE_MIN_CALLBACK_RATE}, {BINANCE_MAX_CALLBACK_RATE}]",
+            )
+            return
+
         # Ensure activation price
         activation_price: Price | None = order.trigger_price
         if not activation_price:
             quote = self._cache.quote_tick(order.instrument_id)
             trade = self._cache.trade_tick(order.instrument_id)
             if quote:
                 if order.side == OrderSide.BUY:
-                    activation_price = quote.ask_price
-                elif order.side == OrderSide.SELL:
                     activation_price = quote.bid_price
+                elif order.side == OrderSide.SELL:
+                    activation_price = quote.ask_price
             elif trade:
                 activation_price = trade.price
             else:
@@ -802,7 +816,7 @@ async def _submit_trailing_stop_market_order(self, order: TrailingStopMarketOrde
             good_till_date=self._determine_good_till_date(order, time_in_force),
             quantity=str(order.quantity),
             activation_price=str(activation_price),
-            callback_rate=str(order.trailing_offset / 100),
+            callback_rate=str(callback_rate),
             working_type=working_type,
             reduce_only=self._determine_reduce_only_str(order),
             new_client_order_id=order.client_order_id.value,

nautilus_trader/adapters/binance/futures/execution.py

@@ -14,6 +14,7 @@
 # -------------------------------------------------------------------------------------------------
 
 import asyncio
+import json
 from decimal import Decimal
 
 import msgspec
@@ -257,7 +258,7 @@ async def _batch_cancel_orders(self, command: BatchCancelOrders) -> None:
 
     def _handle_user_ws_message(self, raw: bytes) -> None:
         # TODO: Uncomment for development
-        # self._log.info(str(json.dumps(msgspec.json.decode(raw), indent=4)), color=LogColor.MAGENTA)
+        self._log.info(str(json.dumps(msgspec.json.decode(raw), indent=4)), color=LogColor.MAGENTA)
         wrapper = self._decoder_futures_user_msg_wrapper.decode(raw)
         if not wrapper.stream or not wrapper.data:
             # Control message response

nautilus_trader/adapters/binance/futures/schemas/user.py

@@ -35,6 +35,7 @@
 from nautilus_trader.model.enums import LiquiditySide
 from nautilus_trader.model.enums import OrderSide
 from nautilus_trader.model.enums import OrderStatus
+from nautilus_trader.model.enums import OrderType
 from nautilus_trader.model.enums import TrailingOffsetType
 from nautilus_trader.model.identifiers import AccountId
 from nautilus_trader.model.identifiers import ClientOrderId
@@ -279,6 +280,18 @@ def handle_order_trade_update(  # noqa: C901 (too complex)
         venue_order_id = VenueOrderId(str(self.i))
         instrument_id = exec_client._get_cached_instrument_id(self.s)
         strategy_id = exec_client._cache.strategy_id_for_order(client_order_id)
+
+        instrument = exec_client._instrument_provider.find(instrument_id=instrument_id)
+        if instrument is None:
+            raise ValueError(f"Cannot handle trade: instrument {instrument_id} not found")
+
+        price_precision = instrument.price_precision
+        size_precision = instrument.size_precision
+
+        order = exec_client._cache.order(client_order_id)
+        if not order:
+            exec_client._log.error(f"Cannot find order {client_order_id!r}")
+
         if strategy_id is None:
             report = self.parse_to_order_status_report(
                 account_id=exec_client.account_id,
@@ -291,6 +304,9 @@ def handle_order_trade_update(  # noqa: C901 (too complex)
             )
             exec_client._send_order_status_report(report)
         elif self.x == BinanceExecutionType.NEW:
+            if order.order_type == OrderType.TRAILING_STOP_MARKET and order.is_open:
+                return  # Already accepted: this is an update
+
             exec_client.generate_order_accepted(
                 strategy_id=strategy_id,
                 instrument_id=instrument_id,
@@ -299,10 +315,6 @@ def handle_order_trade_update(  # noqa: C901 (too complex)
                 ts_event=ts_event,
             )
         elif self.x == BinanceExecutionType.TRADE:
-            instrument = exec_client._instrument_provider.find(instrument_id=instrument_id)
-            if instrument is None:
-                raise ValueError(f"Cannot handle trade: instrument {instrument_id} not found")
-
             # Determine commission
             commission_asset: str | None = self.N
             commission_amount: str | None = self.n
@@ -325,8 +337,8 @@ def handle_order_trade_update(  # noqa: C901 (too complex)
                 trade_id=TradeId(str(self.t)),  # Trade ID
                 order_side=exec_client._enum_parser.parse_binance_order_side(self.S),
                 order_type=exec_client._enum_parser.parse_binance_order_type(self.o),
-                last_qty=Quantity(float(self.l), instrument.size_precision),
-                last_px=Price(float(self.L), instrument.price_precision),
+                last_qty=Quantity(float(self.l), size_precision),
+                last_px=Price(float(self.L), price_precision),
                 quote_currency=instrument.quote_currency,
                 commission=commission,
                 liquidity_side=LiquiditySide.MAKER if self.m else LiquiditySide.TAKER,
@@ -343,28 +355,43 @@ def handle_order_trade_update(  # noqa: C901 (too complex)
                 ts_event=ts_event,
             )
         elif self.x == BinanceExecutionType.AMENDMENT:
-            instrument = exec_client._instrument_provider.find(instrument_id=instrument_id)
-            if instrument is None:
-                raise ValueError(f"Cannot handle amendment: instrument {instrument_id} not found")
-
             exec_client.generate_order_updated(
                 strategy_id=strategy_id,
                 instrument_id=instrument_id,
                 client_order_id=client_order_id,
                 venue_order_id=venue_order_id,
-                quantity=Quantity(float(self.q), instrument.size_precision),
-                price=Price(float(self.p), instrument.price_precision),
+                quantity=Quantity(float(self.q), size_precision),
+                price=Price(float(self.p), price_precision),
                 trigger_price=None,
                 ts_event=ts_event,
             )
         elif self.x == BinanceExecutionType.EXPIRED:
-            exec_client.generate_order_expired(
-                strategy_id=strategy_id,
-                instrument_id=instrument_id,
-                client_order_id=client_order_id,
-                venue_order_id=venue_order_id,
-                ts_event=ts_event,
-            )
+            instrument = exec_client._instrument_provider.find(instrument_id=instrument_id)
+            if instrument is None:
+                raise ValueError(f"Cannot handle amendment: instrument {instrument_id} not found")
+
+            price_precision = instrument.price_precision
+            size_precision = instrument.size_precision
+
+            if order.order_type == OrderType.TRAILING_STOP_MARKET:
+                exec_client.generate_order_updated(
+                    strategy_id=strategy_id,
+                    instrument_id=instrument_id,
+                    client_order_id=client_order_id,
+                    venue_order_id=venue_order_id,
+                    quantity=Quantity(float(self.q), size_precision),
+                    price=Price(float(self.p), price_precision),
+                    trigger_price=(Price(float(self.sp), price_precision) if self.sp else None),
+                    ts_event=ts_event,
+                )
+            else:
+                exec_client.generate_order_expired(
+                    strategy_id=strategy_id,
+                    instrument_id=instrument_id,
+                    client_order_id=client_order_id,
+                    venue_order_id=venue_order_id,
+                    ts_event=ts_event,
+                )
         else:
             # Event not handled
             exec_client._log.warning(f"Received unhandled {self}")

nautilus_trader/adapters/binance/http/client.py

@@ -25,6 +25,7 @@
 from nautilus_trader.adapters.binance.http.error import BinanceServerError
 from nautilus_trader.common.component import LiveClock
 from nautilus_trader.common.component import Logger
+from nautilus_trader.common.enums import LogColor
 from nautilus_trader.core.nautilus_pyo3 import HttpClient
 from nautilus_trader.core.nautilus_pyo3 import HttpMethod
 from nautilus_trader.core.nautilus_pyo3 import HttpResponse
@@ -151,6 +152,8 @@ async def send_request(
             url_path += "?" + urllib.parse.urlencode(payload)
             payload = None  # Don't send payload in the body
 
+        self._log.debug(f"{url_path} {payload}", LogColor.MAGENTA)
+
         response: HttpResponse = await self._client.request(
             http_method,
             url=self._base_url + url_path,

nautilus_trader/examples/strategies/ema_cross_trailing_stop.py

@@ -366,6 +366,8 @@ def on_event(self, event: Event) -> None:
             if self.trailing_stop and event.client_order_id == self.trailing_stop.client_order_id:
                 self.trailing_stop = None
         elif isinstance(event, PositionOpened | PositionChanged):
+            if self.trailing_stop:
+                return  # Already a trailing stop
             if self.entry and event.opening_order_id == self.entry.client_order_id:
                 if event.entry == OrderSide.BUY:
                     self.position_id = event.position_id