DOCSEARCHbyAlgolia
Submit Docs

NexusTrader

repository·main·Indexed 20 days ago

https://github.com/quantweb3-com/nexustrader

An execution reliability layer for live trading systems designed for deterministic order execution and state synchronization. It supports major crypto exchanges (Binance, Bybit, OKX, Bitget, HyperLiquid) and TradFi via Bybit MT5 on Windows. Key features include idempotent orders, auto-recovery from WebSocket disconnects, and an MCP-compatible interface for AI agents. The system includes a core API with components like OrderManagementSystem, ExecutionManagementSystem, and a MessageBus for in-process communication.

Tokens
66.5K
Snippets
175
Records
267
Agent score
68%

What's inside nexustrader

  1. Introduction to NexusTrader

    main

    NexusTrader is an open-source trading framework designed for execution reliability in live trading systems. It is specifically built to handle the uncertainties of exchange connectivity, such as delayed acknowledgements, retries, and reconnections.

    Core Reliability Features

    • Deterministic Order Execution: Tracks WebSocket order paths until an ACK is received. If an ACK timeout occurs, the system can trigger a REST confirmation to resolve uncertainty.
    • Idempotent Submissions: Uses client_oid and idempotency_key to prevent duplicate order creation during retries.
    • Reconnect Reconciliation: Automatically resyncs balances, positions, and open orders after a private WebSocket reconnection, emitting a reconciliation diff to the strategy layer.
    • Observable State: Provides explicit tracking of pending ACK states and publishes lifecycle events for failed orders.

  2. Data schemas for Bybit API and WebSocket messages

    main
    The nexustrader.exchange.bybit.schema module provides the formal data structures used to parse and interact with Bybit API responses and WebSocket messages. It categorizes schemas into Market Data, Order Related, Position Related, WebSocket Messages, and Balance Related structures. Use these classes to ensure type safety and correct field access when consuming data from the Bybit exchange integration.

  4. Manage tasks, events, and rate limits with nexustrader.core.entity

    main

    The nexustrader.core.entity module provides core primitives for system orchestration, including:

    • RateLimit: For controlling the frequency of operations.
    • TaskManager: For managing execution tasks.
    • ZeroMQSignalRecv: For receiving signals via ZeroMQ.
    • DataReady: For ensuring data availability before strategy execution.

  5. What is NexusTrader's execution reliability layer?

    main

    NexusTrader acts as an execution reliability layer between your trading strategy and exchange APIs. It is designed to maintain correctness during network jitter, WebSocket disconnects, and exchange-side uncertainty.

    Key reliability features include:

    • Deterministic Order Execution: Tracks WebSocket orders until ACK; if an ACK timeout occurs, it triggers a REST confirmation before marking the request as failed.
    • Idempotent Orders: Uses client_oid and idempotency_key to prevent duplicate orders during retries.
    • Auto-Recovery: Automatically resyncs balances, positions, and open orders after a private WebSocket reconnection, emitting a diff to the strategy.
    • Failure Differentiation: Distinguishes between WS send failures, ACK timeouts, and explicit rejections.

  6. Understand Order Linkage (OID vs EID)

    main

    NexusTrader maintains a mapping between internal system identifiers and external exchange identifiers to manage order lifecycles.

    Order Creation

    When an order is first created within the system, it enters the INITIALIZED status and is assigned an OID (Order ID). This is the internal identifier used by NexusTrader. Once the order is successfully submitted to an exchange, the exchange returns an EID (Exchange Order ID), which is then stored alongside the order to link the two entities.

    If the submission to the exchange fails, the order status is set to FAILED and no EID is associated.

    Order Cancellation

    To cancel an order, you do not need to know the exchange's ID. Instead, you use the internal OID when calling the cancel_order method in the Strategy class. NexusTrader uses this OID to look up the corresponding EID and automatically submits the cancellation request to the exchange.

    # To cancel an order, use the internal Order ID (OID)
