{"id":30719957,"url":"https://github.com/texascoding/trend-momentum-x","last_synced_at":"2025-09-03T10:43:01.497Z","repository":{"id":309053486,"uuid":"1035016839","full_name":"TexasCoding/trend-momentum-x","owner":"TexasCoding","description":null,"archived":false,"fork":false,"pushed_at":"2025-08-13T10:40:01.000Z","size":3009,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-02T09:49:31.228Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TexasCoding.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-09T13:30:52.000Z","updated_at":"2025-09-02T02:23:55.000Z","dependencies_parsed_at":"2025-08-09T15:29:12.637Z","dependency_job_id":"39a18298-540a-4f2b-a96f-2116cda167a8","html_url":"https://github.com/TexasCoding/trend-momentum-x","commit_stats":null,"previous_names":["texascoding/trend-momentum-x"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/TexasCoding/trend-momentum-x","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TexasCoding%2Ftrend-momentum-x","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TexasCoding%2Ftrend-momentum-x/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TexasCoding%2Ftrend-momentum-x/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TexasCoding%2Ftrend-momentum-x/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TexasCoding","download_url":"https://codeload.github.com/TexasCoding/trend-momentum-x/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TexasCoding%2Ftrend-momentum-x/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273431373,"owners_count":25104496,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-03T02:00:09.631Z","response_time":76,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-09-03T10:43:00.581Z","updated_at":"2025-09-03T10:43:01.485Z","avatar_url":"https://github.com/TexasCoding.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TrendMomentumX Trading Strategy\n\nA multi-timeframe trend-aligned momentum breakout strategy for futures trading, powered by [Project X](https://www.projectx.com/) and built with [project-x-py](https://github.com/TexasCoding/project-x-py).\n\n## Overview\n\nTrendMomentumX is a sophisticated algorithmic trading strategy that combines multi-timeframe analysis with momentum indicators and order book confirmation. Built exclusively on the Project X trading framework through its Python SDK ([project-x-py](https://texascoding.github.io/project-x-py/)), this strategy is designed for futures trading with a focus on ES (E-mini S\u0026P 500) and NQ (Nasdaq-100) contracts.\n\n## Features\n\n- **Multi-Timeframe Analysis**: 15-second base timeframe with 1-minute, 5-minute, and 15-minute trend verification\n- **Advanced Signal Generation**: RSI, Waddah Attar Explosion (WAE), Fair Value Gaps (FVG), and Order Blocks\n- **Level 2 OrderBook Confirmation**: Real-time bid-ask imbalance analysis and iceberg order detection\n- **Risk Management**: Dynamic position sizing, stop-loss, take-profit, and trailing stops using Parabolic SAR\n- **24/5 Operation**: Designed for continuous futures market operation with robust error handling\n- **Modern Python**: Built with Python 3.12+ using async/await patterns and type hints\n\n## Project X Integration\n\nThis strategy leverages the full power of [Project X](https://www.projectx.com/), a comprehensive trading framework that provides:\n- Real-time WebSocket data feeds\n- Level 2 order book analysis\n- Advanced technical indicators optimized with Polars DataFrames\n- Unified order management system\n- Risk management tools\n\nAll trading functionality is provided through [project-x-py](https://github.com/TexasCoding/project-x-py), the official Python SDK for Project X.\n\n## Installation\n\n### Prerequisites\n\n- Python 3.12 or higher\n- [uv](https://github.com/astral-sh/uv) package manager (recommended)\n\n### Setup\n\n1. Clone the repository:\n```bash\ngit clone https://github.com/yourusername/trend-momentum-x.git\ncd trend-momentum-x\n```\n\n2. Install dependencies using uv:\n```bash\nuv sync\n```\n\nOr with pip:\n```bash\npip install -r requirements.txt\n```\n\n## Configuration\n\n### Environment Variables\n\nCreate a `.env` file in the project root or set environment variables:\n\n```bash\n# Project X Authentication\nPROJECT_X_API_KEY=your_api_key\nPROJECT_X_API_SECRET=your_api_secret\n\n# Trading Configuration\nINSTRUMENT=ES                    # Trading instrument (ES, NQ, etc.)\nTRADING_MODE=paper               # paper or live\nRISK_PER_TRADE=0.005            # 0.5% risk per trade\nMAX_DAILY_LOSS=0.03             # 3% daily loss limit\nMAX_WEEKLY_LOSS=0.05            # 5% weekly loss limit\nMAX_CONCURRENT_TRADES=3         # Maximum concurrent positions\n\n# Technical Parameters\nRSI_PERIOD=14\nRSI_OVERSOLD=30\nRSI_OVERBOUGHT=70\nWAE_SENSITIVITY=150\nVOLUME_THRESHOLD_PERCENT=0.2\n\n# OrderBook Parameters\nIMBALANCE_LONG_THRESHOLD=1.5\nIMBALANCE_SHORT_THRESHOLD=0.6667\nORDERBOOK_DEPTH_LEVELS=5\n```\n\n## Usage\n\n### Development Commands\n\n```bash\n# Validate project-x-py API usage (run this first)\nuv run python validate_api_usage.py\n\n# Run linting\nuv run ruff check\n\n# Run type checking\nuv run mypy .\n\n# Format code\nuv run ruff format\n\n# Run tests\nuv run pytest\n\n# Run tests with coverage (91% coverage achieved)\nuv run pytest --cov=strategy --cov-report=html\n```\n\n### Running the Strategy\n\n#### Paper Trading (Recommended First)\n```bash\nuv run python main.py\n```\n\n#### Live Trading (Use with Caution)\n```bash\nTRADING_MODE=live uv run python main.py\n```\n\n#### Custom Configuration\n```bash\nINSTRUMENT=NQ RISK_PER_TRADE=0.01 uv run python main.py\n```\n\n## Strategy Logic\n\n### Entry Conditions\n\n**Long Entry Requirements:**\n1. All timeframes aligned bullish (15m, 5m, 1m)\n2. RSI(14) crosses above 40 after dipping below 30\n3. WAE explosion above sensitivity threshold with positive trend\n4. Price bounces from Bullish Order Block or fills Fair Value Gap upward\n5. OrderBook bid-ask imbalance \u003e 1.5\n6. No iceberg orders detected on ask side\n\n**Short Entry Requirements:**\n1. All timeframes aligned bearish (15m, 5m, 1m)\n2. RSI(14) crosses below 60 after rising above 70\n3. WAE explosion with negative trend line\n4. Price rejects from Bearish Order Block or fills Fair Value Gap downward\n5. OrderBook bid-ask imbalance \u003c 0.67\n6. No iceberg orders detected on bid side\n\n### Exit Management\n\n- **Initial Target**: 2x risk (dynamically calculated via ATR)\n- **Stop Loss**: 1% or 10-15 ticks (whichever is tighter)\n- **Trailing Stop**: Parabolic SAR activated after 1x risk achieved\n- **Time Exit**: Close position after 5 minutes without progress\n- **Trend Reversal**: Exit if higher timeframe trend flips\n\n## Project Structure\n\n```\ntrend-momentum-x/\n├── main.py                 # Main entry point and trading loop\n├── strategy/               # Strategy components\n│   ├── __init__.py\n│   ├── trend_analysis.py   # Multi-timeframe trend determination\n│   ├── signals.py          # Entry signal generation\n│   ├── orderbook.py        # Level 2 OrderBook analysis\n│   ├── risk_manager.py     # Position sizing and risk management\n│   └── exits.py            # Exit rules and trailing stops\n├── tests/                  # Comprehensive test suite (91% coverage)\n│   ├── conftest.py        # Pytest fixtures and mocks\n│   └── test_*.py          # Test files for each module\n├── utils/                  # Utilities\n│   ├── __init__.py\n│   ├── config.py          # Configuration management\n│   └── logger.py          # Logging setup\n├── validate_api_usage.py   # API validation script for project-x-py\n├── CLAUDE.md              # Comprehensive development documentation\n├── pyproject.toml         # Project configuration and dependencies\n└── uv.lock               # Locked dependencies\n```\n\n## Safety Features\n\n1. **Volume Filter**: Ignores signals in thin markets (volume \u003c 20% of 1-minute average)\n2. **Risk Limits**: Automatically stops trading at daily/weekly loss limits via project-x-py's managed_trade context\n3. **Position Limits**: Enforces maximum concurrent positions through built-in risk manager\n4. **Correlation Filter**: Prevents correlated trades (e.g., ES and NQ when correlation \u003e 0.8)\n5. **Graceful Shutdown**: Closes all positions and saves state on exit\n\n## Monitoring\n\nThe strategy provides comprehensive logging:\n- **Console**: INFO level and above for real-time monitoring\n- **File**: `trading_YYYYMMDD.log` with DEBUG level for detailed analysis\n\nKey metrics tracked:\n- Daily and weekly P\u0026L\n- Win rate and risk-reward ratio\n- Average trade duration\n- Number of trades per session\n- Slippage and commission impact\n\n## Testing Recommendations\n\n1. **Paper Trading**: Test for at least 2-4 weeks on a paper account\n2. **Small Size**: Start with minimum position sizes when going live\n3. **Monitor Closely**: Watch the first 100 trades carefully\n4. **Parameter Tuning**: Adjust parameters based on market conditions\n5. **Market Conditions**: Test in different volatility regimes\n\n## Documentation\n\n- [CLAUDE.md](CLAUDE.md) - Comprehensive development documentation\n- [Project X Documentation](https://texascoding.github.io/project-x-py/) - Official project-x-py documentation\n- [Project X GitHub](https://github.com/TexasCoding/project-x) - Main Project X repository\n\n## Contributing\n\nContributions are welcome! Please ensure:\n1. Code passes all linting checks (`uv run ruff check`)\n2. Type hints are properly added (`uv run mypy .`)\n3. New features are documented\n4. Tests are added for new functionality\n\n## Support\n\nFor issues related to:\n- **project-x-py**: Check the [official documentation](https://texascoding.github.io/project-x-py/)\n- **Project X**: Visit the [Project X repository](https://github.com/TexasCoding/project-x)\n- **Strategy Logic**: Open an issue in this repository\n\n## Disclaimer\n\n**IMPORTANT**: This strategy is for educational purposes only. Trading futures involves substantial risk of loss and is not suitable for all investors. Past performance is not indicative of future results. \n\n- Always test thoroughly on paper accounts before live trading\n- Never risk more than you can afford to lose\n- Consider consulting with a financial advisor\n- Be aware that market conditions can change rapidly\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## Acknowledgments\n\n- Built with [Project X](https://www.projectx.com/) - The comprehensive trading framework\n- Powered by [project-x-py](https://github.com/TexasCoding/project-x-py) - The official Python SDK\n- Optimized with [Polars](https://github.com/pola-rs/polars) - Lightning-fast DataFrame library\n- Package management by [uv](https://github.com/astral-sh/uv) - An extremely fast Python package installer","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftexascoding%2Ftrend-momentum-x","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftexascoding%2Ftrend-momentum-x","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftexascoding%2Ftrend-momentum-x/lists"}