ProjectX Python SDK

A high-performance async Python SDK for the ProjectX Trading Platform Gateway API. This library enables developers to build sophisticated trading strategies and applications by providing comprehensive async access to futures trading operations, historical market data, real-time streaming, technical analysis, and advanced market microstructure tools with enterprise-grade performance optimizations.

Note: This is a client library/SDK, not a trading strategy. It provides the tools and infrastructure to help developers create their own trading strategies that integrate with the ProjectX platform.

🎯 What is ProjectX?

ProjectX is a cutting-edge web-based futures trading platform that provides:

• TradingView Charts: Advanced charting with hundreds of indicators
• Risk Controls: Auto-liquidation, profit targets, daily loss limits
• Unfiltered Market Data: Real-time depth of market data with millisecond updates
• REST API: Comprehensive API for custom integrations
• Mobile & Web Trading: Native browser-based trading platform

This Python SDK acts as a bridge between your trading strategies and the ProjectX platform, handling all the complex API interactions, data processing, and real-time connectivity.

🚀 v3.5.8 - DateTime Parsing Fix for Mixed Timestamp Formats

Latest Version: v3.5.8 - Fixed critical datetime parsing error when API returns mixed timestamp formats, ensuring reliable market data retrieval across all scenarios.

Key Improvements:

• 🕐 Robust DateTime Parsing: Handles all timestamp formats (with/without timezone info)
• ⚡ Performance Optimized: Fast path for 95% of cases, with intelligent fallbacks
• 🔄 Zero Breaking Changes: Fully backward compatible implementation
• 🧪 Test Stability: Fixed flaky performance tests for reliable CI/CD
• 📊 TradingSuite Compatible: Ensures smooth initialization with mixed data formats

See CHANGELOG.md for complete v3.5.8 fixes and previous version features.

📦 Production Stability Guarantee

Since v3.1.1, this project maintains:

• ✅ Backward compatibility between minor versions
• ✅ Deprecation warnings for at least 2 minor versions before removal
• ✅ Breaking changes only in major releases (4.0.0+)
• ✅ Strict semantic versioning (MAJOR.MINOR.PATCH)

Key Features

• TradingSuite Class: Unified entry point for simplified SDK usage
• One-line Initialization: TradingSuite.create() handles all setup
• Feature Flags: Easy enabling of optional components
• Context Manager Support: Automatic cleanup with async with statements
• Unified Event Handling: Built-in EventBus for all components
• Performance Optimized: Connection pooling, caching, and WebSocket batching
• Memory Management: Automatic overflow to disk with transparent access

Why Async?

• Concurrent Operations: Execute multiple API calls simultaneously
• Non-blocking I/O: Handle real-time data feeds without blocking
• Better Resource Usage: Single thread handles thousands of concurrent operations
• WebSocket Native: Perfect for real-time trading applications
• Modern Python: Leverages Python 3.12+ async features

Migration to v3.0+

If you're upgrading from v2.x, key changes include TradingSuite replacing factories:

