feat(orderbook): implement dynamic tick size detection with client integration

- Add optional ProjectX client parameter to OrderBook constructor
- Implement _fetch_instrument_tick_size() method for cached instrument metadata
- Enhance _calculate_price_tolerance() to use cached tick size (3x multiplier)
- Update create_orderbook() factory function to accept project_x parameter
- Eliminate repeated get_instrument() API calls during cluster detection
- Maintain backward compatibility with fallback to hardcoded tick sizes

Performance improvements:
- Single API call during initialization vs repeated calls per method
- Cached tick size ensures consistent analysis throughout lifecycle
- Accurate price tolerance based on real instrument metadata

Updated documentation:
- README.md: Enhanced OrderBook section with client integration example
- CHANGELOG.md: Added v1.1.2 release notes
- docs/api/orderbook.rst: Updated Quick Start with proper initialization

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Author: TexasCoding

.gitignore

@@ -2,7 +2,7 @@
 __pycache__/
 *.py[cod]
 *$py.class
-
+.grok/settings.json
 # C extensions
 *.so
 

.grok/GROK.md

@@ -0,0 +1,60 @@
+# GROK.md
+
+This file provides guidance to Grok CLI (x.ai/grok) when assisting with file editing, coding tasks, and system operations in this repository.
+
+## Project Overview
+This is a Python SDK/client library for the ProjectX Trading Platform Gateway API. It enables developers to build trading strategies with access to real-time market data, order management, and analysis using Polars for high-performance data processing.
+
+**Note**: Focus on toolkit development, not on creating trading strategies.
+
+## Tool Usage Guidelines
+As Grok CLI, you have access to tools like view_file, create_file, str_replace_editor, bash, search, and todo lists. Use them efficiently for tasks.
+
+- **ALWAYS** create a todo list for complex tasks.
+- **NEVER** overwrite existing files with create_file; use str_replace_editor.
+- **ALWAYS** view files before editing.
+- For searches, use the search tool or bash commands like grep.
+
+## Development Commands
+Use bash tool to execute these:
+
+### Package Management (UV)
+uv add [package]              # Add a dependency
+uv add --dev [package]        # Add a development dependency
+uv sync                       # Install/sync dependencies
+uv run [command]              # Run command in virtual environment
+
+### Testing
+uv run pytest                # Run all tests
+uv run pytest tests/test_client.py  # Run specific test file
+
+### Code Quality
+uv run ruff check .          # Lint code
+uv run ruff check . --fix    # Auto-fix linting issues
+uv run ruff format .         # Format code
+uv run mypy src/             # Type checking
+
+## Project Architecture
+Refer to CLAUDE.md for details, but when editing:
+- Use dependency injection in clients and managers.
+- Handle real-time data with WebSockets.
+- Ensure thread safety with locks.
+
+## Coding Rules for Edits
+When using str_replace_editor:
+- **ALWAYS** use modern Python 3.10+ features.
+- **PREFER** Polars over Pandas.
+- **ALWAYS** add type hints using | for unions.
+- **HANDLE** errors with custom exceptions.
+
+## Performance Considerations
+- Implement memory management in edits (e.g., sliding windows).
+- Optimize DataFrame operations with chaining and lazy evaluation.
+
+## Integration with ProjectX API
+- Use configurable endpoints.
+- Validate payloads strictly.
+- Map enums correctly.
+
+For any updates, ensure consistency with .cursorrules and CLAUDE.md.
+

CHANGELOG.md

