diff --git a/artifacts/exchanges/base_exchange.yaml b/artifacts/exchanges/base_exchange.yaml index e69de29..2458ef3 100644 --- a/artifacts/exchanges/base_exchange.yaml +++ b/artifacts/exchanges/base_exchange.yaml @@ -0,0 +1,65 @@ +source_file: exch_live/__init__.py +schema_version: v1.1 + +factual_summary: > + Defines shared utilities and base behavior for exchange integrations, + including standardized order string formatting and basic exchange + health/state tracking used across concrete exchange implementations. + +methods: + - name: order_str + signature: "(inst, order_dict, eOid) -> str" + description: > + Formats a human-readable string representation of an order, including + side, quantity, symbol, price, exchange name, and external order ID. + + - name: all_up + signature: "() -> bool" + description: > + Returns whether all tracked exchange subsystems are currently marked + as operational. + + - name: set_up + signature: "(kind) -> None" + description: > + Marks a specific exchange subsystem as operational and logs the updated + exchange state, including any remaining subsystems that are not yet up. + +interpretive_summary: > + Provides a minimal base abstraction for exchange integrations, centralizing + shared concerns such as operational state tracking and consistent logging. + This base class deliberately avoids order placement or strategy logic, + serving instead as a foundation that concrete exchange implementations + can extend while preserving uniform health semantics and observability. + +invariants: + - Exchange operational state is represented consistently via string values + - An exchange is considered fully operational only when all subsystems are up + - Logging reflects partial readiness when subsystems are still initializing + +tags: + domain: + - exchange_integration + - monitoring + trading_function: + - order_execution + strategy_layer: + - execution + system_layer: + - engine + intent: + - abstraction + - observability + data_type: + - orders + - configs + risk: + - latency + - data_corruption + maturity: + - production + +provenance: + generated_at: 2026-02-02 + generated_by: llm_assisted + confidence_score: 0.70 diff --git a/artifacts/exchanges/binance.yaml b/artifacts/exchanges/binance.yaml index e69de29..8785dc6 100644 --- a/artifacts/exchanges/binance.yaml +++ b/artifacts/exchanges/binance.yaml @@ -0,0 +1,108 @@ +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 diff --git a/artifacts/exchanges/btcc.yaml b/artifacts/exchanges/btcc.yaml index e69de29..4b944b1 100644 --- a/artifacts/exchanges/btcc.yaml +++ b/artifacts/exchanges/btcc.yaml @@ -0,0 +1,104 @@ +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 diff --git a/artifacts/exchanges/bullish.yaml b/artifacts/exchanges/bullish.yaml index e69de29..64b6da3 100644 --- a/artifacts/exchanges/bullish.yaml +++ b/artifacts/exchanges/bullish.yaml @@ -0,0 +1,92 @@ +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 diff --git a/artifacts/exchanges/bybit.yaml b/artifacts/exchanges/bybit.yaml index e69de29..c3441b4 100644 --- a/artifacts/exchanges/bybit.yaml +++ b/artifacts/exchanges/bybit.yaml @@ -0,0 +1,109 @@ +# 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 diff --git a/artifacts/exchanges/mexc.yaml b/artifacts/exchanges/mexc.yaml index e69de29..8200f48 100644 --- a/artifacts/exchanges/mexc.yaml +++ b/artifacts/exchanges/mexc.yaml @@ -0,0 +1,94 @@ +# artifacts/exchange/mexc_exchange.yaml + +source_file: exchange/mexc.py +schema_version: v1.1 + +factual_summary: > + Implements the exchange integration for the MEXC exchange, providing + authenticated REST and websocket connectivity for order execution and + exchange state monitoring. This module manages request signing, connection + setup, instrument discovery, and asynchronous processing of exchange events + using a shared base exchange abstraction. + +methods: + - name: sign_rest + signature: "(key, obj) -> MexcSignature" + description: > + Generates a REST API signature for authenticated requests by serializing + request data and producing a signed representation. + + - name: sign_ws + signature: "() -> MexcSignature" + description: > + Generates a signature required for authenticated websocket connections + to the exchange. + + - name: headers_for_sign + signature: "(s: MexcSignature) -> dict" + description: > + Constructs HTTP headers required for authenticated REST requests using + a previously generated signature. + + - name: __init__ + signature: "(trader, exchName) -> None" + description: > + Initializes the MEXC exchange instance, configures internal state tracking, + and starts background tasks required for exchange interaction. + + - name: up + signature: "() -> None" + description: > + Establishes authenticated websocket and HTTP connections, retrieves + instrument information, and initializes exchange readiness state. + + - name: run + signature: "() -> None" + description: > + Monitors websocket streams and asynchronous task queues, processes + incoming exchange events, and logs relevant operational information. + +interpretive_summary: > + Serves as the execution-layer adapter for the MEXC exchange, encapsulating + all exchange-specific authentication, request signing, and connectivity + logic. This module isolates MEXC protocol and security requirements from + trading strategy and decision-making components, enabling consistent and + safer multi-exchange execution within the trading system. + +invariants: + - Exchange authentication must be completed before private data is processed + - Request signing is required for all authenticated REST and websocket interactions + - Instrument information is fetched before the exchange is considered ready + - Exchange readiness state reflects user, trade, position, and instrument subsystems + +tags: + domain: + - exchange_integration + - order_execution + trading_function: + - order_execution + - position_management + strategy_layer: + - execution + system_layer: + - engine + intent: + - abstraction + - isolation + - security + - 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.77