strategy.cancel_order(oid="your_internal_order_id")

  7. Concurrency considerations for Web Callbacks

    main

    When implementing web callbacks, keep the following architectural constraints in mind:

    1. Non-blocking execution: The web server runs in a background thread and does not block the main trading event loop.
    2. Separate Event Loops: Endpoint handlers are async and run inside the web server's own event loop.
    3. Avoid direct awaits: Do not directly await coroutines from the main trading loop inside your web endpoint handlers, as they belong to different event loops.

  8. NexusTrader performance and technology stack

    main

    NexusTrader is optimized for low-latency and high-throughput live trading using the following technologies:

    • Event Loop: Uses uvloop for performance up to 2-4x faster than standard asyncio.
    • WebSocket Framework: Built on picows (a Cython-based library) for high-speed communication.
    • Data Serialization: Uses msgspec (specifically msgspec.Struct) for highly efficient serialization/deserialization, outperforming orjson and ujson.
    • Order Management: Utilizes asyncio.Queue for scalable processing of high order volumes.
    • Logging: Uses loguru for lightweight, predictable, time-based log rotation.

  9. Use the MessageBus for pub/sub and point-to-point routing

    main

    The MessageBus is an in-process communication system that allows components (like connectors, EMS, OMS, and strategies) to interact without polling. It supports two distinct patterns:

    1. Topic (fan-out): One publisher can send messages to many subscribers. Use subscribe(topic, handler) and publish(topic, msg).
    2. Endpoint (point-to-point): Exactly one registered handler per endpoint. Use register(endpoint, handler) and send(endpoint, msg).

  10. Choose a Strategy Execution Mode

    main

    NexusTrader supports three modes of operation depending on your requirements:

    1. Event-Driven Mode

    Logic is executed in response to real-time market events. Methods like on_bookl1, on_trade, and on_kline are triggered immediately upon data updates.

    2. Timer Mode

    Logic is executed at specific intervals. Use the schedule method to define periodic execution (e.g., every 1 second).

    3. Custom Signal Mode

    Logic is executed based on custom signals. Implement on_custom_signal(self, signal: object) to trigger actions when external systems or custom logic emit a signal.

    # Timer Mode Example
class Demo2(Strategy):
    def __init__(self):
        super().__init__()
        self.schedule(self.algo, trigger="interval", seconds=1)

    def algo(self):
        # Runs every 1 second
        pass

# Custom Signal Mode Example
class Demo3(Strategy):
    def __init__(self):
        super().__init__()
        self.signal = True

    def on_custom_signal(self, signal: object):
        # Triggered by custom signals
        pass

  11. Handle Binance exchange errors in NexusTrader

    main

    When interacting with the Binance exchange via NexusTrader, errors are categorized into two main exception classes to help you distinguish between infrastructure issues and request-level issues:

    1. BinanceServerError: Use this to catch errors originating from the Binance server side (e.g., 5xx status codes, service outages, or maintenance). These are typically transient and may be suitable for retry logic.
    2. BinanceClientError: Use this to catch errors originating from your own requests (e.g., 4xx status codes, invalid parameters, authentication failures, or rate limiting). These usually require code changes or adjustments to your request parameters rather than simple retries.

  12. Understand Order Status Lifecycle

    main

    Orders transition through several states defined in the OrderStatus class, grouped into four categories:

    1. LOCAL (Created by user, not yet sent):
      • INITIALIZED: Order created via create_order or cancel_order.
      • FAILED: Creation failed.
      • CANCEL_FAILED: Cancellation failed.
    2. IN-FLOW (Sending to exchange, awaiting WS response):
      • PENDING: Pending on exchange.
      • CANCELING: Pending cancellation.
    3. OPEN (WS response received, order live on exchange):
      • ACCEPTED: Accepted by exchange.
      • PARTIALLY_FILLED: Partially filled.
    4. CLOSED (Order finished on exchange):
      • FILLED: Fully filled.
      • CANCELLED: Cancelled by user.
      • EXPIRED: Cancelled by the exchange.

    If an order enters FAILED or CANCEL_FAILED, inspect the order.reason field for the error description.