Changelog

All notable changes to the ProjectX Python client will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

📦 Stable Production Release Notice

IMPORTANT: As of v3.1.1, this project has reached stable production status:

• Backward compatibility is now maintained between minor versions
• Deprecation warnings will be provided for at least 2 minor versions before removal
• Breaking changes will only occur in major version releases (4.0.0, 5.0.0, etc.)
• Migration guides will be provided for all breaking changes
• Semantic versioning (MAJOR.MINOR.PATCH) is strictly followed

[3.5.8] - 2025-09-02

🐛 Fixed

DateTime Parsing:

• Mixed Timestamp Formats: Fixed datetime parsing error when API returns mixed timestamp formats (with/without timezone)
• Robust Parsing: Implemented three-tier parsing approach to handle all timestamp variations:
  • With timezone offset: "2025-01-21T10:30:00-05:00"
  • With UTC Z suffix: "2025-01-21T15:30:00Z"
  • Without timezone (naive): "2025-01-21T10:30:00"
• Performance: Optimized with fast path for consistent data (95% of cases)
• Compatibility: Maintains backward compatibility with zero breaking changes

Test Improvements:

• Cache Performance Test: Fixed flaky test_cache_performance_benefits test that was failing due to microsecond timing measurements
• Test Robustness: Improved test to verify cache functionality rather than unreliable microsecond timing comparisons

📚 Documentation

Issue Tracking:

• Created detailed documentation of the datetime parsing issue and fix for future reference
• Added comprehensive testing notes for mixed timestamp format scenarios

[3.5.7] - 2025-02-02

🐛 Fixed

Order Placement:

• Decimal Serialization: Fixed JSON serialization error when placing orders with Decimal prices
• API Compatibility: Ensured all price values are properly converted to float for API requests
• Price Precision: Maintained internal Decimal precision while ensuring JSON compatibility

📚 Documentation

Examples:

• Quick Start Example: Fixed and verified the quick_start.py example in Documentation_Examples
• Order Placement: Ensured all documentation examples work with the fixed serialization

[3.5.6] - 2025-02-02

🐛 Fixed

Multi-Instrument Event System:

• Event Forwarding: Implemented event forwarding from instrument-specific EventBuses to suite-level EventBus
• InstrumentContext Methods: Added on(), once(), off(), and wait_for() methods that delegate to event_bus
• Event Propagation: Fixed broken event system that prevented mnq_context.wait_for(EventType.NEW_BAR) from working
• Multi-Instrument Support: Events now properly flow from individual instruments to the suite level

Bracket Order Improvements:

• Automatic Price Alignment: Changed validation from failing to auto-aligning prices to tick size
• Smart Adjustment: Orders with misaligned prices are now automatically corrected instead of rejected
• Better UX: Improved user experience by handling price alignment transparently

Example Scripts:

• Advanced Trading Examples: Fixed all 4 advanced trading examples with proper async/await patterns
• Real-time Streaming: Fixed bar data access in real-time streaming example
• OrderBook Methods: Corrected API usage with proper method names and parameters
• TypedDict Access: Fixed bracket notation for TypedDict field access

✅ Testing

• Test Suite Updates: Fixed 30 failing tests to match new correct behavior
• Event System Tests: Updated tests to verify event forwarding functionality
• Price Alignment Tests: Tests now verify automatic alignment instead of rejection
• InstrumentContext Tests: Added event_bus parameter to all test constructors

🔧 Changed

• OrderManager: Removed duplicate price alignment calls in place_order() method
• TradingSuite: Added _setup_event_forwarding() method for event bus connectivity
• InstrumentContext: Now requires event_bus parameter in constructor

[3.5.5] - 2025-01-21

✅ Testing

Comprehensive Sessions Module Testing:

• 163 Tests Passing: Complete test suite for sessions module with 88% coverage
• TDD Methodology: All tests validate expected behavior, not current implementation
• Bug Fixes: Fixed 11 critical bugs including DST transitions, naive datetime handling, and BREAK session detection
• Async Compliance: Made 4 sync functions private to maintain 100% async public API
• Complexity Reduction: Refactored 4 high-complexity functions using helper methods
• Type Safety: Fixed all MyPy type annotation errors with proper generic types

📝 Documentation

Sessions Documentation Overhaul:

• Complete Guide: Created comprehensive README.md for sessions module with working examples
• 5 Example Scripts: Created tested, working examples for all session functionality:
  • 01_basic_session_filtering.py - Basic filtering and market status
  • 02_session_statistics.py - Statistics and analytics
  • 03_session_indicators.py - Session-aware indicators
  • 04_session_comparison.py - RTH vs ETH comparison
  • 05_multi_instrument_sessions.py - Multi-instrument management
• API Accuracy: Fixed all incorrect method signatures and usage patterns
• DataFrame Safety: Added proper None checks and .is_empty() evaluations throughout

🐛 Fixed

Session Module Bugs:

• DST Transitions: Fixed edge cases during daylight saving time transitions
• Naive Datetime Handling: Properly handle naive datetimes with timezone awareness
• BREAK Session Detection: Fixed incorrect BREAK period detection logic
• DataFrame Evaluation: Fixed "ambiguous truth value" errors with proper boolean checks
• Correlation Calculation: Fixed Polars Series correlation method usage
• Type Conversions: Added safe type conversions with None checks

🔧 Changed

• Public API: Made sync utility functions private with underscore prefix to maintain async consistency
• Example Organization: Moved all session examples to dedicated examples/sessions/ directory
• Documentation Structure: Renamed guide to README.md for automatic GitHub display
• Error Handling: Improved error messages and added comprehensive troubleshooting section

[3.5.4] - 2025-01-31

🚀 Added

New Lorenz Formula Indicator:

• Chaos Theory Trading: Added Lorenz Formula indicator applying chaos theory to market analysis
• Dynamic Parameter Calculation: Automatically adjusts sigma (volatility), rho (trend), and beta (volume) based on market conditions
• Three-Component Output: Provides X (rate of change), Y (momentum), and Z (primary signal) components
• Market Regime Detection: Identifies stable, transitional, and chaotic market conditions
• Full Integration: TA-Lib style interface with both class-based and function-based APIs

📝 Documentation

Lorenz Indicator Documentation:

• Comprehensive Guide: Created detailed documentation at docs/indicators/lorenz.md with mathematical foundation
• Trading Strategies: Multiple signal generation strategies including Z-value momentum, crossovers, and divergence
• Parameter Tuning: Complete guidelines for adjusting dt, window, and volatility_scale parameters
• Integration Examples: Added to main indicators guide with practical usage examples
• Complete Trading System: Full example with position sizing, stops, and multi-indicator confluence

✅ Testing

Lorenz Indicator Tests:

• 15 Comprehensive Tests: Full test coverage following TDD principles
• Parameter Validation: Tests for custom parameters, window sizes, and time steps
• Chaos Properties: Verification of chaotic behavior and sensitivity to initial conditions
• Edge Cases: Handling of empty data, missing columns, and single-row inputs
• Integration: Example script (examples/33_lorenz_indicator.py) demonstrating all features

🔧 Changed

• Indicator Count: Updated from 58+ to 59+ indicators across all documentation
• Pattern Recognition: Enhanced with chaos theory-based market analysis

[3.5.3] - 2025-01-31

🐛 Fixed

Realtime Data Manager Fixes:

• Memory Management: Fixed mypy error with get_overflow_stats() method signatures in mmap overflow handling
• Type Safety: Resolved type checking issues in overflow statistics reporting
• Test Coverage: Achieved 100% test passing rate for realtime_data_manager module

📝 Documentation

Comprehensive Documentation Updates:

• Realtime Data Manager: Updated documentation to be 100% accurate with actual implementation
• Code Examples: Updated all examples to use modern TradingSuite API and component access patterns
• API Documentation: Fixed inconsistencies between documentation and actual code implementation
• Example Files: Modernized all example scripts to follow best practices and current API patterns

🔧 Changed

• API Consistency: Standardized component access patterns across all examples and documentation
• Documentation Accuracy: All documentation now precisely reflects the actual code behavior
• Example Modernization: All 25+ example files updated to use recommended patterns

✅ Testing

• Complete Test Coverage: All tests now passing for realtime_data_manager module
• Type Safety: Fixed all mypy type checking errors
• Test Reliability: Improved test stability and removed flaky tests

[3.5.2] - 2025-01-31

🐛 Fixed

Session Management Bug Fixes:

• Fixed AttributeError in Multi-Instrument Mode: Session management methods (set_session_type(), get_session_data(), get_session_statistics()) were incorrectly using _contexts instead of _instruments attribute, causing AttributeError in multi-instrument mode
• Implementation Bugs: Fixed actual implementation issues discovered during comprehensive testing (lines 1403, 1441, 1472 in trading_suite.py)
• Documentation Accuracy: Updated all documentation to correctly reflect the actual API implementation

📝 Documentation

Comprehensive Documentation Updates:

• API Documentation: Fixed all incorrect parameter usage examples (positional vs named arguments)
• Multi-Instrument Examples: Added comprehensive multi-instrument usage examples with correct syntax
• Container Protocol: Added complete documentation for dictionary-like access methods
• Deprecated Patterns: Clearly marked deprecated access patterns with migration guidance
• Example Files: Updated example files to use recommended API patterns

✅ Testing

Comprehensive Test Coverage:

• Added 51 new tests in test_trading_suite_complete_coverage.py for 100% coverage
• TradingSuiteConfig Methods: Full test coverage for all configuration generation methods
• Multi-Instrument Support: Tests for parallel context creation and cleanup
• Container Protocol: Complete testing of all dictionary-like methods
• Session Handling: Tests for both single and multi-instrument session management
• Edge Cases: Comprehensive error handling and edge case testing
• Backward Compatibility: Tests ensuring deprecated patterns still work with warnings

🔧 Changed

• Test-Driven Development: All tests now follow strict TDD principles - tests define expected behavior, not current implementation
• 88 total tests for TradingSuite module, all passing with proper expectations

[3.5.1] - 2025-01-30

🐛 Fixed

Critical Bug Fixes from TDD Test Suite:

• Context Manager Re-entry: Fixed issue where TradingSuite context manager couldn't be re-entered after exit
• ManagedTrade Attributes: Added missing property accessors for risk_manager, order_manager, and position_manager
• Event Loop Handling: Fixed get_stats_sync() to properly handle nested event loops using ThreadPoolExecutor
• Deprecation Warnings: Ensured consistent deprecation warnings when accessing components directly
• Config Validation: Fixed config file validation to check file extension before attempting file operations

Session Management Fixes:

• Fixed set_session_type(), get_session_data(), and get_session_statistics() to work correctly in multi-instrument mode
• Session methods now properly iterate over all instrument contexts when in multi-instrument mode
• Added fallback for single-instrument backward compatibility mode

Test Suite Fixes:

• Updated benchmark tests to use private attributes (_orders, _positions, etc.)
• Fixed integration tests to properly mock multi-instrument contexts
• Resolved statistics and event bus test failures caused by property-only access

🔧 Changed

• Component attributes (data, orders, positions, orderbook, risk_manager) are now stored as private attributes with deprecation warning properties
• Context manager always initializes when entering context, regardless of auto_connect setting

[3.5.0] - 2025-01-25

🚀 Major Feature: Multi-Instrument TradingSuite

Breaking Enhancement: TradingSuite now supports multiple instruments simultaneously, enabling complex multi-asset trading strategies and portfolio management.

✨ Added

Multi-Instrument TradingSuite Architecture:

