Exchange Integrations
Relevant source files
The following files were used as context for generating this wiki page:
Exchange Integrations in the hyperdrive library facilitate the connection between quantitative research models and live trading execution. This module specifically manages the interaction with external cryptocurrency and financial exchanges to perform market operations based on generated signals.
The primary focus of this system is the execution of orders, balance management, and the translation of abstract trading signals into concrete API calls. Currently, the library provides a robust integration for the Binance exchange, supporting both production and testnet environments.
Sources: README.md:14-17, hyperdrive/Exchange.py:1-10
Architecture and Components
The exchange integration is designed to be modular, allowing for different exchange providers to be implemented. The core of the system resides in classes that wrap exchange-specific SDKs (like python-binance) to provide a consistent interface for the hyperdrive ecosystem.
Key Classes and Structures
| Component | Description |
|---|---|
Binance | The primary class for interacting with Binance.US. Handles authentication, balance retrieval, and order placement. |
MarketData | Used alongside exchanges to provide symbol paths and data persistence for order history. |
Constants (C) | Provides global configuration, including environment-specific toggles like C.TEST. |
Sources: hyperdrive/Exchange.py:6, scripts/execute_order.py:10-14, test/test_Exchange.py:6-10
Order Execution Flow
The flow of an order begins with a signal generated from historical analysis or live market data. This signal determines the "side" (BUY or SELL) of the trade. The exchange component then calculates the necessary quantity based on account balances and executes the order.
Sources: scripts/execute_order.py:17-36
Order Management
The integration handles complex logic for market orders, including the conversion of "spend ratios" into actual asset quantities.
Order Logic and Parameters
The order method within the Binance class is the central point for execution. It requires a base asset, a quote asset, and a side. It supports a spend_ratio which represents the percentage of the available balance to use for the trade.
- Authentication: Sensitive credentials (API Keys and Secrets) are loaded from environment variables (e.g.,
os.environ['BINANCE']). - Safety Features: The system supports a
testnetmode and atestparameter in the order method to prevent accidental live trades during development.
Sources: hyperdrive/Exchange.py:11-30, test/test_Exchange.py:15-18, README.md:175-185
Sequence of Order Execution
The following diagram illustrates the interaction between the script, the Binance integration, and the external API.
Data Persistence
After an order is successfully executed, the system captures the response data and persists it for auditing and future backtesting verification.
Order Response Schema
The system normalizes the JSON response from the exchange into a flat structure suitable for CSV storage using pd.json_normalize. Key fields captured include:
| Field | Description |
|---|---|
symbol | The pair traded (e.g., BTCUSD). |
orderId | The unique identifier provided by the exchange. |
status | The state of the order (e.g., FILLED). |
executedQty | The actual amount of the base asset bought or sold. |
cummulativeQuoteQty | The total amount of the quote asset spent/received. |
transactTime | The timestamp of the transaction. |
Sources: test/test_Exchange.py:21-28, scripts/execute_order.py:30-35
# Implementation of order logging in scripts/execute_order.py
order = bn.order(base, quote, 'BUY' if signal else 'SELL', spend_ratio, C.TEST)
order_df = pd.json_normalize(order)
yesterday = (datetime.utcnow().date() - timedelta(days=1)).strftime(C.DATE_FMT)
order_df[C.TIME] = [yesterday]
orders = md.reader.update_df(orders_path, order_df, C.TIME, C.DATE_FMT)
md.writer.update_csv(orders_path, orders)
Sources: scripts/execute_order.py:27-36
Conclusion
The Exchange Integrations module provides a streamlined bridge between algorithmic signals and market execution. By abstracting the complexities of API authentication, balance calculation, and order formatting, it allows the rest of the library to focus on quantitative research while ensuring that trades are executed reliably and logged for future analysis.
Summary: The module currently prioritizes Binance.US and utilizes environment-based configuration for secure and flexible operation across production and testing environments.
Sources: README.md:175-180, hyperdrive/Exchange.py:6-10