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

factual_summary: >
  Provides asynchronous utilities for discovering available perpetual futures
  contracts, normalizing symbol representations, and streaming real-time order
  book depth and trade data from a futures exchange via REST and websocket
  interfaces. The module coordinates contract discovery, websocket subscription,
  message parsing, and queue-based data distribution.

methods:
  - name: propose_contracts
    signature: "() -> list"
    description: >
      Retrieves metadata for all available perpetual futures contracts from the
      exchange, filters for actively trading instruments, normalizes symbol names,
      and returns the resulting contract list for downstream consumption.

  - name: get_depths
    signature: "(qDepth: asyncio.Queue, qOut: asyncio.Queue, sendRaw: bool) -> None"
    description: >
      Continuously fetches order book depth snapshots for symbols received via an
      asyncio queue and forwards either raw or processed depth data to an output
      queue depending on configuration.

  - name: run_ws
    signature: "(contract_data: list, qDepth: asyncio.Queue, qOut: asyncio.Queue, sendRaw: bool) -> None"
    description: >
      Establishes and maintains websocket subscriptions for depth and trade streams
      for a set of contracts, receives and parses streaming messages, and forwards
      structured data to downstream consumers with basic timeout handling.

  - name: get_normalized_symbols
    signature: "(cd: list) -> list"
    description: >
      Extracts and returns the standardized symbol identifiers from a list of
      contract metadata objects.

  - name: get_native_symbols
    signature: "(cd: list) -> list"
    description: >
      Extracts and returns the exchange-native symbol identifiers from a list of
      contract metadata objects.

  - name: price_precision_from_ticksize
    signature: "(ts: str) -> int"
    description: >
      Derives the price precision implied by a tick size representation.

  - name: get_price_precision_map
    signature: "(cd: list) -> dict"
    description: >
      Builds a mapping from symbol to price precision based on exchange-provided
      price filter metadata.

  - name: get_min_qty_map
    signature: "(cd: list) -> dict"
    description: >
      Builds a mapping from symbol to minimum tradable quantity using exchange
      contract metadata.

  - name: main
    signature: "(runWriter: bool, contracts: list, args) -> None"
    description: >
      Orchestrates contract selection, data stream initialization, and optional
      downstream writing or processing behavior based on runtime configuration.

interpretive_summary: >
  Acts as a market data ingestion and normalization layer for perpetual futures
  trading, abstracting away exchange-specific REST and websocket mechanics.
  This module is intentionally focused on data acquisition and standardization,
  avoiding any trading or decision logic so that downstream components can rely
  on consistent, exchange-agnostic market data streams.

invariants:
  - Only actively trading perpetual contracts are streamed
  - Symbol normalization is applied consistently across all downstream consumers
  - Market data is distributed via asynchronous queues to avoid tight coupling
  - Websocket reconnection logic preserves the original contract set

tags:
  domain:
    - market_data
    - exchange_integration
  trading_function:
    - data_ingest
    - feature_engineering
  strategy_layer:
    - signal
  system_layer:
    - worker
  intent:
    - abstraction
    - isolation
    - observability
  data_type:
    - raw_market_ticks
    - aggregated_candles
  risk:
    - latency
    - data_corruption
  maturity:
    - production

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