v3.5.7: Fix Decimal JSON serialization in order placement

[TexasCoding]

• Fixed JSON serialization error when placing orders with Decimal prices
• Convert Decimal prices to float for API requests while maintaining internal precision
• Added comprehensive documentation examples in Documentation_Examples/
• Updated all version references to v3.5.7 in README, CHANGELOG, and docs
• Verified all examples work with the fixed serialization

🤖 Generated with Claude Code

[claude]

Claude finished @TexasCoding's task —— View job

---

PR Review: v3.5.7 Decimal JSON Serialization Fix

Review Checklist:

• Analyze core serialization fix in order_manager/core.py
• Review test coverage for the serialization changes
• Examine new documentation examples for quality and best practices
• Check version consistency across all updated files
• Assess security implications of Decimal to float conversion
• Evaluate performance considerations
• Provide comprehensive feedback and recommendations

---

Overall Assessment: ✅ Well-Executed Fix

This PR successfully addresses a critical JSON serialization issue while maintaining code quality and adding valuable documentation. The changes are well-tested and properly versioned.

Code Quality & Best Practices: ✅ Excellent

Core Fix (order_manager/core.py:529-537)

Strengths:

• Clean serialization solution: The conversion from Decimal to float is performed at the exact point of JSON serialization while preserving internal Decimal precision throughout calculations
• Strategic placement: Conversion happens in the payload construction, maintaining type safety in all internal operations
• Consistent pattern: Applied uniformly across limitPrice, stopPrice, and trailPrice fields
• Well-documented intent: Clear comments explain the serialization conversion purpose

Technical Implementation:

"limitPrice": float(aligned_limit_price) if aligned_limit_price is not None else None,
"stopPrice": float(aligned_stop_price) if aligned_stop_price is not None else None,
"trailPrice": float(aligned_trail_price) if aligned_trail_price is not None else None,

This approach maintains the benefits of Decimal arithmetic while ensuring API compatibility.

Test Coverage: ✅ Comprehensive

Strong Test Coverage

• Serialization verification: Tests confirm that API requests receive proper float values (lines 253-255)
• Precision maintenance: Tests verify that Decimal precision is preserved internally before conversion
• Edge cases: Includes null value handling and type validation
• Regression protection: Tests ensure the fix doesn't break existing functionality

The test validates the exact behavior:

assert call_args.get("limitPrice") == float(Decimal('100.78'))

Documentation Examples: ✅ High Quality

New Documentation Structure

• Well-organized: Clear directory structure under Documentation_Examples/
• Progressive complexity: From simple single instrument to multi-instrument trading
• Practical examples: Real-world usage patterns with proper async/await handling
• Modern patterns: Uses recommended TradingSuite approach (v3.x standards)

Example Quality Assessment:

• Proper error handling: Examples check for null values and handle exceptions
• Resource management: Consistent use of await suite.disconnect()
• Clear documentation: Good comments explaining key concepts
• Best practices: Uses context access patterns (suite["MNQ"])

Security Considerations: ✅ Secure

No Security Issues Identified

• No credential exposure: Examples properly use environment-based authentication
• Controlled conversion: Decimal-to-float conversion is safe and reversible within trading precision
• Input validation: Maintains existing validation of price and size parameters
• No injection risks: All values are properly typed and validated

Financial Precision Analysis

• Acceptable precision loss: Float precision (15-17 significant digits) is sufficient for financial prices
• Tick alignment: Prices are aligned to instrument tick sizes before conversion, minimizing precision concerns
• Internal precision: Decimal arithmetic is preserved for internal calculations until final API serialization

Performance Considerations: ✅ Optimized

Performance Impact Analysis

• Minimal overhead: Float conversion adds negligible computational cost
• Memory efficient: No significant memory footprint changes
• Serialization improvement: Eliminates JSON serialization errors that could cause retries
• Network optimization: Cleaner JSON payloads reduce parsing overhead

No Performance Regressions

• Existing alignment and validation logic unchanged
• Caching and connection pooling remain intact
• Real-time processing unaffected

Version Consistency: ✅ Complete

Comprehensive Version Updates

All references properly updated to v3.5.7 across:

• ✅ pyproject.toml (line 3)
• ✅ src/project_x_py/__init__.py (line 112)
• ✅ src/project_x_py/indicators/__init__.py (line 210)
• ✅ README.md - Multiple references
• ✅ CHANGELOG.md - Proper semantic versioning
• ✅ Documentation files - Consistent version references

Potential Improvements & Recommendations

Minor Enhancement Opportunities

1. Type hints: Consider adding explicit type hints for the float conversion:

   "limitPrice": float(aligned_limit_price) if aligned_limit_price is not None else None

2. Documentation enhancement: Could add a docstring comment explaining the Decimal→float conversion rationale

3. Logging consideration: Could add debug logging for the conversion process (very minor)

Future Considerations

• JSON encoder: For future iterations, consider a custom JSON encoder that handles Decimal automatically
• Configuration option: Could potentially make precision handling configurable, though current approach is likely optimal

Summary

This is a high-quality fix that addresses a real production issue with minimal risk. The implementation is clean, well-tested, and properly documented. The serialization fix is exactly what's needed—preserving internal precision while ensuring API compatibility.

Recommendation: ✅ Approve - This PR demonstrates excellent software engineering practices with a focused fix, comprehensive testing, and valuable documentation additions.

---

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!