Order Execution Guide
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Order Execution system within hyperdrive provides a standardized interface for interacting with cryptocurrency exchanges, specifically Binance. It bridges the gap between quantitative research signals and live market transactions, allowing for automated trading based on generated signals.
This module handles the logic for connecting to exchanges, calculating order quantities based on available balances and risk parameters (spend ratios), and recording executed orders for future analysis.
Sources: README.md:144-148, scripts/execute_order.py:1-12
Core Components
Binance Exchange Interface
The Binance class serves as the primary gateway for order execution. It utilizes the python-binance client to interact with both the live exchange and the Binance Testnet.
- Initialization: Requires API keys and secrets, which can be passed directly or loaded from environment variables (
BINANCE_KEY,BINANCE_SECRET,BINANCE_TESTNET_KEY,BINANCE_TESTNET_SECRET). - Order Logic: Supports market orders for both buying and selling. It automatically handles asset precision, lot size filters, and fee deductions.
Sources: hyperdrive/Exchange.py:8-25, test/test_Exchange.py:7-12
Order Logic and Parameter Calculation
The execution flow involves several steps to ensure compliance with exchange constraints:
- Fee Management: A default fee of 0.1% is subtracted from the
spend_ratioto prevent order failures due to insufficient funds. - Asset Information: The system fetches
symbol_infoto retrieveLOT_SIZE(for sells) andquoteAssetPrecision(for buys). - Balance Retrieval: It checks the "free" balance of the base asset (for sells) or quote asset (for buys).
- Quantity Formatting:
- BUY: Quantity is formatted as
quoteOrderQtybased on the quote asset precision. - SELL: Quantity is rounded using
round_step_sizebased on the exchange'sstepSize.
- BUY: Quantity is formatted as
Sources: hyperdrive/Exchange.py:27-66
Data Flow for Automated Execution
The production script execute_order.py demonstrates the typical workflow for automated trading. It compares the two most recent signals; if a signal change is detected (e.g., from 0 to 1), an order is triggered.
The diagram above shows the logic used to determine if a market move is required based on model output.
Sources: scripts/execute_order.py:14-41
Configuration and Constants
Environment Variables
| Variable | Description |
|---|---|
BINANCE_KEY | Production API Key |
BINANCE_SECRET | Production API Secret |
BINANCE_TESTNET_KEY | Testnet API Key |
BINANCE_TESTNET_SECRET | Testnet API Secret |
TEST | Boolean flag to enable/disable Testnet mode |
Sources: hyperdrive/Exchange.py:12-23, hyperdrive/Constants.py:15-18
Path Management
The PathFinder class provides standardized paths for order-related data storage:
- Signals Path:
models/latest/signals.csv - Orders Path:
models/latest/orders.csv
Sources: hyperdrive/Constants.py:195-207
Implementation Example: Order Execution
The following sequence diagram illustrates the internal interaction within the Binance.order method.
This diagram outlines the synchronous request-response cycle required to safely execute a trade on the exchange.
Sources: hyperdrive/Exchange.py:27-68
Conclusion
Order execution in hyperdrive is designed to be a reliable final step in the algorithmic trading pipeline. By abstracting the complexities of Binance's API—such as precision handling, step sizes, and fee calculations—it allows developers to focus on strategy development while ensuring that trades are executed accurately and logged for auditing.