@@ -5,6 +5,23 @@ All notable changes to the ProjectX Python client will be documented in this fil
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [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

README.md

@@ -22,13 +22,13 @@ This Python SDK acts as a bridge between your trading strategies and the Project
 
 ## 📊 SDK Status
 
-**Current Version**: v1.1.1 (Documentation Accuracy & Enhanced Project Structure)
+**Current Version**: v1.1.2 (Documentation Accuracy & Enhanced Project Structure)
 
 ✅ **Production Ready SDK Components**:
 - Complete ProjectX Gateway API integration with connection pooling
 - Historical and real-time market data APIs with intelligent caching
 - 55+ technical indicators with computation caching (Full TA-Lib compatibility)
-- Institutional-grade orderbook analysis tools with memory management
+- Institutional-grade orderbook analysis tools with memory management and dynamic tick size detection
 - Portfolio and risk management APIs
 - **NEW**: 50-70% performance improvements through optimization
 - **NEW**: 60% memory usage reduction with sliding windows
@@ -296,10 +296,11 @@ for order in orders:
 
 ### Level 2 Market Depth Analysis
 ```python
-from project_x_py import create_orderbook
+from project_x_py import create_orderbook, ProjectX
 
-# Create orderbook with memory management
-orderbook = create_orderbook("MGC")
+# Create orderbook with dynamic tick size detection
+client = ProjectX.from_env()
+orderbook = create_orderbook("MGC", project_x=client)  # Uses real instrument metadata
 
 # Process market depth data (automatically from WebSocket)
 depth_snapshot = orderbook.get_orderbook_snapshot()
@@ -605,7 +606,7 @@ We welcome contributions! Please follow these guidelines:
 
 ## 📝 Changelog
 
-### Version 1.1.1 (Latest)
+### Version 1.1.2 (Latest)
 **📊 Documentation Accuracy & Enhanced Project Structure**
 - ✅ **Documentation Alignment**: Updated all documentation to match actual codebase
 - ✅ **Version Consistency**: Corrected version references throughout project

docs/api/orderbook.rst

@@ -21,11 +21,11 @@ Quick Start
 
 .. code-block:: python
 
-   from project_x_py import ProjectX, OrderBook
+   from project_x_py import ProjectX, create_orderbook
    
-   # Create client and orderbook
+   # Create client and orderbook with dynamic tick size detection
    client = ProjectX.from_env()
-   orderbook = OrderBook("MGC")
+   orderbook = create_orderbook("MGC", project_x=client)  # Uses real instrument metadata
    
    # Get real-time market depth (requires real-time data subscription)
    snapshot = orderbook.get_orderbook_snapshot(levels=10)

docs/conf.py

@@ -3,7 +3,6 @@
 # For the full list of built-in configuration values, see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
-import os
 import sys
 from pathlib import Path
 
@@ -24,8 +23,8 @@
 project = "project-x-py"
 copyright = "2025, Jeff West"
 author = "Jeff West"
-release = "1.1.1"
-version = "1.1.1"
+release = "1.1.2"
+version = "1.1.2"
 
 # -- General configuration ---------------------------------------------------
 
@@ -199,7 +198,7 @@
 
 # SEO
 html_title = f"ProjectX Python SDK {version} documentation"
-html_short_title = f"ProjectX Python SDK docs"
+html_short_title = "ProjectX Python SDK docs"
 
 # GitHub integration
 html_context = {

examples/04_realtime_data.py

@@ -229,13 +229,10 @@ def monitor_realtime_feed(data_manager, duration_seconds=60):
                 # Health check
                 try:
                     health = data_manager.health_check()
-                    if health.get("status") == "healthy":
+                    if health:
                         print("   ✅ System Health: Good")
                     else:
-                        issues = health.get("issues", [])
                         print("   ⚠️  System Health: Issues detected")
-                        for issue in issues:
-                            print(f"     • {issue}")
                 except Exception as e:
                     print(f"   ❌ Health check error: {e}")
 
@@ -265,6 +262,10 @@ def main():
     print("🚀 Real-time Data Streaming Example")
     print("=" * 60)
 
+    # Initialize variables for cleanup
+    data_manager = None
+    realtime_client = None
+
     try:
         # Initialize client
         print("🔑 Initializing ProjectX client...")
@@ -286,6 +287,16 @@ def main():
         try:
             jwt_token = client.get_session_token()
             realtime_client = create_realtime_client(jwt_token, str(account.id))
+
+            # Connect the realtime client
+            print("   Connecting to real-time WebSocket feeds...")
+            if realtime_client.connect():
+                print("   ✅ Real-time client connected successfully")
+            else:
+                print(
+                    "   ⚠️ Real-time client connection failed - continuing with limited functionality"
+                )
+
             data_manager = create_data_manager(
                 instrument="MNQ",
                 project_x=client,
@@ -451,14 +462,22 @@ def main():
         return False
     finally:
         # Cleanup
-        if "data_manager" in locals():
+        if data_manager is not None:
             try:
                 print("\n🧹 Stopping real-time feed...")
                 data_manager.stop_realtime_feed()
                 print("✅ Real-time feed stopped")
             except Exception as e:
                 print(f"⚠️  Stop feed warning: {e}")
 
+        if realtime_client is not None:
+            try:
+                print("🧹 Disconnecting real-time client...")
+                realtime_client.disconnect()
+                print("✅ Real-time client disconnected")
+            except Exception as e:
+                print(f"⚠️  Disconnect warning: {e}")
+
 
 if __name__ == "__main__":
     success = main()