══════════════════════════════════════════════════════════════════════
YAKUZA EA V3.0 — BREAKOUT EDITION
User Guide
Copyright 2026, Ahmed Ibrahim. All Rights Reserved.
══════════════════════════════════════════════════════════════════════
TABLE OF CONTENTS
─────────────────
1. Overview
2. Installation
3. How the Strategy Works
4. Input Parameters Reference
4.1 General
4.2 S1: Breakout
4.3 S1: Time Filter
4.4 News Filter
4.5 Lot Sizing
4.6 Telegram
4.7 Logging
4.8 Dashboard
5. Lot Size Modes Explained
6. News Filter Explained
7. Telegram Setup
8. Dashboard
9. Backtesting Notes
10. Troubleshooting
11. Changelog
══════════════════════════════════════════════════════════════════════
1. OVERVIEW
══════════════════════════════════════════════════════════════════════
Yakuza EA V3.0 Breakout Edition is a fully automated Expert Advisor
for MetaTrader 5 that trades swing-level breakouts using pending
BuyStop and SellStop orders.
Key features:
- Swing high/low detection with configurable lookback depth
- Pending order placement with automatic expiration
- Step-based trailing stop loss
- Session time filter (broker time or GMT)
- Economic news filter using the MQL5 built-in calendar
- Automatic position closing on news events (optional)
- Five lot-sizing modes including percentage risk
- Real-time on-chart dashboard
- Telegram notifications for trades, daily/weekly reports,
and protection events
- Works on any symbol and any timeframe
══════════════════════════════════════════════════════════════════════
2. INSTALLATION
══════════════════════════════════════════════════════════════════════
Step 1 — Attach to a chart
In MT5 Navigator panel (Ctrl+N), expand Expert Advisors, find
"Yakuza_EA_V3_Breakout", and drag it onto your desired chart.
Step 2 — Enable algo trading
Make sure the "Algo Trading" button on the MT5 toolbar is enabled
(it should appear green, not red).
Step 3 — Allow web requests (for Telegram)
If using Telegram notifications, go to:
Tools → Options → Expert Advisors
Check "Allow WebRequest for listed URL" and add:
══════════════════════════════════════════════════════════════════════
3. HOW THE STRATEGY WORKS
══════════════════════════════════════════════════════════════════════
The EA runs on each new bar and performs the following steps:
1. SWING DETECTION
The EA scans the last 200 bars looking for swing highs and
swing lows. A swing high is a bar whose high is the highest
within S1_BarsN bars on each side. A swing low is the
opposite — the lowest low within the same window.
2. PENDING ORDER PLACEMENT
If there is no existing buy position or buy pending order,
the EA places a BuyStop at the most recent swing high.
If there is no existing sell position or sell pending order,
it places a SellStop at the most recent swing low.
Each pending order gets:
- A stop loss at S1_Slpoints distance from entry
- A take profit at S1_Tppoints distance from entry
- An expiration time of S1_ExpirationBars bars from now
3. ORDER FILTERING
Before placing orders, the EA checks:
- Time filter: Is the current hour within the allowed
trading session? If not, all pending orders are deleted.
- News filter: Is a high-impact news event imminent or
in progress? If so, pending orders are deleted and
optionally open positions are closed.
4. TRAILING STOP
On every tick, the EA checks all open S1 positions. Once
price has moved S1_TslTriggerPoints in profit, the stop
loss is trailed in steps of S1_Tslpoints behind the
current price. The trail only moves in the favorable
direction — it never moves backward.
5. EXIT
Positions are closed by either:
- Take profit being hit
- Stop loss (original or trailed) being hit
- Pending order expiration (if never triggered)
- News filter closing positions (if NewsCloseOnEvent=true)
══════════════════════════════════════════════════════════════════════
4. INPUT PARAMETERS REFERENCE
══════════════════════════════════════════════════════════════════════
───────────────────────────────────────────────────────────────────
4.1 GENERAL
────────────────────────────────────────────────────────────────────
Magic (default: 696969)
Unique magic number that identifies this EA's trades. If you
run multiple EAs on the same account, each must have a
different magic number.
EA_Comment (default: "Yakuza EA")
Comment string attached to every order and position opened
by this EA. The EA appends " S1" to identify breakout trades.
────────────────────────────────────────────────────────────────────
4.2 S1: BREAKOUT
────────────────────────────────────────────────────────────────────
S1_BarsN (default: 3)
Number of bars on each side required to confirm a swing
point. A value of 3 means a swing high must be higher than
the 3 bars before it and the 3 bars after it (7-bar window).
Higher values produce fewer but stronger breakout levels.
S1_OrderDistPoints (default: 0)
Distance between High/Low to place the pending order
S1_ExpirationBars (default: 50)
Number of bars after which an unfilled pending order is
automatically cancelled by the broker. On H1 this means
roughly 50 hours; on M15 it means about 12.5 hours.
S1_Tppoints (default: 1000)
Take profit distance in points from the entry price.
On a 5-digit broker, 1000 points = 100 pips for forex.
On gold (2-digit), 1000 points = 10.00 price distance.
S1_Slpoints (default: 400)
Stop loss distance in points from the entry price.
Same point/pip conversion as above.
S1_Tslpoints (default: 50)
Trailing stop step size in points. Once the trail is
activated, the stop loss follows price at this distance.
S1_TslTriggerPoints (default: 50)
Minimum profit in points before the trailing stop
activates. The position must be at least this far in
profit before any trailing begins.
────────────────────────────────────────────────────────────────────
4.3 S1: TIME FILTER
────────────────────────────────────────────────────────────────────
S1_TradingTime (default: true)
Enable or disable the session time filter. When enabled,
the EA only places new pending orders during the allowed
hours. Existing pending orders are deleted outside the
allowed session. Open positions are NOT closed by this
filter — only pending orders are affected.
S1_TimeSelection (default: BROKER_TIME)
Which clock to use for the time filter.
BROKER_TIME = server time returned by TimeCurrent()
GMT_TIME = UTC/GMT time returned by TimeGMT()
S1_TradingStartHour (default: 7)
Hour (0–23) when the trading session begins.
S1_TradingEndHour (default: 18)
Hour (0–23) when the trading session ends.
Overnight sessions are supported: if StartHour > EndHour
(e.g. Start=22, End=6), the EA trades from 22:00 through
midnight to 06:00.
────────────────────────────────────────────────────────────────────
4.4 NEWS FILTER
────────────────────────────────────────────────────────────────────
UseNewsFilter (default: true)
Enable the economic calendar news filter. When a qualifying
news event is within the buffer window, the EA blocks new
order placement and deletes existing pending orders.
NewsMinsBefore (default: 15)
Minutes before a news event to begin blocking.
NewsMinsAfter (default: 15)
Minutes after a news event to continue blocking.
NewsHighOnly (default: true)
When true, only high-impact (red) events trigger the
filter. When false, both high and medium-impact events
are included.
NewsCloseOnEvent (default: false)
When true, all open positions (not just pending orders)
are immediately closed when a news block begins. Use with
caution — this will force-close profitable trades.
NewsCountry (default: "US")
Country code to filter events by. The filter checks if
the event's country code contains this string. Common
values: "US", "EU", "GB", "JP", "AU", "CA", "CH", "NZ".
To match multiple countries, you would need to run
separate EA instances or modify the code.
───────────────────────────────────────────────────────────────────
4.5 LOT SIZING
────────────────────────────────────────────────────────────────────
LotSizeMode (default: FIXED_LOTS)
Selects which lot calculation method to use.
See Section 5 for a detailed explanation of each mode.
RiskPct (default: 3.0)
The percentage value used by PCT_ACCOUNT_BALANCE,
PCT_EQUITY, and PCT_FREE_MARGIN modes.
FixedRiskAmount (default: 50.0)
Dollar amount risked per trade when using
FIXED_RISK_PER_TRADE mode.
FixedLotSize (default: 0.05)
Lot size used in FIXED_LOTS mode and as a fallback
if any dynamic calculation fails.
MaxLotSize (default: 0.0)
Hard cap on lot size. Set to 0.0 to disable the cap.
When set to a positive value, no trade will exceed
this lot size regardless of the calculated amount.
────────────────────────────────────────────────────────────────────
4.6 TELEGRAM
────────────────────────────────────────────────────────────────────
TG_Enabled (default: true)
Master switch for all Telegram notifications.
TG_BotToken (default: "")
Your Telegram bot token from @BotFather.
Example: "1234567890:ABCDefGhIjKlMnOpQrStUvWxYz"
TG_ChatID (default: "")
Your Telegram chat or group ID.
Example: "-1001234567890" for a group, or "123456789"
for a private chat.
TG_TradeAlerts (default: true)
Send a notification when a trade opens or closes.
TG_DailyReport (default: true)
Send a daily summary report.
TG_DailyReportHour (default: 23)
Hour (broker time) to send the daily report.
TG_WeeklyReport (default: true)
Send a weekly summary report (Fridays only).
TG_WeeklyReportHour (default: 22)
Hour (broker time, Friday) to send the weekly report.
TG_ProtectionAlerts (default: true)
Send a notification when a protection event triggers,
such as a news block activating.
────────────────────────────────────────────────────────────────────
4.7 LOGGING
────────────────────────────────────────────────────────────────────
VerboseLog (default: false)
When enabled, the EA prints detailed debug messages to
the MT5 Experts log tab. Useful for troubleshooting.
Keep disabled in production to reduce log file size.
────────────────────────────────────────────────────────────────────
4.8 DASHBOARD
────────────────────────────────────────────────────────────────────
ShowDashboard (default: true)
Display the on-chart information panel.
DashBgColor (default: C'8,5,12')
Background color of the dashboard panel.
DashTextColor (default: C'210,200,225')
Default text color for values.
DashGreenColor (default: C'40,200,100')
Color used for positive values and active status.
DashRedColor (default: C'220,35,25')
Color used for negative values and losses.
DashAccentColor (default: C'200,30,20')
Color used for labels and the panel border.
DashFontSize (default: 12)
Font size in pixels for dashboard text.
DashX (default: 12)
Horizontal offset from the left edge of the chart.
DashY (default: 40)
Vertical offset from the top of the chart.
══════════════════════════════════════════════════════════════════════
5. LOT SIZE MODES EXPLAINED
══════════════════════════════════════════════════════════════════════
All dynamic modes calculate lot size based on the stop loss
distance of each individual trade. The formula is:
lots = risk_amount / (SL_distance_in_ticks × tick_value)
The five available modes:
FIXED_LOTS
Every trade uses exactly the FixedLotSize value.
Simple and predictable, but does not adapt to account
growth or varying stop loss distances.
PCT_ACCOUNT_BALANCE
Risk amount = Account Balance × RiskPct / 100
Best for: Steady compounding based on realized gains.
PCT_EQUITY
Risk amount = Account Equity × RiskPct / 100
Equity includes unrealized floating P&L. Lot sizes
increase when you have winning open trades and decrease
when you have losing ones.
PCT_FREE_MARGIN
Risk amount = Free Margin × RiskPct / 100
Free margin is equity minus margin used by open positions.
This is the most conservative dynamic mode because lot
sizes shrink as you open more positions.
FIXED_RISK_PER_TRADE
Risk amount = FixedRiskAmount (in account currency)
Risks exactly the specified dollar amount per trade
regardless of account size.
Safety features built into all modes:
- Lot size is clamped to the symbol's minimum and maximum
- Lot size is rounded down to the nearest valid step
- MaxLotSize cap is enforced if set
- A margin check ensures the account can afford the trade;
if not, lot size is reduced until it fits
══════════════════════════════════════════════════════════════════════
6. NEWS FILTER EXPLAINED
══════════════════════════════════════════════════════════════════════
The news filter uses the MQL5 built-in economic calendar
(CalendarValueHistory) to detect upcoming events. It does NOT
require any external files, downloads, or indicator dependencies.
How it works:
1. On every tick, the EA queries the calendar for events
within the time window:
from: now − NewsMinsAfter
to: now + NewsMinsBefore + 60 minutes
2. It filters events by:
- Country code matching NewsCountry
- Importance level (high only, or high + medium)
3. If the current time falls within the blocking window
of any matching event (NewsMinsBefore before through
NewsMinsAfter after the event time):
- All pending S1 orders are immediately deleted
- If NewsCloseOnEvent is true, all open positions
are also closed
- No new orders are placed until the block clears
- A Telegram alert is sent (if TG_ProtectionAlerts)
4. The dashboard shows the news filter status in real time:
"Clear" — no nearby events
"Next: NFP in 45m" — upcoming event with countdown
"BLOCKED: NFP" — currently in a blocking window
Requirements:
The MQL5 calendar requires an active internet connection
and only works with a live or demo account. It does NOT
function in the Strategy Tester (backtesting). During
backtests the news filter is effectively disabled.
══════════════════════════════════════════════════════════════════════
7. TELEGRAM SETUP
══════════════════════════════════════════════════════════════════════
Step 1 — Create a bot
Open Telegram, search for @BotFather, and send /newbot.
Follow the prompts. You will receive a bot token like:
1234567890:ABCDefGhIjKlMnOpQrStUvWxYz
Step 2 — Get your chat ID
Option A (private chat): Search for @userinfobot on
Telegram and send it any message. It replies with your ID.
Option B (group chat): Add your bot to the group, send a
message, then visit in your browser:
https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates
Look for the "chat":{"id": value in the JSON response.
Step 3 — Allow the URL in MT5
Go to Tools → Options → Expert Advisors, check
"Allow WebRequest for listed URL" and add:
Step 4 — Enter your credentials
Set TG_BotToken and TG_ChatID in the EA inputs.
Notification types:
Startup message — sent when the EA initializes, confirms
it is running and shows the symbol and balance.
Trade opened — sent when a pending order fills, showing
entry price, SL, TP, lot size, and direction.
Trade closed — sent when a position exits (SL, TP, or
forced close), showing P&L, open/close prices, and lots.
Protection alert — sent when the news filter blocks
trading, showing the event name and time.
Daily report — sent once per day at TG_DailyReportHour,
showing balance and day P&L.
Weekly report — sent on Fridays at TG_WeeklyReportHour,
showing the current balance.
══════════════════════════════════════════════════════════════════════
8. DASHBOARD
══════════════════════════════════════════════════════════════════════
The on-chart dashboard displays the following information,
updated on every tick:
Row Content
─── ──────────────────────────────────────────────────
1 Title: YAKUZA AI V3.0 · BREAKOUT
2 Account name
3 Trading symbol
4 Equity P&L (current equity minus balance)
5 Day P&L (equity minus start-of-day balance)
6 Strategy status (S1 Breakout ON)
7 News filter status (Clear / Next event / BLOCKED)
8 Open positions (Buy count, Sell count)
9 Pending orders (BuyStop count, SellStop count)
10 Running time in days since EA was attached
The dashboard is automatically removed when the EA is
removed from the chart or when the chart is closed.
To reposition the dashboard, adjust DashX and DashY. To
hide it entirely, set ShowDashboard to false.
══════════════════════════════════════════════════════════════════════
10. TROUBLESHOOTING
══════════════════════════════════════════════════════════════════════
PROBLEM: EA is on the chart but not trading.
CHECK:
- Is "Algo Trading" enabled (green button on toolbar)?
- Is the EA within the allowed trading hours?
- Is the news filter currently blocking?
- Check the Experts tab (Ctrl+E) for error messages.
- Enable VerboseLog=true for detailed output.
PROBLEM: "Trade request failed" errors in the log.
CHECK:
- Is the market open for this symbol?
- Does the account have sufficient free margin?
- Are SL/TP distances respecting the broker's minimum
stops level? The EA checks this automatically, but
some brokers have very wide minimums.
PROBLEM: Telegram messages are not being received.
CHECK:
- Is https://api.telegram.org added to the allowed
URLs in Tools → Options → Expert Advisors?
- Is TG_BotToken and TG_ChatID correct?
- Has the bot been added to the group (if using a group)?
- Check the Experts tab for WebRequest errors.
PROBLEM: Pending orders are being deleted repeatedly.
CHECK:
- The time filter deletes pending orders outside the
allowed session. Check S1_TradingStartHour and
S1_TradingEndHour.
- The news filter deletes pending orders when a block
activates. Check the dashboard News row.
- A very short S1_ExpirationBars value causes orders
to expire quickly. Increase it.
PROBLEM: Dashboard is not visible.
CHECK:
- Is ShowDashboard set to true?
- The dashboard may be offscreen. Reset DashX=12 and
DashY=40.
- Zoom out or scroll the chart — the dashboard is
anchored to the top-left corner.
PROBLEM: Lot size is always the minimum.
CHECK:
- If using a dynamic mode, the stop loss distance
may be very large relative to the risk amount,
resulting in a tiny calculated lot size.
- Check that RiskPct or FixedRiskAmount is set to
a reasonable value.
- Check the Experts log with VerboseLog=true.
══════════════════════════════════════════════════════════════════════
11. CHANGELOG
══════════════════════════════════════════════════════════════════════
V3.0 — Breakout Edition (2026)
- News filter using MQL5 built-in calendar
- Optional position closing on news events
- Telegram notifications via POST/JSON (reliable
delivery of special characters and emoji)
- On-chart dashboard with real-time updates
- Five lot-sizing modes with margin safety check
- Session time filter with overnight support
- Step trailing stop loss
══════════════════════════════════════════════════════════════════════
DISCLAIMER
══════════════════════════════════════════════════════════════════════
Trading foreign exchange, commodities, and other financial
instruments carries a high level of risk and may not be
suitable for all investors. Past performance is not indicative
of future results. You should be aware of all the risks
associated with trading and seek advice from an independent
financial advisor if you have any doubts. The author is not
responsible for any losses incurred through the use of this
software.
══════════════════════════════════════════════════════════════════════
Copyright 2026, Ahmed Ibrahim. All Rights Reserved.
══════════════════════════════════════════════════════════════════════