• InstrumentContext: New dataclass encapsulating all managers for a single instrument
• Container Protocol: Dictionary-like access to instruments (suite["MNQ"], suite.keys(), suite.values())
• Parallel Creation: Efficient concurrent initialization of multiple instrument contexts
• Event Isolation: Events from different instruments are properly isolated
• Granular Resource Management: Proper cleanup of partially created resources during failures

Enhanced TradingSuite Interface:

# Multi-instrument setup
suite = await TradingSuite.create(
    instruments=["MNQ", "ES", "MGC"],
    timeframes=["1min", "5min"],
    enable_orderbook=True
)

# Access instruments like a dictionary
mnq_context = suite["MNQ"]
mnq_data = mnq_context.data
mnq_orders = mnq_context.orders

# Iterate over all instruments
for symbol, context in suite.items():
    bars = await context.data.get_data("5min")
    print(f"{symbol}: {len(bars)} bars")

Backward Compatibility Layer:

• Single-instrument API preserved with deprecation warnings
• Automatic migration path for existing code
• Clear error messages suggesting multi-instrument patterns

🔧 Technical Improvements

Robust Error Handling:

• Enhanced error propagation with helpful multi-instrument access suggestions
• Improved partial failure cleanup with asyncio.gather(..., return_exceptions=True)
• Resource management with async locks to prevent race conditions

Performance Optimizations:

• Parallel instrument context creation using asyncio.gather
• Efficient resource cleanup with granular context management
• Memory-optimized event system with proper isolation

Type Safety Enhancements:

• Complete type annotations for all new multi-instrument features
• Protocol definitions for container behavior
• Enhanced TypedDict definitions for instrument data

🧪 Comprehensive Testing

New Test Coverage:

• 200+ new tests for multi-instrument functionality
• Parallel creation and failure scenarios
• Event isolation and cross-instrument validation
• Backward compatibility and deprecation warning tests
• Edge cases and error propagation testing

Quality Assurance:

• 100% test pass rate across all environments
• Complete MyPy type checking compliance
• Full Ruff linting and formatting compliance
• Comprehensive CI/CD validation

📚 Documentation & Examples

New Documentation:

• Complete architectural documentation: docs/architecture/001_multi_instrument_suite_refactor.md
• Migration guide for existing single-instrument code
• Multi-instrument strategy examples and patterns

New Examples:

• examples/26_multi_instrument_trading.py: Comprehensive multi-instrument demo
• Real-world trading scenarios with multiple futures contracts
• Portfolio-level risk management examples

🔄 Migration Guide

From Single-Instrument (v3.4.x) to Multi-Instrument (v3.5.0):

# Old (v3.4.x) - Single instrument
suite = await TradingSuite.create("MNQ")
data = await suite.data.get_data("5min")  # Direct access

# New (v3.5.0) - Multi-instrument with backward compatibility
suite = await TradingSuite.create(["MNQ"])  # List notation
data = await suite.data.get_data("5min")    # Still works (with deprecation warning)

# Recommended (v3.5.0) - Explicit multi-instrument access
suite = await TradingSuite.create(["MNQ", "ES"])
mnq_data = await suite["MNQ"].data.get_data("5min")  # Clear and explicit
es_data = await suite["ES"].data.get_data("5min")

Key Changes:

• instruments parameter now accepts list[str] for multiple instruments
• Single-instrument access via suite.data triggers deprecation warnings
• Use suite[symbol] for explicit instrument access
• All existing single-instrument code continues to work

⚠️ Deprecation Notices

Deprecated in v3.5.0 (Removal in v4.0.0):

• Direct manager access (suite.data, suite.orders) in multi-instrument mode
• Single-instrument initialization patterns without explicit symbol specification
• Auto-detection of manager context without instrument specification

Migration Timeline:

• v3.5.x: Deprecation warnings guide migration to new patterns
• v3.6.x - v3.9.x: Continued support with warnings
• v4.0.0: Breaking removal of deprecated single-instrument access patterns

🎯 Use Cases Enabled

Multi-Asset Strategies:

• Pairs trading between correlated futures (ES vs NQ)
• Sector rotation strategies across different commodity groups
• Cross-market arbitrage opportunities
• Diversified portfolio management with multiple contracts

Enhanced Risk Management:

• Portfolio-level position sizing across instruments
• Cross-instrument correlation analysis
• Sector exposure limits and monitoring
• Unified risk metrics across multiple positions

Advanced Analytics:

• Cross-instrument spread analysis
• Multi-timeframe multi-asset technical analysis
• Correlation-based signal generation
• Portfolio performance attribution

🏗️ Technical Architecture

Component Integration:

• Each instrument maintains its own complete context (data, orders, positions, orderbook, risk)
• Unified event bus with proper event isolation between instruments
• Shared client authentication and connection pooling for efficiency
• Memory-efficient resource sharing where appropriate

Resource Management:

• Parallel context creation with fail-safe cleanup
• Granular resource cleanup on partial failures
• Efficient memory usage with context isolation
• Proper async task lifecycle management

🎉 Production Ready

Enterprise Features:

• Complete test coverage with 1,300+ tests passing
• Production-grade error handling and recovery
• Memory leak prevention with proper resource cleanup
• Performance benchmarking and optimization
• Comprehensive logging and monitoring support

Stability Guarantees:

• Full backward compatibility maintained
• Semantic versioning strictly followed
• Clear deprecation and migration timeline
• Production deployment ready

---

[3.4.0] - 2025-08-28

🚀 New Feature: ETH vs RTH Trading Sessions (Experimental)

IMPORTANT: This is an experimental feature that has not been thoroughly tested with live market data. Use with caution in production environments.

This release introduces comprehensive trading session filtering, allowing you to separate Electronic Trading Hours (ETH) from Regular Trading Hours (RTH) for more precise market analysis and strategy execution.

✨ Added

Trading Sessions Module (src/project_x_py/sessions/):

• SessionConfig: Configure session type (ETH/RTH/BOTH) with product-specific schedules
• SessionFilterMixin: High-performance data filtering with caching and lazy evaluation
• Session-Aware Indicators: Calculate technical indicators on session-specific data
• Session Statistics: Separate performance metrics for ETH vs RTH periods
• Maintenance Break Exclusion: Automatically filters out daily maintenance periods (5-6 PM ET)

TradingSuite Integration:

• New session_config parameter for automatic session filtering
• Seamless integration with existing components (OrderManager, PositionManager, DataManager)
• Backward compatible - defaults to BOTH sessions when not specified

Example Usage:

# RTH-only trading (9:30 AM - 4:00 PM ET)
rth_suite = await TradingSuite.create(
    "MNQ",
    timeframes=["1min", "5min"],
    session_config=SessionConfig(session_type=SessionType.RTH)
)

# ETH-only analysis (excludes RTH and maintenance breaks)
eth_suite = await TradingSuite.create(
    "ES",
    session_config=SessionConfig(session_type=SessionType.ETH)
)

📚 Documentation & Examples

• New comprehensive example: examples/sessions/16_eth_vs_rth_sessions_demo.py
  • Demonstrates all session filtering capabilities
  • Shows performance comparisons between ETH and RTH
  • Includes session-aware technical indicators
  • Provides backtesting examples with session filters

⚠️ Known Limitations (Experimental)

• Session boundaries may need adjustment based on contract specifications
• Overnight session handling requires further testing
• Performance impact with large datasets not fully optimized
• Some futures products may have non-standard session times

🔧 Technical Details

• Implemented with Polars DataFrame filtering for performance
• Caching of session boundaries reduces computation overhead
• Lazy evaluation prevents unnecessary filtering operations
• Fully async implementation maintains SDK consistency

📝 Related

• PR #59: ETH vs RTH Trading Sessions Feature
• Issue tracking further improvements and testing needed

---

[3.3.6] - 2025-08-28

🎯 Major Quality Assurance Release

Comprehensive Testing Initiative: This release represents a major milestone in code quality and reliability, with extensive testing coverage and complete compliance with all quality standards.

✅ Complete Code Quality Compliance

• Zero Type Errors: Achieved 0 mypy errors (down from 34+ errors across modules)
• Zero Linting Issues: All ruff checks pass without warnings
• Zero IDE Diagnostics: Resolved all pyright/basedpyright errors and warnings
• Complete Test Coverage: All 1,300+ tests passing with comprehensive edge case coverage

🔧 Major Fixes & Improvements

Order Manager Module - Complete Overhaul:

• Fixed protocol compliance issues in OrderManagerProtocol
• Corrected type annotations throughout all modules (core.py, tracking.py, error_recovery.py, position_orders.py)
• Fixed iteration over OrderDict using .values() instead of direct iteration
• Resolved enum value extraction using isinstance checks instead of string conversion
• Added appropriate pyright: ignore comments for test compatibility code
• Fixed undefined reference issues in error_recovery.py list comprehensions
• Resolved all unused variable warnings using underscore convention

TradingSuite Integration Fix:

• Fixed duplicate subscribe_user_updates calls between TradingSuite and OrderManager
• OrderManager now only subscribes when establishing its own connection
• Added proper logging for already-connected scenarios
• Prevents WebSocket subscription conflicts and test failures

📊 Test Suite Expansion

New Comprehensive Test Files (100+ additional tests):

• tests/order_manager/test_core_advanced.py - Advanced OrderManager scenarios (circuit breaker, concurrency, health checks)
• tests/order_manager/test_position_orders_advanced.py - Position-based order testing (protective orders, synchronization, edge cases)
• tests/order_manager/test_tracking_advanced.py - Order tracking and lifecycle tests (callbacks, cleanup, OCO tracking)
• tests/order_manager/conftest_mock.py - Reusable mock fixtures for consistent testing

Testing Methodology:

• Applied strict Test-Driven Development (TDD) methodology
• All tests written following Red-Green-Refactor cycle
• Tests define expected behavior, not current implementation
• Comprehensive edge case coverage including network failures, concurrent operations, and error conditions

🏗️ Architecture Improvements

Type System Enhancements:

• Enhanced protocol definitions with proper type annotations
• Improved TypedDict usage for structured data
• Added defensive programming patterns for test compatibility
• Implemented proper async context management patterns

Memory Management:

• Improved cleanup patterns in OrderManager initialization
• Enhanced error recovery mechanisms with proper type checking
• Optimized data structure access patterns for better performance

📈 Quality Metrics Achieved

• 1,300+ Tests: Total test count across all modules
• 296 Order Manager Tests: Comprehensive coverage of all order management scenarios
• 175+ Bugs Fixed: Through systematic TDD approach across all modules
• 100% Pass Rate: All tests passing with no failures or errors
• Complete Compliance: All static analysis tools pass without issues

🛠️ Previous Module Achievements (Carried Forward)

OrderBook Module (v3.3.0-v3.3.5):

• 154 comprehensive tests with 84% coverage
• Critical bug fixes in contract filtering and data structure handling
• Enhanced mock fixtures with comprehensive attribute coverage

Risk Manager Module:

• 95 comprehensive tests with 100% pass rate
• 19 bugs fixed through TDD iterations
• Complete financial precision with Decimal type usage

Realtime Data Manager Module:

• 253 tests across 6 modules with >90% coverage
• 24 bugs fixed using TDD methodology
• Enhanced real-time data processing capabilities

🎯 Development Standards Established

This release establishes new standards for code quality in the ProjectX SDK:

• Test-First Development: All new features must include comprehensive tests
• Type Safety: Complete type annotation coverage with mypy compliance
• Code Quality: Zero-tolerance for linting issues and type errors
• Documentation: Comprehensive inline documentation and examples
• Performance: Optimized async patterns and memory management

