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

factual_summary: >
  Implements the exchange integration for the BTCC perpetual futures exchange.
  This module manages authentication, HTTP and websocket connectivity, order
  lifecycle handling, and synchronization of positions and execution state
  between the exchange and the trading system. It extends shared exchange
  behavior from a base exchange abstraction.

methods:
  - name: CustomAdapter.process
    signature: "(msg, kwargs) -> str"
    description: >
      Modifies log messages by applying a standardized prefix to improve
      identification of BTCC-related log output.

  - name: sympathToSymbol
    signature: "(sympath: str) -> str"
    description: >
      Converts BTCC-specific symbol path representations into standardized
      symbol identifiers used internally by the trading system.

  - name: volumesListToLeverage
    signature: "(vl: str) -> int"
    description: >
      Extracts leverage information from a volume list string provided by
      the exchange.

  - name: __init__
    signature: "(trader, exchName) -> None"
    description: >
      Initializes the BTCC exchange instance, sets up internal state tracking,
      and schedules asynchronous initialization tasks.

  - name: up
    signature: "() -> None"
    description: >
      Establishes authenticated websocket and HTTP sessions, initializes
      exchange state, retrieves position information, and synchronizes
      positions with the trader component.

  - name: run
    signature: "() -> None"
    description: >
      Coordinates asynchronous processing of websocket messages and queued
      tasks, ensuring proper handling once all exchange subsystems are ready.

  - name: send_order
    signature: "(instr, side, price, qty, isHedge=0) -> None"
    description: >
      Submits a new order to the exchange and tracks its lifecycle using
      exchange-provided order identifiers.

  - name: cancel_order
    signature: "(sym, eOid) -> None"
    description: >
      Cancels an existing order on the exchange using the exchange order ID.

interpretive_summary: >
  Serves as the concrete execution-layer integration for the BTCC exchange,
  encapsulating all exchange-specific protocols, state management, and
  authentication details. This module deliberately isolates exchange mechanics
  from trading strategy logic, allowing the broader system to interact with
  BTCC through a consistent interface while reducing coupling and operational
  risk across exchanges.

invariants:
  - Exchange connectivity must be fully established before order processing
  - Exchange order IDs are the source of truth for order lifecycle tracking
  - Internal state reflects readiness of user, trade, position, and instrument subsystems
  - Symbol normalization is applied consistently across all exchange interactions

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

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