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

factual_summary: >
  Implements the exchange integration for the Bullish exchange, providing
  authenticated access via HTTP and private WebSocket connections. This module
  manages authentication using HMAC and JWT tokens, establishes exchange
  connectivity, retrieves position data, and maintains readiness state for
  downstream trading operations.

methods:
  - name: __init__
    signature: "(trader, exchName) -> None"
    description: >
      Initializes the Bullish exchange instance, configures authentication
      parameters, and prepares internal state for asynchronous startup.

  - name: up
    signature: "() -> None"
    description: >
      Retrieves an authentication token, establishes a private WebSocket
      connection, and fetches initial position data from the exchange.

  - name: run
    signature: "() -> None"
    description: >
      Waits for all required exchange subsystems to be fully initialized before
      allowing further processing or interaction.

  - name: get_jwt_token
    signature: "() -> str"
    description: >
      Generates and retrieves a JWT token using HMAC-based authentication for
      authorized access to the Bullish API.

  - name: http_get
    signature: "(url: str) -> dict"
    description: >
      Performs an asynchronous HTTP GET request to the specified API endpoint
      and returns the parsed JSON response.

  - name: all_up
    signature: "() -> bool"
    description: >
      Determines whether all exchange components, including connectivity and
      position state, are fully initialized and operational.

interpretive_summary: >
  Serves as the execution-layer adapter for the Bullish exchange, encapsulating
  all exchange-specific authentication, connectivity, and state initialization
  logic. This module intentionally isolates Bullish protocol details from the
  rest of the trading system, enabling consistent exchange interaction while
  reducing coupling and simplifying multi-exchange support.

invariants:
  - Authentication must be completed successfully before private data access
  - Position data must be synchronized before the exchange is considered ready
  - Trading operations are gated on full exchange readiness
  - Exchange-specific credentials are handled exclusively within this module

tags:
  domain:
    - exchange_integration
    - order_execution
  trading_function:
    - order_execution
    - position_management
  strategy_layer:
    - execution
  system_layer:
    - engine
  intent:
    - abstraction
    - isolation
    - safety
    - observability
  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.76