# Old (v2.x)
suite = await create_initialized_trading_suite(\"MNQ\", client)

# New (v3.0+)
suite = await TradingSuite.create(\"MNQ\")

✨ Key Features

Core Trading Operations (All Async)

• Authentication & Account Management: Multi-account support with async session management
• Order Management: Place, modify, cancel orders with real-time async updates
• Position Tracking: Real-time position monitoring with P&L calculations
• Market Data: Historical and real-time data with async streaming
• Risk Management: Portfolio analytics and risk metrics

Advanced Features

• 59+ Technical Indicators: Full TA-Lib compatibility with Polars optimization including new pattern indicators
• Level 2 OrderBook: Depth analysis, iceberg detection, spoofing detection with 6 pattern types
• Real-time WebSockets: Async streaming for quotes, trades, and account updates
• Performance Optimized: Connection pooling, intelligent caching, memory management
• Pattern Recognition: Fair Value Gaps, Order Blocks, Waddah Attar Explosion, and Lorenz Formula indicators
• Market Manipulation Detection: Advanced spoofing detection with confidence scoring
• Financial Precision: All calculations use Decimal type for exact precision
• Enterprise Error Handling: Production-ready error handling with decorators and structured logging
• Comprehensive Type Safety: Full TypedDict and Protocol definitions for IDE support and static analysis
• Advanced Statistics & Analytics: 100% async-first statistics system with comprehensive health monitoring and performance tracking
• Multi-format Export: Statistics export in JSON, Prometheus, CSV, and Datadog formats with data sanitization
• Component-Specific Tracking: Enhanced statistics for OrderManager, PositionManager, OrderBook, and more
• Health Monitoring: Intelligent 0-100 health scoring with configurable thresholds and degradation detection
• Performance Optimization: TTL caching, parallel collection, and circular buffers for memory efficiency
• Comprehensive Testing: 1,300+ tests with complete code quality compliance and extensive TDD methodology

📦 Installation

Using UV (Recommended)

uv add project-x-py

Using pip

pip install project-x-py

Development Installation

git clone https://github.com/yourusername/project-x-py.git
cd project-x-py
uv sync  # or: pip install -e ".[dev]"

🚀 Quick Start

Basic Usage

import asyncio
from project_x_py import TradingSuite

async def main():
    suite = await TradingSuite.create(\"MNQ\")

    print(f\"Connected to account: {suite.client.account_info.name}\")

    # Get instrument info if needed
    instrument = await suite.client.get_instrument(suite.instrument_id or \"MNQ\")
    print(f\"Trading {instrument.name} - Tick size: ${instrument.tickSize}\")

    data = await suite.client.get_bars(\"MNQ\", days=5)
    print(f\"Retrieved {len(data)} bars\")

    positions = await suite.positions.get_all_positions()
    for position in positions:
        print(f\"Position: {position.size} @ ${position.averagePrice}\")

    # New v3.3.0: Get comprehensive statistics (async-first API)
    stats = await suite.get_stats()
    print(f\"System Health: {stats['health_score']:.1f}/100\")
    print(f\"Total API Calls: {stats['total_api_calls']}\")
    print(f\"Memory Usage: {stats['memory_usage_mb']:.1f} MB\")

    # Export statistics to multiple formats
    prometheus_metrics = await suite.export_stats(\"prometheus\")
    csv_data = await suite.export_stats(\"csv\")

    await suite.disconnect()

if __name__ == \"__main__\":
    asyncio.run(main())

Multi-Instrument Trading (NEW in v3.5.0)

Manage multiple instruments simultaneously for advanced trading strategies:

import asyncio
from project_x_py import TradingSuite

async def multi_instrument_example():
    # Multi-instrument setup - trade multiple futures simultaneously
    suite = await TradingSuite.create(
        instruments=["MNQ", "ES", "MGC"],  # E-mini NASDAQ, S&P 500, Gold
        timeframes=["1min", "5min"],
        enable_orderbook=True,
        enable_risk_management=True
    )

    print(f"Managing {len(suite)} instruments: {list(suite.keys())}")

    # Access specific instruments via dictionary-like interface
    mnq_context = suite["MNQ"]
    es_context = suite["ES"]
    mgc_context = suite["MGC"]

    # Get current prices for all instruments
    for symbol, context in suite.items():
        current_price = await context.data.get_current_price()
        print(f"{symbol}: ${current_price:.2f}")

    # Execute pairs trading strategy (ES vs MNQ correlation)
    es_data = await es_context.data.get_data("5min", bars=100)
    mnq_data = await mnq_context.data.get_data("5min", bars=100)

    # Analyze spread between ES and MNQ for pairs trading
    es_price = es_data.select("close").to_series().to_list()[-1]
    mnq_price = mnq_data.select("close").to_series().to_list()[-1]
    spread = es_price * 50 - mnq_price * 20  # Contract value normalized

    print(f"ES/MNQ Spread: ${spread:.2f}")

    # Portfolio-level position management
    total_exposure = 0
    for symbol, context in s