Skip to content

Commit 5f82df4

Browse files
JoaopeukoJoaopeuko
committed
improve documentation
1 parent ff6384e commit 5f82df4

27 files changed

+3792
-13
lines changed

‎README.md

Lines changed: 19 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -15,17 +15,27 @@
1515

1616
Welcome to the Mql5-Python-Integration project! This project facilitates the integration between MetaTrader 5 (Mql5) and Python, allowing for efficient algorithmic trading strategies.
1717

18+
## ⚠️ TRADING RISK WARNING
19+
20+
**IMPORTANT: Trading involves substantial risk of loss and is not suitable for all investors.**
21+
22+
- Always use a **demo account** with fake money when testing strategies
23+
- MQPy is provided for **educational purposes only**
24+
- Past performance is not indicative of future results
25+
- Never trade with money you cannot afford to lose
26+
- The developers are not responsible for any financial losses incurred from using this software
27+
1828
## Table of Contents
1929

20-
- [Mql5-Python-Integration (MQPy)](#mql5-python-integration-mqpy)
21-
- [Table of Contents](#table-of-contents)
22-
- [Project Update: Changes in Progress](#project-update-changes-in-progress)
23-
- [Installation](#installation)
24-
- [Usage](#usage)
25-
- [Generate the File](#generate-the-file)
26-
- [Missing Features/Good Practice](#missing-featuresgood-practice)
27-
- [Delicate Metatrader5 Environment](#delicate-metatrader5-environment)
28-
- [Alternative Libraries](#alternative-libraries)
30+
- [⚠️ TRADING RISK WARNING](#️-trading-risk-warning)
31+
- [Table of Contents](#table-of-contents)
32+
- [Project Update: Changes in Progress](#project-update-changes-in-progress)
33+
- [Installation](#installation)
34+
- [Usage](#usage)
35+
- [Generate the File](#generate-the-file)
36+
- [Missing Features/Good Practice](#missing-featuresgood-practice)
37+
- [Delicate Metatrader5 Environment](#delicate-metatrader5-environment)
38+
- [Alternative Libraries](#alternative-libraries)
2939

3040
## Project Update: Changes in Progress
3141

‎docs/examples.md

Lines changed: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
# MQPy Examples
2+
3+
!!! danger "Trading Risk Warning"
4+
**IMPORTANT: All examples should be tested using demo accounts only!**
5+
6+
- Trading involves substantial risk of loss
7+
- These examples are for educational purposes only
8+
- Always test with fake money before using real funds
9+
- Past performance is not indicative of future results
10+
- The developers are not responsible for any financial losses
11+
12+
MQPy provides a variety of example trading strategies to help you understand how to implement your own algorithmic trading solutions using MetaTrader 5.
13+
14+
## Getting Started
15+
16+
If you're new to MQPy, we recommend starting with the [Getting Started Example](https://github.com/Joaopeuko/Mql5-Python-Integration/blob/main/docs/examples/getting_started.py) which introduces you to the basics of:
17+
18+
- Initializing the trading environment
19+
- Fetching market data
20+
- Making trading decisions
21+
- Executing trades
22+
23+
## Basic Strategies
24+
25+
### Moving Average Crossover
26+
27+
The [Moving Average Crossover](https://github.com/Joaopeuko/Mql5-Python-Integration/blob/main/docs/examples/basic_moving_average_strategy.py) strategy is a classic trading approach that:
28+
29+
| Feature | Description |
30+
|---------|-------------|
31+
| Signal Generation | Uses crossovers between short and long moving averages |
32+
| Implementation | Includes proper crossover detection logic |
33+
| Error Handling | Comprehensive logging and exception handling |
34+
35+
[Read detailed explanation of the Moving Average strategy →](strategies/moving_average.md)
36+
37+
```python
38+
def calculate_sma(prices, period):
39+
"""Calculate Simple Moving Average."""
40+
if len(prices) < period:
41+
return None
42+
return sum(prices[-period:]) / period
43+
```
44+
45+
## Technical Indicator Strategies
46+
47+
### RSI Strategy
48+
49+
The [RSI Strategy](https://github.com/Joaopeuko/Mql5-Python-Integration/blob/main/docs/examples/rsi_strategy.py) example demonstrates:
50+
51+
| Feature | Description |
52+
|---------|-------------|
53+
| Indicator | Implementation of the Relative Strength Index (RSI) |
54+
| Trading Approach | Entry/exit based on overbought and oversold conditions |
55+
| Technical Analysis | Practical example of calculating and using indicators |
56+
57+
[Read detailed explanation of the RSI strategy →](strategies/rsi_strategy.md)
58+
59+
### Bollinger Bands Strategy
60+
61+
The [Bollinger Bands Strategy](https://github.com/Joaopeuko/Mql5-Python-Integration/blob/main/docs/examples/bollinger_bands_strategy.py) shows:
62+
63+
| Feature | Description |
64+
|---------|-------------|
65+
| Trading Approach | Using Bollinger Bands for trading range breakouts |
66+
| Strategy Type | Mean reversion trading principles |
67+
| Signal Generation | Volatility-based entry and exit logic |
68+
69+
[Read detailed explanation of the Bollinger Bands strategy →](strategies/bollinger_bands.md)
70+
71+
## Advanced Strategies
72+
73+
### Fibonacci Retracement Strategy
74+
75+
The [Fibonacci Retracement Strategy](https://github.com/Joaopeuko/Mql5-Python-Integration/blob/main/docs/examples/fibonacci_retracement_eurusd.py) for EURUSD:
76+
77+
| Feature | Description |
78+
|---------|-------------|
79+
| Strategy Type | Implements the FiMathe strategy |
80+
| Pattern Recognition | Uses Fibonacci retracement levels for entries and exits |
81+
| Risk Management | Includes dynamic stop-loss adjustment based on price action |
82+
83+
[Read detailed explanation of the Fibonacci Retracement strategy →](strategies/fibonacci_retracement.md)
84+
85+
### Market Depth Analysis
86+
87+
The [Market Depth Analysis](https://github.com/Joaopeuko/Mql5-Python-Integration/blob/main/docs/examples/market_depth_analysis.py) provides insights into order book data:
88+
89+
| Feature | Description |
90+
|---------|-------------|
91+
| Order Book Analysis | Examines buy/sell order distribution and concentration |
92+
| Support/Resistance | Identifies potential support and resistance levels from actual orders |
93+
| Visualization | Creates horizontal bar charts showing bid/ask distribution with key levels |
94+
95+
[Read detailed explanation of the Market Depth Analysis →](strategies/market_depth_analysis.md)
96+
97+
### Multi-Timeframe Analysis
98+
99+
The [Rate Converter Example](https://github.com/Joaopeuko/Mql5-Python-Integration/blob/main/docs/examples/rate_converter_example.py) demonstrates:
100+
101+
| Feature | Description |
102+
|---------|-------------|
103+
| Timeframe Conversion | How to convert between different timeframes using the RateConverter |
104+
| Multi-timeframe Analysis | Calculating moving averages across different timeframes |
105+
| Visualization | Creating charts for price data across 1-minute, 5-minute, and 1-hour timeframes |
106+
107+
### Indicator Connector Strategy
108+
109+
The [Indicator Connector Strategy](https://github.com/Joaopeuko/Mql5-Python-Integration/blob/main/docs/examples/indicator_connector_strategy.py) shows:
110+
111+
| Feature | Description |
112+
|---------|-------------|
113+
| Connectivity | How to connect to MetaTrader 5's custom indicators |
114+
| Signal Combination | Combining multiple indicator signals (Stochastic and Moving Average) |
115+
| Advanced Techniques | Advanced signal generation and filtering approaches |
116+
117+
## Running the Examples
118+
119+
To run any of these examples:
120+
121+
1. Ensure you have MQPy installed:
122+
```bash
123+
pip install mqpy
124+
```
125+
126+
2. Make sure MetaTrader 5 is installed and running on your system
127+
128+
3. Run any example with Python:
129+
```bash
130+
python getting_started.py
131+
```
132+
133+
## Contributing Your Own Examples
134+
135+
If you've developed an interesting strategy using MQPy, consider contributing it to this examples collection by submitting a pull request!
136+
137+
## Disclaimer
138+
139+
These example strategies are for educational purposes only and are not financial advice. Always perform your own analysis and risk assessment before trading with real money.
140+
141+
## All Example Files
142+
143+
You can access these examples in several ways:
144+
145+
1. **Clone the entire repository**:
146+
```bash
147+
git clone https://github.com/Joaopeuko/Mql5-Python-Integration.git
148+
cd Mql5-Python-Integration/docs/examples
149+
```
150+
151+
2. **Download individual files** by clicking on the links in the table below.
152+
153+
3. **Copy the code** from the strategy explanations page for the strategies with detailed documentation.
154+
155+
Here are direct links to all the example files in the MQPy repository:
156+
157+
| Strategy | Description | Source Code |
158+
|----------|-------------|-------------|
159+
| Getting Started | Basic introduction to MQPy | [getting_started.py](https://github.com/Joaopeuko/Mql5-Python-Integration/blob/main/docs/examples/getting_started.py) |
160+
| Moving Average Crossover | Simple trend-following strategy | [basic_moving_average_strategy.py](https://github.com/Joaopeuko/Mql5-Python-Integration/blob/main/docs/examples/basic_moving_average_strategy.py) |
161+
| RSI Strategy | Momentum-based overbought/oversold strategy | [rsi_strategy.py](https://github.com/Joaopeuko/Mql5-Python-Integration/blob/main/docs/examples/rsi_strategy.py) |
162+
| Bollinger Bands | Mean reversion volatility strategy | [bollinger_bands_strategy.py](https://github.com/Joaopeuko/Mql5-Python-Integration/blob/main/docs/examples/bollinger_bands_strategy.py) |
163+
| Fibonacci Retracement | Advanced Fibonacci pattern strategy | [fibonacci_retracement_eurusd.py](https://github.com/Joaopeuko/Mql5-Python-Integration/blob/main/docs/examples/fibonacci_retracement_eurusd.py) |
164+
| Market Depth Analysis | Order book and volume analysis | [market_depth_analysis.py](https://github.com/Joaopeuko/Mql5-Python-Integration/blob/main/docs/examples/market_depth_analysis.py) |
165+
| Rate Converter | Multi-timeframe analysis example | [rate_converter_example.py](https://github.com/Joaopeuko/Mql5-Python-Integration/blob/main/docs/examples/rate_converter_example.py) |
166+
| Indicator Connector | Custom indicator integration | [indicator_connector_strategy.py](https://github.com/Joaopeuko/Mql5-Python-Integration/blob/main/docs/examples/indicator_connector_strategy.py) |
167+
| Sockets Connection | Advanced MetaTrader connectivity | [example_sockets_connection.py](https://github.com/Joaopeuko/Mql5-Python-Integration/blob/main/docs/examples/example_sockets_connection.py) |

‎docs/examples/README.md

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
# MQPy Trading Strategy Examples
2+
3+
This directory contains various example trading strategies implemented using the MQPy framework for MetaTrader 5 integration.
4+
5+
## Getting Started
6+
7+
If you're new to MQPy, start with the `getting_started.py` example which demonstrates basic concepts:
8+
9+
- Initializing the trading environment
10+
- Fetching market data
11+
- Making trading decisions
12+
- Executing trades
13+
14+
## Available Examples
15+
16+
### Basic Strategies
17+
18+
1. **Getting Started** (`getting_started.py`)
19+
- A simple introduction to the MQPy framework
20+
- Demonstrates basic data retrieval and trading operations
21+
- Perfect for beginners
22+
23+
2. **Moving Average Crossover** (`basic_moving_average_strategy.py`)
24+
- Uses crossovers between short and long moving averages
25+
- Implements proper crossover detection logic
26+
- Includes logging and exception handling
27+
28+
### Technical Indicator Strategies
29+
30+
3. **RSI Strategy** (`rsi_strategy.py`)
31+
- Implements the Relative Strength Index (RSI) indicator
32+
- Trades based on overbought and oversold conditions
33+
- Shows how to calculate and use technical indicators
34+
35+
4. **Bollinger Bands Strategy** (`bollinger_bands_strategy.py`)
36+
- Uses Bollinger Bands for trading range breakouts
37+
- Demonstrates mean reversion trading principles
38+
- Includes volatility-based entry and exit logic
39+
40+
### Advanced Strategies
41+
42+
5. **Fibonacci Retracement Strategy** (`fibonacci_retracement_eurusd.py`)
43+
- Implements the FiMathe strategy for EURUSD
44+
- Uses Fibonacci retracement levels for entries and exits
45+
- Includes dynamic stop-loss adjustment based on price action
46+
47+
6. **Multi-Timeframe Analysis** (`rate_converter_example.py`)
48+
- Demonstrates how to convert between different timeframes using the RateConverter
49+
- Implements multi-timeframe analysis by calculating moving averages across timeframes
50+
- Visualizes price data and indicators across 1-minute, 5-minute, and 1-hour charts
51+
52+
## Fibonacci Retracement Strategy
53+
54+
The Fibonacci Retracement strategy (`fibonacci_retracement_eurusd.py`) demonstrates how to implement a trading system based on Fibonacci retracement levels. This strategy:
55+
56+
1. **Identifies swing points**: The algorithm detects significant market swing highs and lows within a specified window.
57+
2. **Calculates Fibonacci levels**: Standard Fibonacci ratios (0, 0.236, 0.382, 0.5, 0.618, 0.786, 1.0) are applied between swing points to generate potential support and resistance levels.
58+
3. **Generates trading signals**: The strategy produces buy signals when price bounces off key retracement levels during uptrends and sell signals during downtrends.
59+
4. **Visualizes analysis**: Creates charts showing price action with identified swing points and Fibonacci levels to aid in trading decisions.
60+
61+
This approach is popular among technical traders who believe that markets frequently retrace a predictable portion of a move before continuing in the original direction.
62+
63+
## Market Depth Analysis
64+
65+
The Market Depth Analysis tool (`market_depth_analysis.py`) provides insights into order book data (DOM - Depth of Market) to understand supply and demand dynamics. Key features include:
66+
67+
1. **Real-time market depth monitoring**: Captures and analyzes order book snapshots at regular intervals.
68+
2. **Buy/sell pressure analysis**: Calculates metrics such as buy/sell volume ratio, percentage distribution, and order concentration.
69+
3. **Support/resistance identification**: Detects potential support and resistance levels based on unusual volume concentration at specific price points.
70+
4. **Visual representation**: Creates horizontal bar charts showing the distribution of buy (bid) and sell (ask) orders, with highlighted support/resistance zones.
71+
72+
This analysis helps traders understand current market sentiment and identify price levels where significant buying or selling interest exists. The tool is particularly valuable for short-term traders and those interested in order flow analysis.
73+
74+
## Detailed Strategy Documentation
75+
76+
For an in-depth explanation of advanced strategies including theoretical background, implementation details, and potential customizations, see the [detailed strategy documentation](STRATEGY_DOCUMENTATION.md).
77+
78+
## Running the Examples
79+
80+
1. Make sure you have MQPy installed:
81+
```bash
82+
pip install mqpy
83+
```
84+
85+
2. Ensure MetaTrader 5 is installed and running on your system
86+
87+
3. Run any example with Python:
88+
```bash
89+
python getting_started.py
90+
```
91+
92+
## Strategy Development Best Practices
93+
94+
When developing your own strategies with MQPy, consider the following best practices:
95+
96+
1. **Error Handling**: Implement proper exception handling to catch network issues, data problems, or unexpected errors
97+
98+
2. **Logging**: Use Python's logging module to record important events and debug information
99+
100+
3. **Testing**: Test your strategy on historical data before deploying with real money
101+
102+
4. **Risk Management**: Always implement proper stop-loss and take-profit levels
103+
104+
5. **Architecture**: Separate your trading logic, indicators, and execution code for better maintainability
105+
106+
## Contributing
107+
108+
If you've developed an interesting strategy using MQPy, consider contributing it to this examples collection by submitting a pull request.
109+
110+
## Disclaimer
111+
112+
These example strategies are for educational purposes only and are not financial advice. Always perform your own analysis and risk assessment before trading with real money.

‎docs/examples/__init__.py

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
"""Example package for MQPy demonstration code."""

0 commit comments

Comments
 (0)