[Bybit] Add public all-liquidation custom data subscription
Feature Request
- I've searched existing issues and discussions to avoid duplicates.
Problem statement
The Bybit adapter does not currently expose Bybit's public all-liquidations WebSocket stream as subscribable custom data.
Bybit V5 publishes all liquidations for a symbol through the public topic allLiquidation.{symbol} for linear and inverse derivatives. The stream is public, can batch multiple events in one message, and provides the event timestamp, symbol, liquidated position side, executed size, and bankruptcy price.
Without adapter support, strategies cannot consume Bybit liquidation events through NautilusTrader's standard subscribe_data(DataType(...)) workflow and must maintain a separate WebSocket connection and synchronization path.
Proposed solution
Add a Bybit adapter custom data type, tentatively named BybitFuturesLiquidation, and support subscribing and unsubscribing to allLiquidation.{symbol} from the Bybit market data client.
Suggested event fields:
instrument_idside(the liquidated position side, preserving Bybit's documented semantics)price(bankruptcy price)quantity(executed size)ts_event(Bybit fieldT)ts_init
Implementation considerations:
- Support both linear and inverse public WebSocket clients.
- Reject unsupported Spot and Option instruments with a clear error.
- Decode every element in the batched
dataarray, not only the first event. - Route symbols through the existing Bybit symbol/instrument mapping.
- Keep the event timestamp (
T) distinct from the message generation timestamp (ts). - Register the type for Python/PyO3 and JSON serialization.
- Register Arrow serialization when the adapter's feature setup permits it, so events can be written to and queried from
ParquetDataCatalograther than requiring a later persistence-only change. - Document that the feed contains the liquidation events published by Bybit and should not be treated as independently audited exchange-wide ground truth.
Example usage
from nautilus_trader.adapters.bybit import BybitFuturesLiquidation
from nautilus_trader.model import ClientId, DataType
self.subscribe_data(
data_type=DataType(
BybitFuturesLiquidation.__name__,
metadata={"instrument_id": "BTCUSDT-LINEAR.BYBIT"},
),
client_id=ClientId.from_str("BYBIT"),
)The exact instrument ID should follow the existing Bybit adapter conventions.
Acceptance criteria
BybitFuturesLiquidationis exposed from the Rust and Python adapter APIs.SubscribeCustomDataandUnsubscribeCustomDatasubscribe/unsubscribeallLiquidation.{symbol}on the correct linear or inverse public WebSocket client.- Batched messages emit one custom data event per liquidation.
- Parsing tests cover side, bankruptcy price, quantity, symbol mapping,
T, and multiple events in one payload. - Data-client tests cover subscribe, emit, unsubscribe, duplicate subscription behavior, and unsupported product types.
- JSON serialization round-trips successfully.
- Arrow/Parquet persistence round-trips successfully if included in the adapter feature configuration.
- The Bybit integration documentation includes subscription and handling examples plus exchange-feed limitations.
Alternatives considered
- Maintain an external Bybit WebSocket collector and inject generic custom data. This duplicates connection management, symbol mapping, timestamps, reconnection, and persistence logic already owned by the adapter.
- Infer liquidations from public trades. Public trades do not provide the same liquidation classification and bankruptcy-price semantics.
- Use account execution events. Those only describe activity related to the authenticated account, not the public market-wide liquidation stream.
Additional context
- Bybit documentation: https://bybit-exchange.github.io/docs/v5/websocket/public/all-liquidation
- Public topic:
allLiquidation.{symbol} - Example response fields:
T,s,S,v,p - Related precedent: Binance liquidation custom data support in #4094 and catalog persistence work in #4297.
Source: nautechsystems/nautilus_trader