# artifacts/exchange/bybit_exchange.yaml

source_file: exch_live/bybit.py
schema_version: v1.1

factual_summary: >
  Implements the exchange integration for the Bybit exchange, supporting
  authenticated HTTP and websocket connectivity for order, trade, position,
  and instrument data. This module manages exchange state tracking, order
  lifecycle mapping, rate limit observability, and synchronization of execution
  and position information with the trading system.

methods:
  - name: gen_signature
    signature: "(param_str: str) -> str"
    description: >
      Generates an HMAC SHA256 signature for authenticated API requests using
      exchange credentials.

  - name: parse_and_print_rate_limiting_data
    signature: "(d: dict) -> None"
    description: >
      Parses and logs rate limit usage information provided by the exchange.

  - name: __init__
    signature: "(trader, exchName, mode) -> None"
    description: >
      Initializes the Bybit exchange instance, configures operational mode,
      prepares websocket endpoints, and initializes internal state tracking.

  - name: up
    signature: "() -> None"
    description: >
      Establishes authenticated connections to order and trade websockets and
      handles exchange authentication responses.

  - name: run
    signature: "() -> None"
    description: >
      Executes the main asynchronous processing loop, monitoring websocket
      messages and handling order updates, executions, and cancellations.

  - name: send_auth
    signature: "(ws) -> None"
    description: >
      Sends authentication messages to a websocket connection to authorize
      private data access.

  - name: set_up
    signature: "(component: str) -> None"
    description: >
      Marks a specific exchange subsystem as operational.

  - name: all_up
    signature: "() -> bool"
    description: >
      Returns whether all exchange subsystems are fully initialized and ready.

  - name: update_pos_for_pos_entry_line
    signature: "(posEntry: dict) -> None"
    description: >
      Updates internal position state using position entry data received from
      the exchange.

interpretive_summary: >
  Serves as the execution-layer adapter for the Bybit exchange, encapsulating
  all exchange-specific authentication, websocket coordination, and order and
  position state management. This module deliberately isolates Bybit protocol
  details from strategy and decision logic, enabling consistent multi-exchange
  execution while maintaining clear readiness and lifecycle semantics.

invariants:
  - Exchange subsystems must be fully initialized before trading operations proceed
  - Exchange order identifiers are consistently mapped to internal order IDs
  - Position state reflects the latest exchange-provided execution data
  - Authentication is required before processing private websocket messages

tags:
  domain:
    - exchange_integration
    - order_execution
  trading_function:
    - order_execution
    - position_management
  strategy_layer:
    - execution
  system_layer:
    - engine
  intent:
    - abstraction
    - isolation
    - observability
    - fault_tolerance
  data_type:
    - orders
    - positions
    - configs
  risk:
    - capital_loss
    - latency
    - exchange_ban
    - security
  maturity:
    - production

provenance:
  generated_at: 2026-02-02
  generated_by: manual_from_docs
  confidence_score: 0.77