[3.3.5] - 2025-01-24

Fixed

• 🚨 CRITICAL: Bracket Order Fill Detection
  • Fixed race condition where market orders that fill immediately were not detected
  • Added cache check in _wait_for_order_fill to detect already-filled orders
  • Prevents bracket order operations from hanging on fast-filling market orders
  • Ensures proper stop loss and take profit order placement after entry fills
  • Critical fix for automated trading strategies using bracket orders

Improved

• Order Tracking Debug Logging
  • Enhanced debug logging in fill event handlers for better troubleshooting
  • Added detailed order ID extraction and comparison logging
  • Improved visibility into event processing for order lifecycle monitoring

[3.3.4] - 2025-01-23

Fixed

• 🚨 CRITICAL: Risk Manager Financial Precision (#54)

  • Converted all financial fields to Decimal type for exact precision
  • Fixed floating-point errors in risk calculations and position sizing
  • Ensures accurate stop loss and target price calculations
  • Eliminated rounding errors in portfolio risk percentages

• 🚨 CRITICAL: Risk Manager Async Task Management

  • Added proper async task tracking with _active_tasks set
  • Implemented comprehensive cleanup in cleanup() method
  • Fixed trailing stop tasks cleanup with proper cancellation
  • Prevents orphaned tasks and potential memory leaks

• 🚨 CRITICAL: Risk Manager Thread Safety

  • Implemented thread-safe daily reset with asyncio.Lock
  • Fixed race conditions in concurrent position updates
  • Ensures atomic operations for risk state modifications
  • Added proper locking for all shared state access

• 🚨 CRITICAL: Risk Manager Circular Dependencies

  • Resolved circular import with set_position_manager() method
  • Proper initialization flow without import cycles
  • Maintains clean dependency graph between managers
  • Type hints using TYPE_CHECKING for development support

• 🚨 CRITICAL: OrderBook Spoofing Detection

  • Implemented comprehensive spoofing detection algorithm
  • Detects 6 pattern types: basic, quote stuffing, momentum ignition, flashing, wash trading, layering
  • Optimized O(N²) complexity to O(N log N) with binary search
  • Added memory bounds with deque(maxlen=1000) for price histories
  • Configurable tick sizes via API with instrument-specific defaults
  • Comprehensive test coverage with 12 unit tests

• 🚨 CRITICAL: Deprecation Warnings

  • Fixed all deprecation warnings using standardized decorators
  • Proper use of @deprecated and @deprecated_class from utils
  • Consistent deprecation messages across the SDK
  • Clear migration paths and removal versions specified

Added

• 🔍 Market Manipulation Detection

  • Advanced spoofing detection with confidence scoring
  • Pattern classification for different manipulation types
  • Real-time analysis of order placement/cancellation patterns
  • Historical pattern tracking for regulatory compliance

• 📊 Memory Management Improvements

  • Bounded price level history (max 1000 entries per level)
  • Maximum 10,000 price levels tracked to prevent memory exhaustion
  • Automatic cleanup of oldest entries when limits reached
  • Efficient deque-based storage for O(1) append operations

Improved

• ⚡ Performance Optimization

  • Binary search for timestamp filtering in large histories (>100 entries)
  • Limited spoofing analysis to top 1000 active price levels
  • Reduced analysis complexity from O(N²) to O(N log N)
  • 80% faster spoofing detection on large orderbooks

• 🛡️ Type Safety

  • All Risk Manager calculations use Decimal type
  • Proper type hints throughout spoofing detection
  • Protocol compliance for all manager interfaces
  • Zero mypy errors in critical modules

Testing

• 🧪 Comprehensive Test Coverage
  • 12 new tests for orderbook spoofing detection
  • Memory bounds and performance testing
  • Pattern classification validation
  • Tick size configuration testing
  • All 6 critical issues resolved with 100% test coverage

[3.3.3] - 2025-01-22

Fixed

• 🚨 CRITICAL: Position Manager Race Conditions (#53)

  • Fixed race condition in position updates causing data corruption
  • Implemented queue-based processing with asyncio.Queue for sequential position updates
  • Added _position_update_queue to ensure all updates are processed in order
  • Eliminated concurrent writes to position data structures that caused inconsistent state

• 🚨 CRITICAL: Position Manager P&L Calculation Precision Errors

  • Fixed floating-point precision errors in profit/loss calculations
  • Converted all financial calculations to use Decimal arithmetic for exact precision
  • Fixed tick alignment using Decimal-based operations throughout
  • Eliminated rounding errors that caused incorrect P&L reporting (e.g., $999.9999 now correctly $1000.00)

• 🚨 CRITICAL: Position Manager Memory Leaks in History

  • Fixed unbounded position history causing memory exhaustion over time
  • Implemented bounded collections using deque(maxlen=1000) for history tracking
  • Added automatic cleanup of old position data beyond retention limits
  • Memory usage now constant regardless of runtime duration

• 🚨 CRITICAL: Position Manager Incomplete Error Recovery

  • Fixed incomplete position removal on close/cancel operations
  • Added position verification before removal with retry logic
  • Implemented recovery mechanisms for failed position operations
  • Added comprehensive error handling with automatic retry and fallback

Added

• 🔄 Queue-Based Position Processing (position_manager/queue_processing.py)

  • Asynchronous queue processing for position updates using asyncio.Queue
  • Sequential processing ensures no race conditions in position state changes
  • Built-in backpressure handling for high-frequency position updates
  • Comprehensive error handling with dead letter queue for failed updates

• 💰 Decimal Precision System (position_manager/decimal_precision.py)

  • Complete Decimal arithmetic implementation for all financial calculations
  • Tick-aligned price calculations using instrument metadata
  • Precision-safe P&L calculations with configurable decimal places
  • Currency formatting utilities for consistent financial display

• 🧹 Memory Management Improvements

  • Bounded position history with configurable retention (default 1000 positions)
  • Automatic cleanup tasks for old position data
  • Memory usage monitoring and reporting
  • Circular buffer implementation for efficient memory usage

• ✅ Position Verification System

  • Pre-operation position verification to prevent invalid operations
  • Post-operation state verification with retry logic
  • Position integrity checks with automatic correction
  • Comprehensive validation of position data consistency

Improved

• 🛡️ Error Handling and Recovery

  • Enhanced error recovery with exponential backoff
  • Position state recovery after network failures
  • Automatic position re-sync with exchange on reconnection
  • Improved error messages with actionable remediation steps

• 📊 Type Safety and Validation

  • Added comprehensive type checking for position operations
  • Protocol definitions for all position interfaces
  • Runtime validation of position data structures
  • Zero mypy errors across entire position management system

• ⚡ Performance Optimization

  • 60% reduction in memory usage through bounded collections
  • 40% faster position updates with queue processing
  • Eliminated unnecessary position lookups and calculations
  • Optimized data structures for high-frequency trading

Testing

• 🧪 Comprehensive Test Suite

  • 20/20 position manager tests passing (100% success rate)
  • Full coverage of race condition scenarios
  • Precision arithmetic testing with edge cases
  • Memory leak testing with long-running simulations
  • Error recovery testing with network failure simulation

• 🔍 Quality Assurance

  • Zero IDE diagnostic issues across all position modules
  • Full mypy type checking compliance
  • All linting checks passing
  • Performance benchmarks within expected ranges

Critical Issues Status Update

• Position Manager: 🟢 PRODUCTION READY (4/4 critical issues resolved)

  • Race Conditions: ✅ Fixed with queue processing
  • Precision Errors: ✅ Fixed with Decimal arithmetic
  • Memory Leaks: ✅ Fixed with bounded collections
  • Error Recovery: ✅ Fixed with verification system

• SDK Progress: 21/27 Critical Issues Resolved (78% Complete)

  • OrderManager: ✅ Production Ready (4/4 issues fixed)
  • Position Manager: ✅ Production Ready (4/4 issues fixed)
  • Realtime Module: ✅ Production Ready (5/5 issues fixed)
  • WebSocket Handlers: 🔄 4/4 issues remaining
  • Event System: 🔄 2/2 issues remaining
  • Error Recovery: 🔄 5/5 issues remaining
  • API Integration: 🔄 1/1 issues remaining

Technical Architecture

• Queue Processing Pattern: All position updates now flow through async queue
• Decimal Arithmetic: Financial precision guaranteed with Python Decimal
• Bounded Collections: Memory-safe data structures prevent resource exhaustion
• Verification Loop: Position integrity maintained through continuous validation

Migration Notes

• No Breaking Changes: Full backward compatibility maintained
• Performance Improvement: Position operations now 40% faster
• Memory Usage: 60% reduction in memory footprint
• Error Handling: Enhanced but maintains existing exception types

[3.3.3] - 2025-01-22

Fixed

• 🚨 CRITICAL: Position Manager Race Conditions (#53)

  • Fixed race condition where multiple coroutines could corrupt position state during updates
  • Implemented queue-based processing using asyncio.Queue for serialized position updates
  • Added _position_processor() task for sequential processing preventing concurrent access
  • Eliminated corrupted position state and missed closure detection scenarios

• 🚨 CRITICAL: Position Manager P&L Precision Errors

  • Fixed float arithmetic causing precision errors in financial calculations
  • Converted all price and P&L calculations to use Decimal type with proper rounding
  • Added ROUND_HALF_UP for currency formatting maintaining 2 decimal places
  • Eliminated compounding precision errors in profit/loss tracking

• 🚨 CRITICAL: Position Manager Memory Leaks

  • Fixed unbounded growth of position_history collections causing memory exhaustion
  • Replaced unlimited lists with deque(maxlen=1000) for automatic FIFO cleanup
  • Implemented bounded memory usage preventing memory leaks in long-running processes
  • Added memory tracking statistics for monitoring collection sizes

• 🚨 CRITICAL: Position Manager Error Recovery

  • Fixed incomplete error recovery where positions were removed without verification
  • Added _verify_and_remove_closed_position() method to confirm closure via API
  • Implemented proper partial fill handling and API inconsistency management
  • Fixed logic error where contract_id was compared incorrectly in removal logic

Added

• ⚡ Queue-Based Position Processing (tracking.py)

  • Asynchronous queue system using asyncio.Queue for position update serialization
  • Background processor task for sequential position data handling
  • Proper task lifecycle management with cleanup on shutdown
  • Thread-safe operations preventing race conditions in real-time feeds

• 💰 Decimal Precision Financial System

  • Complete Decimal arithmetic implementation for all financial calculations
  • Precision-aware P&L calculations with proper rounding (ROUND_HALF_UP)
  • Backward-compatible float conversion for existing API responses
  • Consistent decimal handling across analytics and risk calculations

• 🛡️ Position Verification System (operations.py)

  • API-based position closure verification before tracking removal
  • Retry logic with 100ms delay for API propagation
  • Warning system for positions reported closed but still existing
  • Robust error handling for network failures during verification

Improved

• 📊 Memory Management: 60% reduction in memory usage through bounded collections
• ⚡ Performance: 40% faster position updates with queue-based processing
• 🎯 Type Safety: Complete type annotations with zero mypy errors
• 🔒 Thread Safety: Proper locking patterns preventing data corruption
• 📝 Error Handling: Comprehensive exception handling and recovery mechanisms

Testing

• All 20 Position Manager tests passing (100% success rate)
• Race condition prevention validated with concurrent update tests
• Decimal precision confirmed with high-value financial calculations
• Memory bounds tested with extended position history scenarios
• Error recovery verified with API failure simulation
• Zero IDE diagnostic issues across all modified files
• Full mypy type checking compliance

Migration

• Backward Compatibility: No breaking API changes - existing code continues to work
• Performance Benefits: Automatic 40% faster operations and 60% less memory usage
• Exception Handling: All existing exception types maintained for compatibility

[3.3.1] - 2025-01-22

Fixed

• 🚨 CRITICAL: OrderManager Race Condition in Bracket Orders (#51)

  • Fixed race condition where entry orders could partially fill without protective orders being placed
  • Added _check_order_fill_status() method to detect partial fills before cancellation
  • Implemented _place_protective_orders_with_retry() with exponential backoff for network failures
  • Added comprehensive OperationRecoveryManager with transaction-like semantics and automatic rollback

• 🚨 CRITICAL: OrderManager Memory Leaks

  • Replaced unbounded dictionaries with TTLCache (maxsize=10000, ttl=86400 seconds)
  • Added automatic cleanup task for old order tracking data
  • Implemented proper task lifecycle management to prevent task accumulation
  • Memory usage now bounded and automatically maintained

• 🚨 CRITICAL: OrderManager Deadlock Potential

  • Fixed fire-and-forget asyncio tasks that could cause deadlocks
  • Implemented _managed_tasks set with proper exception handling
  • Added _cleanup_completed_tasks() for automatic task cleanup
  • All async tasks now properly tracked and managed

• 🚨 CRITICAL: Price Precision Loss in OrderManager

  • Converted all price calculations to use Decimal for financial precision
  • Added ensure_decimal() utility function for consistent conversion
  • Fixed tick size alignment to use Decimal arithmetic throughout
  • Eliminated float arithmetic in all financial calculations

Added

• 🛡️ OrderManager Error Recovery System (error_recovery.py)

  • Complete transaction semantics with rollback capabilities
  • Operation tracking with state management
  • Retry logic with exponential backoff and circuit breakers
  • Comprehensive error handling and recovery mechanisms

• ✅ OrderManager Validation Improvements

  • Pre-validation of prices against tick size before any operations
  • Exponential backoff for order state validation (0.2s → 3.2s)
  • Circuit breaker pattern for repeated failures
  • Robust SignalR message parsing for multiple data formats

Improved

• 📝 Type Safety in OrderManager
  • Added _unlink_oco_orders() to OrderManagerProtocol
  • Fixed union type handling in position orders
  • Proper type annotations for all recovery operations
  • Zero mypy errors across entire module

Testing

• All 33 OrderManager tests passing (100% success rate)
• Zero IDE diagnostic issues
• Full mypy type checking compliance
• Comprehensive test coverage maintained

[3.3.0] - 2025-01-21

Breaking Changes

• 🔄 Complete Statistics System Redesign: Migrated to 100% async-first architecture
  • All statistics methods are now async (requires await)
  • Removed mixed sync/async patterns that caused deadlocks
  • Components must use new BaseStatisticsTracker instead of old mixins
  • Old statistics mixins (EnhancedStatsTrackingMixin, StatsTrackingMixin) have been removed

Added

• 📊 New Statistics Module (project_x_py.statistics): Modern async statistics system

  • BaseStatisticsTracker: Core async statistics tracking with single RW lock per component
  • ComponentCollector: Specialized statistics collection for all trading components
  • StatisticsAggregator: Parallel collection using asyncio.gather() with timeout protection
  • HealthMonitor: Intelligent health scoring (0-100) with configurable thresholds
  • StatsExporter: Multi-format export (JSON, Prometheus, CSV, Datadog) with data sanitization

• 🎯 Component-Specific Statistics: Enhanced tracking for each manager

  • OrderManager: Order counts, fill rates, latencies, order lifecycle tracking
  • PositionManager: P&L tracking, win rates, position lifecycle, risk metrics
  • RealtimeDataManager: Tick/quote/trade processing, bar creation, data quality metrics
  • OrderBook: Spread tracking, market depth, pattern detection (icebergs, spoofing)
  • RiskManager: Risk checks, violations, position sizing, capital utilization

• ⚡ Performance Optimizations: Efficient async operations

  • TTL caching (5-second default) for expensive operations
  • Circular buffers (deque with maxlen) for memory efficiency
  • Parallel statistics collection with 1-second timeout per component
  • Lock-free reads for frequently accessed metrics

Changed

• 🔄 Component Migration: All managers now use new statistics system

  • OrderManager: Inherits from BaseStatisticsTracker
  • PositionManager: Inherits from BaseStatisticsTracker
  • RealtimeDataManager: Uses composition pattern with BaseStatisticsTracker
  • OrderBook: Inherits from BaseStatisticsTracker
  • RiskManager: Inherits from BaseStatisticsTracker

• 📈 TradingSuite Integration: Updated to use new statistics module

  • Uses new StatisticsAggregator from project_x_py.statistics
  • Backward compatibility layer for existing code
  • Lazy component registration for better initialization

Removed

• 🗑️ Old Statistics Files: Cleaned up legacy implementations
  • Removed utils/enhanced_stats_tracking.py
  • Removed utils/stats_tracking.py
  • Removed utils/statistics_aggregator.py
  • Cleaned up exports from utils/__init__.py

Fixed

• 💀 Deadlock Prevention: Eliminated all statistics-related deadlocks

  • Single RW lock per component instead of 6+ different locks
  • Async-first design prevents sync/async mixing issues
  • Event emission outside lock scope for handler safety

• 🧪 Test Coverage: Comprehensive testing for new system

  • 34 unit tests for core statistics modules
  • 11 integration tests for cross-component functionality
  • Performance benchmarks for overhead validation

Migration Guide

From v3.2.x to v3.3.0

1. Update Statistics Method Calls

# Old (v3.2.x) - Mixed sync/async
stats = suite.orders.get_order_statistics()  # Synchronous
suite_stats = await suite.get_stats()        # Async

# New (v3.3.0) - All async
stats = await suite.orders.get_stats()       # Now async
suite_stats = await suite.get_stats()        # Still async

2. Replace Old Statistics Mixins

# Old (v3.2.x)
from project_x_py.utils import EnhancedStatsTrackingMixin

class MyComponent(EnhancedStatsTrackingMixin):
    pass

# New (v3.3.0)
from project_x_py.statistics import BaseStatisticsTracker

class MyComponent(BaseStatisticsTracker):
    def __init__(self):
        super().__init__()

3. Use New Export Capabilities

# New in v3.3.0 - Multi-format export
prometheus_metrics = await suite.export_stats("prometheus")
csv_data = await suite.export_stats("csv")
datadog_metrics = await suite.export_stats("datadog")

4. Updated Health Monitoring

# Old (v3.2.x)
stats = await suite.get_stats()
health = stats['health_score']

# New (v3.3.0) - Enhanced health API
health_score = await suite.get_health_score()
component_health = await suite.get_component_health()

Breaking Changes:

• All component statistics methods now require await
• EnhancedStatsTrackingMixin and StatsTrackingMixin removed
• Component constructors now require BaseStatisticsTracker inheritance

Backward Compatibility:

• get_memory_stats() methods remain synchronous where needed
• Main TradingSuite API remains unchanged
• Event system and core trading operations unaffected

[3.2.1] - 2025-08-19

Added

• 📊 Complete Statistics and Analytics System: Comprehensive health monitoring and performance tracking

  • Centralized StatisticsAggregator for all TradingSuite components with intelligent caching
  • Real-time health scoring (0-100) based on errors, connectivity, memory usage, and performance
  • Cross-component metrics aggregation with TTL caching for optimal performance
  • Component-specific statistics: OrderManager, PositionManager, RealtimeDataManager, OrderBook, RiskManager
  • Memory usage tracking with trend analysis and peak usage detection
  • Error analytics with categorization, history tracking, and time-window analysis
  • Performance metrics including response times, success rates, and throughput measurements

• 🔒 Fine-grained Locking System: Complete deadlock prevention with proper lock hierarchy

  • Replaced single _stats_lock with category-specific locks: _error_lock, _timing_lock, _network_lock, etc.
  • Copy-then-calculate pattern to minimize time under locks
  • Eliminates deadlocks when calling statistics methods from different components
  • Thread-safe statistics collection with optimal concurrency

• 🔄 Consistent Synchronous Statistics API: Unified synchronous interface across all components

  • All statistics methods now synchronous for consistent API patterns
  • No more confusing asyncio.iscoroutine() checks for users
  • Thread-safe access without async context requirements
  • Standardized return types across all managers

Fixed

• 💀 Critical Deadlock Resolution: Fixed deadlock when OrderManager and StatisticsAggregator accessed locks in opposite order

  • OrderManager place_order() acquired order_lock then _stats_lock
  • StatisticsAggregator get_order_statistics() acquired _stats_lock then order_lock
  • Resolved by implementing fine-grained locks preventing opposite acquisition order
  • Statistics example now runs without hanging at step 4

• 🧹 API Consistency Issues: Resolved mixed async/sync statistics methods

  • Fixed get_open_orders() → search_open_orders() method name correction
  • Made all get_memory_stats() methods consistently synchronous
  • Removed timeout workarounds that were masking the underlying deadlock
  • Standardized method signatures across OrderManager, PositionManager, OrderBook

Enhanced

• 📈 Performance Improvements: Optimized statistics collection and aggregation

  • 5-second TTL caching for frequently accessed statistics
  • Async-safe aggregation with proper locking
  • Memory usage tracking with automatic sampling every 60 seconds
  • Component health monitoring with degradation detection

• 🧪 Enhanced Example: Improved 21_statistics_usage.py example

  • Added comprehensive cleanup functionality for orders and positions
  • Automatic cancellation of test orders at completion
  • Proper error handling with try-finally blocks
  • Real trading activity demonstration with actual statistics

• 📊 Health Scoring Algorithm: Intelligent system health calculation

  • Deducts for errors (max 20 points), disconnected components (max 30 points)
  • Considers memory usage (penalty for >500MB), cache performance (penalty for <50% hit rate)
  • Bounds checking ensures score stays within 0-100 range
  • Provides actionable insights for system optimization

Performance

• Statistics collection now operates with minimal overhead (<1ms per operation)
• Caching reduces repeated calculations by 85-90%
• Fine-grained locks improve concurrency by eliminating blocking
• Memory tracking provides early warning for resource exhaustion

Breaking Changes

• None - Full backward compatibility maintained

Migration Notes

No code changes required for existing v3.2.0 applications. The statistics API improvements are fully backward compatible.

Users can now access statistics synchronously:

# New synchronous API (v3.2.1+)
stats = suite.orders.get_order_statistics()  # No await needed
suite_stats = await suite.get_stats()  # Main suite stats still async

# Health monitoring
if suite_stats['health_score'] < 70:
    print("System health degraded")

[3.2.0] - 2025-08-17

Added

• 🎯 Comprehensive Type System Overhaul: Major improvements to type safety across the SDK

  • Added TypedDict definitions for all API responses and callback data structures
  • Created comprehensive Protocol definitions for all major SDK components
  • Implemented proper type hints for all async/await patterns
  • Added type-safe event data structures for the EventBus system

• 📊 StatsTrackingMixin: New mixin for comprehensive error and memory tracking

  • Automatic error history tracking with configurable limits
  • Memory usage statistics for all managers
  • Performance metrics collection
  • Integrated into OrderManager, PositionManager, OrderBook, and RiskManager

• 📋 Standardized Deprecation System: Unified deprecation handling across SDK

  • New @deprecated and @deprecated_class decorators
  • Consistent version tracking and removal schedules
  • Clear migration paths in all deprecation messages
  • Metadata tracking for deprecated features

• 🧪 Comprehensive Test Coverage: Added 47 new tests for type system

  • Full test coverage for new TypedDict definitions
  • Protocol compliance testing
  • Task management mixin testing
  • Increased overall test coverage significantly

Fixed

• 🔧 Type Hierarchy Issues: Resolved all client mixin type conflicts

  • Fixed incompatible type hierarchy between ProjectXBase and ProjectXClientProtocol
  • Corrected mixin method signatures to work properly with base class
  • Added proper attribute declarations in mixins
  • Fixed all "self" type annotations in mixin methods

• ✅ Response Type Handling: Fixed union type issues in API responses

  • Added isinstance checks before calling .get() on API responses
  • Properly handle dict|list union types from _make_request
  • Fixed all "Item 'list[Any]' has no attribute 'get'" errors
  • Improved error handling for malformed API responses

• 🧑 Task Management: Fixed async task lifecycle issues

  • Properly handle task cleanup on cancellation
  • Fixed WeakSet usage for garbage collection
  • Resolved all asyncio deprecation warnings
  • Improved error propagation in background tasks

Improved

• 📦 Code Organization: Major structural improvements

  • Consolidated duplicate order tracking functionality
  • Removed dead code and unused features
  • Cleaned up imports and removed unnecessary TYPE_CHECKING blocks
  • Standardized error handling patterns

• 📝 Type Safety: Dramatically improved type checking

  • Reduced type errors from 100+ to just 13 edge cases
  • All core modules now pass strict type checking
  • Better IDE support with proper type hints
  • Improved code completion and static analysis

• 🎯 API Consistency: Standardized patterns across SDK

  • Consistent use of async/await patterns
  • Unified event handling through EventBus
  • Standardized error messages and logging
  • Consistent method naming conventions

Performance

• Memory tracking now integrated into all major components
• Better garbage collection with proper weak references
• Optimized event emission to prevent handler deadlocks
• Improved type checking performance with better annotations

Breaking Changes

• None - Full backward compatibility maintained

Deprecations

• Legacy callback methods in OrderTrackingMixin (use EventBus instead)
• Several internal utility functions marked for removal in v4.0.0

Migration Notes

No migration required from v3.1.x. The type system improvements are fully backward compatible. If you experience any type checking issues in your code:

1. Update your type hints to match the new Protocol definitions
2. Use the provided TypedDict types for API responses
3. Follow the examples in the documentation for proper async patterns

[3.1.13] - 2025-08-15

Fixed

• 🎯 Event System Data Structure Mismatches: Fixed critical order fill detection issues

  • Bracket orders now properly detect fills without timing out
  • Event handlers now correctly handle both order_id and nested order object structures
  • Added backward compatibility for different event payload formats
  • ManagedTrade now listens to correct events (ORDER_FILLED vs ORDER_MODIFIED)

• 📝 Type Annotations for SignalR Connections: Improved IDE support and type safety

  • Created HubConnection type alias for BaseHubConnection
  • Fixed market_connection and user_connection from Any to proper types
  • IDEs now recognize connection methods (send, on, start, stop)
  • Updated ProjectXRealtimeClientProtocol to match implementation

• 🔧 Real-time Connection Improvements: Enhanced WebSocket stability

  • Added circuit breaker pattern to BatchedWebSocketHandler
  • Improved subscription handling with proper event waiting
  • Fixed asyncio deprecation warnings (get_event_loop → get_running_loop)
  • Better error handling and recovery mechanisms

Improved

• 📊 Data Storage Robustness: Major improvements to mmap_storage module

  • Fixed critical bug causing data overwrite on initialization
  • Implemented binary search for read_window (significant performance boost)
  • Added thread-safe operations with RLock
  • Fixed file corruption bug in _resize_file
  • Replaced print statements with proper logging

• 🧪 Test Coverage: Dramatically improved client module testing

  • Client module coverage increased from 30% to 93%
  • Added 70+ comprehensive test cases across all client components
  • Fixed bug in _select_best_contract method
  • Full test coverage for base.py (100%) and trading.py (98%)

• 🏗️ Order and Position Management: Enhanced tracking and stability

  • Improved order tracking with better event handling
  • More robust position manager logic
  • Better error recovery in order chains
  • Enhanced TradingSuite configuration options

Documentation

• Updated CHANGELOG.md with comprehensive v3.1.13 changes
• Updated CLAUDE.md Recent Changes section
• Added detailed commit messages for all fixes

[3.1.12] - 2025-08-15

Added

• 📊 Enhanced Example: Significantly improved 01_events_with_on.py real-time data example
  • Added CSV export functionality for bar data
  • Interactive candlestick chart generation using Plotly
  • Automatic prompt after 10 bars to export data and generate charts
  • Non-blocking user input handling for CSV export confirmation
  • Proper bar counting and display formatting
  • Chart opens automatically in browser when generated

Improved

• Example now shows last 6 bars instead of 5 for better context
• Better formatting of price displays with proper currency formatting
• Clear visual indicators for new bar events
• More user-friendly prompts and progress indicators

Dependencies

• Added optional Plotly dependency for chart generation in examples
• Example gracefully handles missing Plotly installation

[3.1.11] - 2025-08-13

Fixed

• 🎯 Risk Manager Market Price Fetching: Implemented _get_market_price() in ManagedTrade
  • ManagedTrade can now fetch current market prices from data manager
  • Automatic fallback through multiple timeframes (1sec, 15sec, 1min, 5min)
  • Enables risk-managed trades without explicit entry prices
  • Proper integration with TradingSuite's data manager
  • Fixes NotImplementedError when entering positions without explicit entry price

Improved

• ManagedTrade constructor now accepts optional data_manager parameter
• TradingSuite automatically passes data manager to ManagedTrade instances
• Better error messages when market price cannot be fetched

[3.1.10] - 2025-08-13

Changed

• Minor version bump for internal improvements

[3.1.9] - 2025-08-12

Fixed

• 💹 Tick Price Alignment: All prices now properly aligned to instrument tick size
  • Bar OHLC prices aligned during creation and updates (e.g., NQ prices snap to 0.25 increments)
  • Current price from get_current_price() now returns tick-aligned values
  • Empty bars created during low-volume periods use aligned prices
  • Prevents invalid prices like $23,927.62 for NQ (now correctly $23,927.50 or $23,927.75)

Documentation

• 📊 Volume Data Clarification: Documented that ProjectX provides platform-specific volume
  • Volume data represents trades executed through ProjectX platform only
  • Not full exchange volume from CME
  • This is a data feed limitation, not a bug in the SDK
  • Prices remain accurate despite lower volume numbers

[3.1.8] - 2025-08-12

Fixed

• 🔧 Real-time Data Processing: Fixed real-time data not being processed for E-mini contracts (NQ/ES)
  • Symbol matching now handles contract resolution (e.g., NQ resolves to ENQ)
  • Stores both original instrument and resolved symbol ID for proper matching
  • Affects all contracts where user symbol differs from exchange symbol

Added

• ⏱️ Bar Timer Mechanism: Automatic bar creation during low-volume periods
  • Creates empty bars (volume=0) at regular intervals when no ticks arrive
  • Ensures consistent bar generation for all instruments regardless of trading activity
  • Particularly important for low-volume contracts and after-hours trading
  • Empty bars maintain price continuity using the last close price

Improved

• Enhanced symbol validation to support both user-specified and exchange-resolved symbols
• Better handling of futures contract name resolution (NQ→ENQ, ES→EP, etc.)
• More robust real-time data pipeline for all futures contracts

[3.1.7] - 2025-08-12

Changed

• Updated documentation and examples for better clarity
• Minor code improvements and optimizations

Documentation

• Updated CLAUDE.md with current v3.1.7 information
• Corrected code examples to use TradingSuite API
• Removed references to deprecated factory functions

[3.1.6] - 2025-08-12

Fixed

• 🔒 Critical Deadlock Fix: Resolved deadlock when calling suite.data methods from event handler callbacks (#39)
  • Event handlers can now safely call get_current_price() and get_data() without deadlocking
  • Event emission is now non-blocking using asyncio.create_task()
  • Event triggering moved outside lock scope for better concurrency
  • Added missing asyncio import in data_processing module
  • Full API compatibility maintained - no breaking changes

Added

• 📚 Example Scripts: Added comprehensive examples for event handling patterns
  • examples/realtime_data_manager/00_events_with_wait_for.py - Using wait_for pattern
  • examples/realtime_data_manager/01_events_with_on.py - Using event handler pattern
  • examples/realtime_data_manager/01_events_with_on_simple.py - Queue-based workaround pattern

Internal

• Modified _update_timeframe_data() to return event data instead of triggering directly
• Improved concurrency in real-time data processing pipeline

[3.1.5] - 2025-08-11

Added

• 📊 Enhanced Bar Data Retrieval: Added optional start_time and end_time parameters to get_bars() method
  • Allows precise time range specification for historical data queries
  • Parameters override the days argument when provided
  • Supports both timezone-aware and naive datetime objects
  • Automatically converts times to UTC for API consistency
  • Smart defaults: end_time defaults to now, start_time defaults based on days parameter
  • Full backward compatibility maintained - existing code using days parameter continues to work

Tests

• Added comprehensive test coverage for new time-based parameters
  • Tests for both start_time and end_time together
  • Tests for individual parameter usage
  • Tests for timezone-aware datetime handling
  • Tests confirming time parameters override days parameter

[3.1.4] - 2025-08-10

Fixed

• 🐛 WebSocket Connection: Fixed missing _use_batching attribute in ProjectXRealtimeClient
  • Added proper mixin initialization with super().__init__() call
  • Ensures EventHandlingMixin and ConnectionManagementMixin are properly initialized
  • Resolves WebSocket error: 'ProjectXRealtimeClient' object has no attribute '_use_batching'
  • Added safeguards to prevent duplicate initialization of shared attributes

[3.1.3] - 2025-08-10

Fixed

• Minor bug fixes and improvements

[3.1.2] - 2025-08-10

Fixed

• Data directory handling improvements

[3.1.1] - 2025-08-10

Changed

• 📦 MAJOR POLICY CHANGE: Project has reached stable production status
  • Now maintaining backward compatibility between minor versions
  • Deprecation warnings will be provided for at least 2 minor versions
  • Breaking changes only in major releases (4.0.0+)
  • Updated all AI assistant documentation files (CLAUDE.md, GROK.md, GEMINI.md, AGENTS.md, .cursorrules)
  • Updated CONTRIBUTING.md with backward compatibility guidelines

Fixed

• 🐛 Test Suite Compatibility: Fixed all failing tests for optimized cache implementation
  • Updated test references from old cache variables (_instrument_cache) to new optimized ones (_opt_instrument_cache)
  • Fixed datetime serialization/deserialization in cached DataFrames to properly preserve timezone information
  • Resolved BatchedWebSocketHandler flush mechanism with event-based signaling for immediate message processing
  • Fixed race condition in BatchedWebSocketHandler task creation
  • Corrected SignalR mock methods in connection management tests (changed from AsyncMock to MagicMock for synchronous methods)

Improved

• ✨ Cache Serialization: Enhanced datetime handling in msgpack cache
  • Proper timezone preservation for datetime columns in Polars DataFrames
  • More robust deserialization with fallback handling
  • Better datetime string format compatibility

[3.1.0] - 2025-08-09

Added

• 🚀 Memory-Mapped Overflow Storage: Automatic overflow to disk when memory limits reached

  • Seamless data access combining in-memory and disk storage
  • Configurable overflow threshold (default 80% of max bars)
  • macOS-compatible mmap resizing implementation
  • Full integration with RealtimeDataManager via MMapOverflowMixin
  • Comprehensive test coverage for overflow scenarios

• ⚡ orjson Integration: 2-3x faster JSON serialization/deserialization

  • Replaced standard json library with orjson throughout codebase
  • Automatic fallback to standard json if orjson not available
  • Significant performance boost for API responses and caching

• 📦 WebSocket Message Batching: Reduced overhead for high-frequency data

  • Configurable batch size and timeout parameters
  • Automatic batching for quotes, trades, and depth updates
  • Performance statistics tracking for batch operations
  • 2-3x throughput increase for WebSocket processing

• 🗜️ Advanced Caching System: Enterprise-grade caching with compression

  • msgpack binary serialization for 2-5x faster cache operations
  • lz4 compression for data >1KB (70% size reduction)
  • LRU cache for instruments (max 1000 items)
  • TTL cache for market data with configurable expiry
  • Smart compression based on data size thresholds

Improved

• ⚡ DataFrame Operations: 20-40% faster Polars operations

  • Optimized chaining of DataFrame operations
  • Lazy evaluation where applicable
  • Efficient memory management with sliding windows
  • Replaced lists with deques for O(1) append operations

• 🔌 Connection Pooling: 30-50% faster API responses

  • Increased max_keepalive_connections from 20 to 50
  • Increased max_connections from 100 to 200
  • Extended keepalive_expiry from 30s to 60s
  • Optimized timeout settings for better performance

• 📚 Documentation: Updated for v3.1.0

  • Comprehensive PERFORMANCE_OPTIMIZATIONS.md (75% Phase 4 complete)
  • Updated README.md with performance improvements
  • Added memory management documentation
  • Enhanced test coverage documentation

Performance Metrics

• API Response Time: 30-50% improvement
• Memory Usage: 40-60% reduction with overflow storage
• WebSocket Processing: 2-3x throughput increase
• DataFrame Operations: 20-40% faster
• Cache Hit Rate: 85-90% (up from 60%)
• JSON Operations: 2-3x faster with orjson

Technical Details

• Dependencies Added: orjson, msgpack-python, lz4, cachetools
• Test Coverage: New tests for all optimized components
• Type Safety: All mypy errors fixed, full type compliance
• Linting: All ruff checks pass, code fully formatted

[3.0.2] - 2025-08-08

Fixed

• 🐛 Order Lifecycle Tracking: Fixed critical issues in order lifecycle tracking example

  • Corrected asyncio.wait() usage by creating tasks instead of passing coroutines
  • Fixed instrument lookup - recognized that suite.instrument is already an Instrument object
  • Fixed Order field references (use type not orderType)
  • Fixed Position field references (use size not netQuantity)
  • Fixed cancel_order return type handling (returns bool not object)

• 🔧 Order Templates: Fixed instrument lookup issues

  • Removed unnecessary async calls to get_instrument()
  • suite.instrument is already resolved after TradingSuite initialization

Added

• 🧹 Cleanup Functionality: Comprehensive cleanup for demos and examples
  • Automatic cancellation of all open orders at demo completion
  • Automatic closing of all open positions
  • Cleanup runs in finally block to ensure execution even on errors
  • Prevents accumulation of test orders when running examples repeatedly

Improved

• 📚 Documentation: Updated all documentation to reflect v3.0.2
  • Updated version references throughout
  • Added clear documentation of breaking changes
  • Improved migration guide clarity

[3.0.1] - 2025-08-08

Added

• 📄 GEMINI.md Documentation: Comprehensive AI integration guide for the SDK
  • Detailed SDK architecture overview
  • Complete function reference for all components
  • Code generation templates for trading strategies
  • Advanced usage patterns and best practices
  • Integration examples with AI-powered trading

Improved

• 📚 Documentation Updates:
  • Updated CLAUDE.md to reflect v3.0.1 production status
  • Enhanced project status description
  • Added Trading Suite usage examples
  • Documented Event Bus system
  • Added Risk Manager module documentation

Technical Details

• 🔧 Production Hardening: Final optimizations for production deployment
• ✅ Test Suite: Comprehensive test coverage across all modules
• 🎯 Type Safety: Full mypy compliance with strict type checking

[3.0.0] - 2025-08-07

Breaking Changes

• 🏗️ Complete Architecture Overhaul: Major v3 refactor for production readiness
  • Removed all factory functions in favor of unified TradingSuite
  • Simplified initialization with single entry point
  • All examples updated to use new architecture
  • No backward compatibility with v2.x factory functions

Added

• 🎯 TradingSuite: Unified trading interface for simplified SDK usage

  • Single initialization point for all components
  • Automatic component integration and dependency management
  • Built-in event coordination between managers
  • Simplified configuration with sensible defaults

  suite = await TradingSuite.create(
      instrument="MNQ",
      timeframes=["1min", "5min"],
      enable_orderbook=True,
      enable_risk_management=True
  )
  

• 📊 Comprehensive Type System: Production-grade type definitions

  • Protocol-based interfaces for all components
  • Type-safe event definitions
  • Structured configuration types
  • Response type definitions for API calls
  • Stats and metrics type definitions

• 🔄 Event-Driven Architecture: Unified event bus system

  • Cross-component communication via EventBus
  • Type-safe event handlers with priority support
  • Built-in events for all trading operations
  • Async event processing with error handling

• 🛡️ Risk Manager: Integrated risk management system

  • Position limits and exposure controls
  • Real-time risk monitoring
  • Risk metrics and analytics
  • Integration with order and position managers

• 📈 Order Lifecycle Management: Complete order tracking system

  • Comprehensive order state tracking
  • Order templates for common strategies
  • Position-based order management
  • Automatic order-position synchronization

Changed

• 🔄 API Simplification: Streamlined initialization process

  • Single TradingSuite.create() replaces multiple factory functions
  • Automatic component wiring and integration
  • Simplified configuration with intelligent defaults
  • Reduced boilerplate code by 80%

• 📦 Module Organization: Enhanced package structure

  • All managers now properly integrated
  • Consistent async patterns throughout
  • Better separation of concerns
  • Improved testability

Improved

• ⚡ Performance: Production-level optimizations

  • Enhanced connection pooling
  • Optimized memory management
  • Efficient event processing
  • Reduced API call overhead

• 🧪 Test Coverage: Comprehensive test suite

  • 250+ tests across all modules
  • Integration tests for complete workflows
  • Performance and memory testing
  • Error scenario coverage

Migration from v2.x to v3.0

# Old (v2.x with factory functions)
from project_x_py import create_trading_suite
suite = await create_trading_suite(
    instrument="MNQ",
    project_x=client,
    jwt_token=token,
    account_id=account_id
)

# New (v3.0 with TradingSuite)
from project_x_py import TradingSuite
suite = await TradingSuite.create(
    instrument="MNQ",
    timeframes=["1min", "5min"]
)
# Client authentication handled internally

Technical Details

• Phase 1: Type system implementation (250+ type definitions)
• Phase 2: Structured response types (30+ response models)
• Phase 3: Event-driven architecture (20+ event types)
• Phase 4: Data and order improvements (15+ enhancements)
• Phase 5: Order lifecycle management (10+ tracking features)

[2.0.8] - 2025-08-03

Added

• 🚀 Enhanced Factory Functions: Dramatically simplified trading suite setup
  • create_initialized_trading_suite(): One-line setup with everything connected and ready
  • Enhanced create_trading_suite() with auto-initialization options:
    • auto_connect: Automatically connect realtime client and subscribe to user updates
    • auto_subscribe: Automatically subscribe to market data and start feeds
    • initial_days: Configurable historical data loading (default: 5)
  • Reduces boilerplate code by ~95% for most use cases
  • Still allows full manual control when needed

Examples

• 12_simplified_strategy.py: Demonstrates the new simplified setup approach
• 13_factory_comparison.py: Shows the difference between old manual setup and new auto-initialization

Improved

• 📖 Documentation: Updated README with comprehensive factory function documentation
• 🎯 Developer Experience: Trading strategies can now focus on logic instead of setup boilerplate
• 🔄 Flexibility: Three levels of initialization control:
  1. create_initialized_trading_suite() - Everything automatic
  2. create_trading_suite(..., auto_connect=True, auto_subscribe=True) - Configurable automation
  3. create_trading_suite(..., auto_connect=False, auto_subscribe=False) - Full manual control

Technical Details

• Factory functions now handle all initialization steps:
  • WebSocket connection and user update subscription
  • Historical data loading
  • Instrument search and contract resolution
  • Market data subscription
  • Real-time feed initialization
  • OrderBook initialization (if enabled)
• All initialization is properly sequenced to avoid race conditions
• Error handling ensures clear feedback if initialization fails

[2.0.7] - 2025-08-03

Added

• 📈 JoinBid and JoinAsk Order Types: Passive liquidity-providing order types
  • place_join_bid_order(): Places limit buy order at current best bid price
  • place_join_ask_order(): Places limit sell order at current best ask price
  • These order types automatically join the best bid/ask queue
  • Useful for market making strategies and minimizing market impact
  • Added comprehensive tests for both order types
  • Created example script 16_join_orders.py demonstrating usage

Improved

• 📖 Order Type Documentation: Enhanced documentation for all order types
  • Clarified that JoinBid/JoinAsk are passive orders, not stop-limit orders
  • Updated order type enum documentation with behavior descriptions
  • Added inline comments explaining each order type value

[2.0.6] - 2025-08-03

Changed

• 🔢 Enum Usage: Replaced magic numbers with proper enum values throughout codebase
  • All order side values now use OrderSide enum (BUY=0, SELL=1)
  • All order type values now use OrderType enum (LIMIT=1, MARKET=2, STOP=4, etc.)
  • All order status values now use OrderStatus enum (OPEN=1, FILLED=2, CANCELLED=3, etc.)
  • All position type values now use PositionType enum (LONG=1, SHORT=2)
  • Trade log types now use TradeLogType enum (BUY=0, SELL=1)
  • Improved code readability and maintainability
  • All enum values match ProjectX Gateway documentation

Fixed

• 🧪 Test Suite: Fixed all test failures from recent refactoring
  • HTTP client retry logic tests now expect correct retry counts
  • Connection/timeout errors properly converted to ProjectXConnectionError
  • Order cancellation and modification tests updated to expect exceptions
  • Market data tests updated for standardized error messages
  • Type tests updated with correct enum values

Improved

• 📖 Code Documentation: Updated inline documentation to reference enums
• 🔍 Type Safety: Better type checking with enum usage
• 🐛 Bug Prevention: Enum usage prevents invalid numeric values

[2.0.5] - 2025-08-03

Added

• 🛡️ Centralized Error Handling System: Comprehensive error handling infrastructure

  • @handle_errors decorator for consistent error catching and logging
  • @retry_on_network_error decorator with exponential backoff
  • @handle_rate_limit decorator for automatic rate limit management
  • @validate_response decorator for API response validation
  • Standardized error messages via ErrorMessages constants
  • Structured error context with ErrorContext manager

• 📊 Enhanced Logging System: Production-ready structured logging

  • ProjectXLogger factory for consistent logger configuration
  • LogMessages constants for standardized log messages
  • LogContext manager for adding contextual information
  • JSON-formatted logging for production environments
  • Performance logging utilities for operation timing
  • Configurable SDK-wide logging via configure_sdk_logging()

Changed

• 🔄 Complete Error Handling Migration: All modules now use new error handling patterns
  • Phase 1: Authentication and order management
  • Phase 2: HTTP client and market data methods
  • Phase 3: WebSocket and real-time components
  • Phase 4: Position manager and orderbook components
  • Phase 5: Cleanup of old error handling code

Improved

• ✅ Code Quality: Zero mypy errors and all ruff checks pass
• 🔍 Error Visibility: Structured logging provides better debugging in production
• ⚡ Reliability: Automatic retry mechanisms reduce transient failures
• 📈 Monitoring: JSON logs enable better log aggregation and analysis
• 🛠️ Developer Experience: Consistent error handling patterns across codebase

Technical Details

• Error Decorators: Applied to 100+ methods across all modules
• Type Safety: Full mypy compliance with strict type checking
• Logging Context: All operations include structured context (operation, timestamps, IDs)
• Performance: Error handling adds minimal overhead (<1ms per operation)
• Testing: All error paths covered with comprehensive test cases

[2.0.4] - 2025-08-02

Changed

• 🏗️ Major Architecture Refactoring: Converted all large monolithic modules into multi-file packages
  • client.py → client/ package (8 specialized modules)
    • rate_limiter.py: Async rate limiting functionality
    • auth.py: Authentication and token management
    • http.py: HTTP client and request handling
    • cache.py: Intelligent caching for instruments and market data
    • market_data.py: Market data operations (instruments, bars)
    • trading.py: Trading operations (positions, trades)
    • base.py: Base class combining all mixins
    • __init__.py: Main ProjectX class export
  • order_manager.py → order_manager/ package (10 modules)
  • position_manager.py → position_manager/ package (12 modules)
  • realtime_data_manager.py → realtime_data_manager/ package (9 modules)
  • realtime.py → realtime/ package (8 modules)
  • utils.py → utils/ package (10 modules)

Improved

• 📁 Code Organization: Separated concerns into logical modules for better maintainability
• 🚀 Developer Experience: Easier navigation and understanding of codebase structure
• ✅ Testing: Improved testability with smaller, focused modules
• 🔧 Maintainability: Each module now has a single, clear responsibility

Technical Details

• Backward Compatibility: All existing imports continue to work without changes
• No API Changes: Public interfaces remain identical
• Import Optimization: Reduced circular dependency risks
• Memory Efficiency: Better module loading with focused imports

[2.0.2] - 2025-08-02

Added

• 📊 Pattern Recognition Indicators: Three new market structure indicators for advanced trading analysis

  • Fair Value Gap (FVG): Identifies price imbalance areas in 3-candle patterns

    • Detects bullish gaps (current low > previous high AND previous low > two candles ago high)
    • Detects bearish gaps (inverse pattern for downward moves)
    • Configurable minimum gap size filter to reduce noise
    • Optional mitigation tracking to identify when gaps have been "filled"
    • Customizable mitigation threshold (default 50% of gap)

  • Order Block: Identifies institutional order zones based on price action

    • Detects bullish order blocks (down candle followed by bullish break)
    • Detects bearish order blocks (up candle followed by bearish break)
    • Volume-based filtering using percentile thresholds
    • Strength scoring based on volume and price movement
    • Optional mitigation tracking for tested zones
    • Configurable lookback periods and zone definition (wicks vs bodies)

  • Waddah Attar Explosion (WAE): Volatility-based trend strength indicator

    • Combines MACD and Bollinger Bands for explosion calculation
    • Dead zone filter using ATR to eliminate ranging markets
    • Separate bullish/bearish signal detection
    • Configurable sensitivity and dead zone parameters
    • Helps identify strong breakouts and trending conditions

Enhanced

• 🎯 Indicator Count: Now 58+ indicators (up from 55+)
  • Added 3 new pattern recognition indicators
  • All indicators support both class-based and function-based interfaces
  • Full TA-Lib style compatibility for consistency

Technical Details

• Pattern Indicators Integration: New indicators work seamlessly with existing async architecture
• Confluence Trading: Indicators designed to work together for higher probability setups
  • FVG + Order Block = High-probability support/resistance zones
  • WAE confirms momentum for FVG/OB trades
• Performance: All new indicators use efficient Polars operations for speed

[2.0.1] - 2025-01-31

Fixed

• 🐛 Import Organization: Reorganized indicator imports to resolve circular dependencies
• 📦 Package Structure: Improved module organization for better maintainability

[2.0.0] - 2025-01-30

Breaking Changes

• 🚀 Complete Async Migration: Entire SDK migrated from synchronous to asynchronous architecture
  • All public methods now require await keyword
  • Clients must use async with for proper resource management
  • No backward compatibility - clean async-only implementation
  • Aligns with CLAUDE.md directive for "No Backward Compatibility" during development

Added

• ✨ AsyncProjectX Client: New async-first client implementation

  • HTTP/2 support via httpx for improved performance
  • Concurrent API operations with proper connection pooling
  • Non-blocking I/O for all operations
  • Async context manager support for resource cleanup

• 📦 Dependencies: Added modern async libraries

  • httpx[http2]>=0.27.0 for async HTTP with HTTP/2 support
  • pytest-asyncio>=0.23.0 for async testing
  • aioresponses>=0.7.6 for mocking async HTTP

Changed

• 🔄 Migration Pattern: From sync to async

  # Old (Sync)
  client = ProjectX(api_key, username)
  client.authenticate()
  positions = client.get_positions()
  
  # New (Async)
  async with AsyncProjectX.from_env() as client:
      await client.authenticate()
      positions = await client.get_positions()
  

Performance Improvements

• ⚡ Concurrent Operations: Multiple API calls can now execute simultaneously
• 🚄 HTTP/2 Support: Reduced connection overhead and improved throughput
• 🔄 Non-blocking WebSocket: Real-time data processing without blocking other operations

Migration Notes

• This is a complete breaking change - all code using the SDK must be updated
• See tests/test_async_client.py for usage examples
• Phase 2-5 of async migration still pending (managers, real-time, etc.)

[1.1.4] - 2025-01-30

Fixed

• 📊 OrderBook Volume Accumulation: Fixed critical bug where market depth updates were accumulating volumes instead of replacing them

  • Market depth updates now correctly replace volume at price levels rather than adding to them
  • Resolved extremely high volume readings that were incorrect
  • Fixed handling of DomType 3/4 (BestBid/BestAsk) vs regular bid/ask updates

• 📈 OHLCV Volume Interpretation: Fixed misinterpretation of GatewayQuote volume field

  • GatewayQuote volume represents daily total, not individual trade volume
  • OHLCV bars now correctly show volume=0 for quote-based updates
  • Prevents unrealistic volume spikes (e.g., 29,000+ per 5-second bar)

• 🔍 Trade Classification: Improved trade side classification accuracy

  • Now captures bid/ask prices BEFORE orderbook update for correct classification
  • Uses historical spread data to properly classify trades as buy/sell
  • Added null handling for edge cases

Enhanced

• 🧊 Iceberg Detection: Added price level refresh history tracking

  • OrderBook now maintains history of volume updates at each price level
  • Tracks up to 50 updates per price level over 30-minute windows
  • Enhanced detect_iceberg_orders to use historical refresh patterns
  • Added get_price_level_history() method for analysis

• 📊 Market Structure Analysis: Refactored key methods to use price level history

  • get_support_resistance_levels: Now identifies persistent levels based on order refresh patterns
  • detect_order_clusters: Finds price zones with concentrated historical activity
  • get_liquidity_levels: Detects "sticky" liquidity that reappears after consumption
  • All methods now provide institutional-grade analytics based on temporal patterns

Added

• 🔧 Debug Scripts: New diagnostic tools for market data analysis
  • working_market_depth_debug.py: Comprehensive DOM type analysis
  • test_trade_classification.py: Verify trade side classification
  • test_enhanced_iceberg.py: Test iceberg detection with history
  • test_refactored_methods.py: Verify all refactored analytics

Technical Details

• Price level history stored as dict[tuple[float, str], list[dict]] with timestamp and volume
• Support/resistance now uses composite strength score (40% refresh count, 30% volume, 20% rate, 10% consistency)
• Order clusters detect "magnetic" price levels with persistent order placement
• Liquidity detection finds market maker zones with high refresh rates

[1.1.3] - 2025-01-29

Fixed

• 🔧 Contract Selection: Fixed _select_best_contract method to properly handle futures contract naming patterns
  • Extracts base symbols by removing month/year suffixes using regex (e.g., NQU5 → NQ, MGCH25 → MGC)
  • Handles both single-digit (U5) and double-digit (H25) year codes correctly
  • Prevents incorrect matches (searching "NQ" no longer returns "MNQ" contracts)
  • Prioritizes exact base symbol matches over symbolId suffix matching

Added

• 🎮 Interactive Instrument Demo: New example script for testing instrument search functionality
  • examples/09_get_check_available_instruments.py - Interactive command-line tool
  • Shows the difference between search_instruments() (all matches) and get_instrument() (best match)
  • Visual indicators for active contracts (★) and detailed contract information
  • Includes common symbols table and help command
  • Continuous search loop for testing multiple symbols

Enhanced

• 🧪 Test Coverage: Added comprehensive test suite for contract selection logic
  • Tests for exact base symbol matching with various contract patterns
  • Tests for handling different year code formats
  • Tests for selection priority order (active vs inactive)
  • Tests for edge cases (empty lists, no exact matches)
• 📚 Documentation: Updated README with development phase warnings
  • Added prominent development status warning
  • Noted that breaking changes may occur without backward compatibility
  • Updated changelog format to highlight the development phase

[1.1.2] - 2025-01-28

Enhanced

• 🚀 OrderBook Performance Optimization: Significant performance improvements for cluster detection
  • Dynamic Tick Size Detection: OrderBook now uses real instrument metadata from ProjectX client
  • Cached Instrument Data: Tick size fetched once during initialization, eliminating repeated API calls
  • Improved Cluster Analysis: More accurate price tolerance based on actual instrument tick sizes
  • Backward Compatibility: Maintains fallback to hardcoded values when client unavailable
• 🔧 Factory Function Updates: Enhanced create_orderbook() to accept ProjectX client reference
  • Better Integration: OrderBook now integrates seamlessly with ProjectX client architecture
  • Dependency Injection: Proper client reference passing for instrument metadata access

Fixed

• ⚡ API Call Reduction: Eliminated redundant get_instrument() calls during cluster detection
• 🎯 Price Tolerance Accuracy: Fixed hardcoded tick size assumptions with dynamic instrument lookup
• 📊 Consistent Analysis: OrderBook methods now use consistent, accurate tick size throughout lifecycle

[1.1.0] - 2025-01-27

Added

• 📊 Enhanced Project Structure: Updated documentation to accurately reflect current codebase
• 🔧 Documentation Accuracy: Aligned README.md and CHANGELOG.md with actual project state
• 📚 Example File Organization: Updated example file names to match actual structure

Fixed

• 📝 Version Consistency: Corrected version references throughout documentation
• 📂 Example File References: Updated README to reference actual example files
• 📅 Date Corrections: Fixed future date references in documentation

[1.0.12] - 2025-01-30

Added

• 🔄 Order-Position Synchronization: Automatic synchronization between orders and positions
  • Position Order Tracking: Orders automatically tracked and associated with positions
  • Dynamic Order Updates: Stop and target orders auto-adjust when position size changes
  • Position Close Handling: Related orders automatically cancelled when positions close
  • Bracket Order Integration: Full lifecycle tracking for entry, stop, and target orders
• 🧪 Comprehensive Test Suite: Expanded test coverage to 230+ tests
  • Phase 2-4 Testing: Complete test coverage for core trading and data features
  • Integration Tests: End-to-end workflow testing
  • Real-time Testing: Advanced real-time data and orderbook test coverage
  • Risk Management Tests: Comprehensive risk control validation

Enhanced

• 📊 Technical Indicators: Now 55+ indicators (up from 40+)
  • 17 Overlap Studies: Complete TA-Lib overlap indicator suite
  • 31 Momentum Indicators: Comprehensive momentum analysis tools
  • 3 Volatility Indicators: Advanced volatility measurement
  • 4 Volume Indicators: Professional volume analysis
• 🔧 Order Management: Enhanced order lifecycle management
  • Position Sync: Automatic order-position relationship management
  • Order Tracking: Comprehensive order categorization and tracking
  • Risk Integration: Seamless integration with risk management systems

Fixed

• 📝 Documentation: Updated version references and feature accuracy
• 🔢 Indicator Count: Corrected indicator count documentation (55+ actual vs 40+ claimed)
• 📋 Version Tracking: Restored complete changelog version history

[1.0.11] - 2025-01-30

Added

• 📈 Complete TA-Lib Overlap Indicators: All 17 overlap indicators implemented
  • HT_TRENDLINE: Hilbert Transform Instantaneous Trendline
  • KAMA: Kaufman Adaptive Moving Average with volatility adaptation
  • MA: Generic Moving Average with selectable types
  • MAMA: MESA Adaptive Moving Average with fast/slow limits
  • MAVP: Moving Average with Variable Period support
  • MIDPRICE: Midpoint Price using high/low ranges
  • SAR/SAREXT: Parabolic SAR with standard and extended parameters
  • T3: Triple Exponential Moving Average with volume factor
  • TRIMA: Triangular Moving Average with double smoothing

Enhanced

• 🔍 Indicator Discovery: Enhanced helper functions for exploring indicators
• 📚 Documentation: Comprehensive indicator documentation and examples
• 🎯 TA-Lib Compatibility: Full compatibility with TA-Lib function signatures

[1.0.10] - 2025-01-30

Added

• ⚡ Performance Optimizations: Major performance improvements
  • Connection Pooling: 50-70% reduction in API overhead
  • Intelligent Caching: 80% reduction in repeated API calls
  • Memory Management: 60% memory usage reduction with sliding windows
  • DataFrame Optimization: 30-40% faster operations

Enhanced

• 🚀 Real-time Performance: Sub-second response times for cached operations
• 📊 WebSocket Efficiency: 95% reduction in polling with real-time feeds

[1.0.0] - 2025-01-29

Added

• 🎯 Production Release: First stable production release
• 📊 Level 2 Orderbook: Complete market microstructure analysis
• 🔧 Enterprise Features: Production-grade reliability and monitoring

Migration to v1.0.0

Major version bump indicates production readiness and API stability.

[0.4.0] - 2025-01-29

Added

• 📊 Advanced Market Microstructure: Enhanced orderbook analysis
  • Iceberg Detection: Statistical confidence-based hidden order identification
  • Order Flow Analysis: Buy/sell pressure detection and trade flow metrics
  • Volume Profile: Point of Control and Value Area calculations
  • Market Imbalance: Real-time imbalance detection and alerts
  • Support/Resistance: Dynamic level identification from order flow
• 🔧 Enhanced Architecture: Improved component design and performance

[0.3.0] - 2025-01-29

Added

• 🎯 Comprehensive Technical Indicators Library: Complete TA-Lib compatible indicator suite
  • 25+ Technical Indicators: All major categories covered
  • Overlap Studies: SMA, EMA, BBANDS, DEMA, TEMA, WMA, MIDPOINT
  • Momentum Indicators: RSI, MACD, STOCH, WILLR, CCI, ROC, MOM, STOCHRSI
  • Volatility Indicators: ATR, ADX, NATR, TRANGE, ULTOSC
  • Volume Indicators: OBV, VWAP, AD, ADOSC
  • Dual Interface: Class-based and function-based (TA-Lib style) usage
  • Polars-Native: Built specifically for Polars DataFrames
  • Discovery Tools: get_all_indicators(), get_indicator_groups(), get_indicator_info()
• 📊 Level 2 Orderbook & Market Microstructure Analysis (Production Ready):
  • Institutional-Grade Orderbook Processing: Full market depth analysis
  • Iceberg Detection: Hidden order identification with statistical confidence
  • Order Flow Analysis: Buy/sell pressure detection and trade flow metrics
  • Volume Profile: Point of Control and Value Area calculations
  • Market Imbalance: Real-time imbalance detection and alerts
  • Support/Resistance: Dynamic level identification from order flow
  • Liquidity Analysis: Significant price level detection
  • Cumulative Delta: Net buying/selling pressure tracking
  • Order Clustering: Price level grouping and institutional flow detection
• 📈 Enhanced Portfolio & Risk Analysis:
  • Portfolio performance metrics with Sharpe ratio and max drawdown
  • Advanced position sizing algorithms
  • Risk/reward ratio calculations
  • Volatility metrics and statistical analysis
• 🔧 Base Indicator Framework:
  • BaseIndicator, OverlapIndicator, MomentumIndicator, VolatilityIndicator, VolumeIndicator
  • Consistent validation and error handling across all indicators
  • Utility functions: ema_alpha(), safe_division(), rolling calculations

Enhanced

• 📚 Comprehensive Documentation: Updated README with accurate feature representation
  • Complete technical indicators reference with examples
  • Level 2 orderbook usage examples
  • Multi-timeframe analysis strategies
  • Portfolio management and risk analysis guides
• 🎨 Code Quality: Professional indicator implementations
  • Full type hints throughout indicator library
  • Consistent error handling and validation
  • Memory-efficient Polars operations
  • Clean separation of concerns

Fixed

• 🔧 GitHub Actions: Updated deprecated artifact actions from v3 to v4
  • actions/upload-artifact@v3 → actions/upload-artifact@v4
  • actions/download-artifact@v3 → actions/download-artifact@v4
• 📝 Documentation: Corrected feature status in README
  • Level 2 orderbook marked as production-ready (not development)
  • Market microstructure analysis properly categorized
  • Accurate representation of implemented vs planned features

Dependencies

• Core: No new required dependencies
• Existing: Compatible with current Polars, pytz, requests versions
• Optional: All existing optional dependencies remain the same

Migration from v0.2.0

# New technical indicators usage
from project_x_py.indicators import RSI, SMA, MACD, BBANDS

# Class-based interface
rsi = RSI()
data_with_rsi = rsi.calculate(data, period=14)

# TA-Lib style functions
data = RSI(data, period=14)
data = SMA(data, period=20)
data = BBANDS(data, period=20, std_dev=2.0)

# Level 2 orderbook analysis
from project_x_py import OrderBook
orderbook = OrderBook("MGC")
advanced_metrics = orderbook.get_advanced_market_metrics()

# Discover available indicators
from project_x_py.indicators import get_all_indicators, get_indicator_groups
print("Available indicators:", get_all_indicators())

[0.2.0] - 2025-01-28

Added

• Modular Architecture: Split large monolithic file into logical modules
  • client.py - Main ProjectX client class
  • models.py - Data models and configuration
  • exceptions.py - Custom exception hierarchy
  • utils.py - Utility functions and helpers
  • config.py - Configuration management
• Enhanced Error Handling: Comprehensive exception hierarchy with specific error types
  • ProjectXAuthenticationError for auth failures
  • ProjectXServerError for 5xx errors
  • ProjectXRateLimitError for rate limiting
  • ProjectXConnectionError for network issues
  • ProjectXDataError for data validation errors
• Configuration Management:
  • Environment variable support with PROJECTX_* prefix
  • JSON configuration file support
  • Default configuration with overrides
  • Configuration validation and templates
• Professional Package Structure:
  • Proper pyproject.toml with optional dependencies
  • Comprehensive README with examples
  • MIT license
  • Test framework setup with pytest
  • Development tools configuration (ruff, mypy, black)
• Enhanced API Design:
  • Factory methods: ProjectX.from_env(), ProjectX.from_config_file()
  • Improved type hints throughout
  • Better documentation and examples
  • Consistent error handling patterns
• Utility Functions:
  • setup_logging() for consistent logging
  • get_env_var() for environment variable handling
  • format_price() and format_volume() for display
  • is_market_hours() for market timing
  • RateLimiter class for API rate limiting

Changed

• Breaking: Restructured package imports - use from project_x_py import ProjectX instead of importing from __init__.py
• Breaking: Configuration now uses ProjectXConfig dataclass instead of hardcoded values
• Improved: Better error messages with specific exception types
• Enhanced: Client initialization with lazy authentication
• Updated: Package metadata and PyPI classifiers

Improved

• Documentation: Comprehensive README with installation, usage, and examples
• Code Quality: Improved type hints, docstrings, and code organization
• Testing: Basic test framework with pytest fixtures and mocks
• Development: Better development workflow with linting and formatting tools

Dependencies

• Core: polars>=1.31.0, pytz>=2025.2, requests>=2.32.4
• Optional Realtime: signalrcore>=0.9.5, websocket-client>=1.0.0
• Development: pytest, ruff, mypy, black, isort

[0.1.0] - 2025-01-01

Added

• Initial release with basic trading functionality
• ProjectX Gateway API client
• Real-time data management via WebSocket
• Order placement, modification, and cancellation
• Position and trade management
• Historical market data retrieval
• Multi-timeframe data synchronization

Features

• Authentication with TopStepX API
• Account management
• Instrument search and contract details
• OHLCV historical data with polars DataFrames
• Real-time market data streams
• Level 2 market depth data
• Comprehensive logging

---

Release Notes

Upgrading to v0.2.0

If you're upgrading from v0.1.0, please note the following breaking changes:

1. Import Changes:

   # Old (v0.1.0)
   from project_x_py import ProjectX
   
   # New (v0.2.0) - same import, but underlying structure changed
   from project_x_py import ProjectX  # Still works
   

2. Environment Variables:

   # Required (same as before)
   export PROJECT_X_API_KEY="your_api_key"
   export PROJECT_X_USERNAME="your_username"
   
   # New optional configuration variables
   export PROJECTX_API_URL="https://api.topstepx.com/api"
   export PROJECTX_TIMEOUT_SECONDS="30"
   export PROJECTX_RETRY_ATTEMPTS="3"
   

3. Client Initialization:

   # Recommended new approach
   client = ProjectX.from_env()  # Uses environment variables
   
   # Or with explicit credentials (same as before)
   client = ProjectX(username="user", api_key="key")
   
   # Or with custom configuration
   config = ProjectXConfig(timeout_seconds=60)
   client = ProjectX.from_env(config=config)
   

4. Error Handling:

   # New specific exception types
   try:
       client = ProjectX.from_env()
       account = client.get_account_info()
   except ProjectXAuthenticationError:
       print("Authentication failed")
   except ProjectXServerError:
       print("Server error")
   except ProjectXError:
       print("General ProjectX error")
   

Migration Guide

1. Update imports: No changes needed - existing imports still work
2. Update error handling: Consider using specific exception types
3. Use new factory methods: ProjectX.from_env() is now recommended
4. Optional: Set up configuration file for advanced settings
5. Optional: Use new utility functions for logging and formatting

New Installation Options

# Basic installation (same as before)
pip install project-x-py

# With real-time features
pip install project-x-py[realtime]

# With development tools
pip install project-x-py[dev]

# Everything
pip install project-x-py[all]