AI MAP 3.00 — Installation & User Guide
AI-driven grid / martingale Expert Advisor for MetaTrader 5 with a price-action engine, Grok (xAI) and OpenRouter support, and an on-chart dashboard.
You must use your own API key
AI MAP sends its market analysis to an AI model. To do that it needs your own personal API key from xAI (Grok) or OpenRouter. The key is not included with the EA and is not shared between users.
- You create the key in your own account and you pay the AI provider directly for your own usage.
- Without a valid key with available credit, the EA cannot analyse the market and will not place any orders.
- Keep your key private. Never post it in comments, screenshots or chats.
1. How AI MAP works
- Price-action engine (inside the EA). The EA reads D1, H4, H1 and M15 and turns raw candles into clean, decision-ready data:etc
- market structure (HH/HL/LH/LL, BOS and CHoCH)
- liquidity sweeps and equal highs/lows
- etc...
- Step 1 – AI analysis. The AI receives that data and returns:
- a bias (bullish, bearish or neutral) with confidence and timeframe-alignment scores
- entry zones
- an invalidation level
- targets
- Step 2 – AI grid plan. The AI plans the grid of pending orders:
- order type and entry price for each order
- expiry time
- a basket take-profit for every number of filled orders
- Execution and management. The EA places the orders. Lots grow by the martingale multiplier for each level. The EA manages the basket with the AI take-profits and never allows a take-profit below the basket break-even. It also applies your risk, news, schedule and drawdown protections.
- Cycle. A new analysis runs about every 60 minutes, and only while there is no open basket. If one AI step fails, only that step is retried, so a good analysis is not thrown away.
2. Requirements
- MetaTrader 5 (build 4000 or newer recommended), with a hedging or netting account.
- Designed and tuned for XAUUSD (Gold). Attach it to an H1 chart. The analysis always uses D1/H4/H1/M15, whatever chart timeframe you use.
- Your own API key from xAI or OpenRouter, with credit (see the next section).
- A stable internet connection. A VPS is recommended for 24/5 operation.
- Always start on a demo account first.
3. Getting your API key
Option A – Grok (xAI)
- Open console.x.ai and sign in or create an account.
- Add credit to your account (billing section).
- Open API Keys, then Create API key. The key starts with xai- .
- Copy the key. You will paste it into the EA input UseCustomAPI .
Option B – OpenRouter (one key, many models)
- Open openrouter.ai and sign in or create an account.
- Add credit (Settings, then Credits). Free models (ids ending in :free ) can work without credit, but they are often slow and rate-limited.
- Open Keys, then Create Key. The key starts with sk-or- .
- Choose a model on openrouter.ai/models and copy its exact id, for example anthropic/claude-sonnet-5.5 or x-ai/grok-4.7 .
Tip: fast paid models give the most reliable results. Free models may take several minutes per answer or fail at busy times. When that happens no orders are placed for that cycle.
4. Installation step by step
- Install the EA. Buy or download AI MAP from the MQL5 Market inside MetaTrader 5 (Toolbox → Market → Purchased). It appears under Navigator → Expert Advisors → Market.
- Allow WebRequest (required). Go to Tools → Options → Expert Advisors.
- Tick Allow algorithmic trading.
- Tick Allow WebRequest for listed URL.
- Add these URLs exactly:
- https://api.x.ai (for Grok)
- https://openrouter.ai (for OpenRouter)
- http://ec.forexprostools.com (for the news filter)
- Open a chart. Open an XAUUSD H1 chart. Use only one AI MAP instance per symbol, or give each instance a different MAGIC_NUMBER .
- Attach the EA. Drag AI MAP onto the chart. On the Common tab, tick Allow Algo Trading.
- Fill in the Inputs tab.
- Choose your provider in group 1.
- Fill in only that provider's group: group 2 for Grok, group 3 for OpenRouter.
- See the quick start below.
- Check the Experts log. Click OK and open Toolbox → Experts. You should see:
- AI MAP 3.00 | provider ... | model ...
- Price-action snapshot built
- AI answered in ... s
5. Quick start settings
| Provider | Set these inputs |
|---|---|
| Grok (xAI) |
|
| OpenRouter |
|
Leave everything else on default for your first demo run. Then adjust risk (groups 11, 14 and 16) to suit your account.
6. All inputs explained
1. AI - Main
| Input | Default | Description |
|---|---|---|
| AI_PROVIDER | Grok (xAI) | Which AI service to use. Fill in only the matching group below (2 for Grok, 3 for OpenRouter). |
| AI_ANALYSIS_MODE | Price Action Pro | Price Action Pro (recommended) is the clean-data, 2-step AI engine. Legacy is the old v2.50 multi-agent flow, kept for compatibility. |
| AI_GRID_PLANNER | true | true: the AI plans the grid (entries, expiry, take-profits). false: the AI only analyses and the EA builds the grid itself from the AI's zones and bias. |
| ShowAIReport | true | Shows the dashboard panel on the chart. |
2. Grok (xAI) — only if provider = Grok
| Input | Default | Description |
|---|---|---|
| CustomAPI | false | Set to true to use your own xAI key. This is required: set it to true and enter your key below. |
| UseCustomAPI | (empty) | Your xAI API key ( xai-... ). |
| FINAL_MODEL | grok-4-1-fast-non-reasoning | The Grok model id. The fast non-reasoning model answers in seconds. grok-4.7 reasons more deeply but can take 1–3 minutes per step. If you use it, keep AI_TIMEOUT_SEC at 240. |
3. OpenRouter — only if provider = OpenRouter
| Input | Default | Description |
|---|---|---|
| OPENROUTER_API_KEY | (empty) | Your OpenRouter key ( sk-or-... ). |
| OPENROUTER_MODEL | anthropic/claude-sonnet-5.5 | The exact model id copied from openrouter.ai/models. Any chat model works. Fast paid models are the most reliable. |
| OPENROUTER_REASONING | (empty) | Reasoning effort for reasoning models: none , low , medium or high . Leave it empty to use the model's own default (recommended). |
4. AI - Advanced (leave default)
| Input | Default | Description |
|---|---|---|
| AI_TEMPERATURE | 0.1 | AI randomness. Low values give consistent, precise answers. Keep it between 0.0 and 0.3. |
| AI_MAX_TOKENS | 0 | Maximum answer length. 0 means no limit (recommended). A low limit can cut off reasoning models before they answer. |
| AI_TIMEOUT_SEC | 240 | How long to wait for an AI answer, in seconds. |
| AI_MAX_RETRIES | 3 | How many times a failed AI step is retried. |
| AI_RETRY_DELAY_SEC | 30 | Pause before retrying a failed step, in seconds. If the analysis step fails, a new analysis is tried after about 10× this value instead of waiting a full hour. |
5. Trading Strategy
| Input | Default | Description |
|---|---|---|
| TRADING_STRATEGY | Aggressive | How selective the EA is.
|
6. Smart Trading Core
| Input | Default | Description |
|---|---|---|
| CLEAR_PREVIOUS_ORDERS | true | Before a new analysis, deletes the EA's old pending orders, but only if no position is open. |
| MAGIC_NUMBER | 303049 | Unique id for this EA's trades. Use a different number for each chart or instance. |
| adjustspread | 3 | Spread compensation. Entry prices are shifted by this many times the current spread so limit orders are realistic. |
| Tag | AIMAP | Text added to the order comment (for example AIMAP_MAP_L1 ). |
7. Trading Schedule
| Input | Default | Description |
|---|---|---|
| TRADING_START_TIME | 06:00 | Daily start time in broker server time (the time shown in Market Watch). |
| TRADING_END_TIME | 20:00 | Daily end time in server time. Overnight ranges such as 22:00–03:00 are supported. |
| AUTO_CLOSE_OUTSIDE_HOURS | true | Closes the EA's positions when trading hours end. |
8. Weekend Protection
| Input | Default | Description |
|---|---|---|
| ENABLE_FRIDAY_PROTECTION | true | Stops trading and closes the EA's trades on Friday at the time below, to avoid weekend gaps. |
| FRIDAY_CLOSE_HOUR | 20 | Friday close hour (0–23, server time). |
| FRIDAY_CLOSE_MINUTE | 30 | Friday close minute (0–59). |
9. News Filter
| Input | Default | Description |
|---|---|---|
| USEFILTERNEWS | true | Pauses new trading around economic news. Requires http://ec.forexprostools.com in the WebRequest list. |
| USE_AUTO_GMT | true | Detects the broker's GMT offset automatically. |
| MANUAL_GMT_OFFSET | 0 | The broker GMT offset (−12 to +14). Used only when auto-detect is off. |
| BeforeNewsStop | 120 | Minutes before a news release to stop opening trades. |
| AfterNewsStop | 60 | Minutes after a news release before trading resumes. |
| NewsLight | false | Also filter low-impact news. |
| NewsMedium | false | Also filter medium-impact news. |
| NewsHard | true | Filter high-impact news. |
| NewsSymb | USD,XAU | Comma-separated currencies whose news is filtered. |
10. Volatility Protection
| Input | Default | Description |
|---|---|---|
| ENABLE_VOLATILITY_PROTECTION | true | Skips trading during abnormal volume spikes or sudden price jumps. |
| MaxSlippage | 30 | Maximum allowed slippage when executing, in points. |
11. Position Sizing
| Input | Default | Description |
|---|---|---|
| RISK_PERCENT | 1.0 | Percentage of the balance used to size the first (base) order when auto lot is on. |
| USE_AUTO_LOT | true | true: the base lot is calculated from RISK_PERCENT . false: FIXED_LOT is used. |
| FIXED_LOT | 0.01 | Base lot when auto lot is off. Later grid levels are this lot × the multiplier. |
12. Profit Targets
| Input | Default | Description |
|---|---|---|
| RESET_AT_MIDNIGHT | true | Resets the daily profit and loss tracking at midnight (server time). |
13. Trailing Stop
| Input | Default | Description |
|---|---|---|
| USE_TRAILING_STOP | false | Enables a trailing stop to lock in profit. |
| TRAILING_TRIGGER | 90 | Profit, in pips, needed before trailing starts. |
| TRAILING_DISTANCE | 15 | Distance, in pips, that the stop trails behind price. |
14. Martingale Configuration
| Input | Default | Description |
|---|---|---|
| MARTINGALE_PROFIT_MODE | AI Dynamic | AI Dynamic (recommended): the basket closes at the AI take-profit for the current number of filled orders, always above break-even. Static: a fixed profit target is used. |
| MARTINGALE_PROFIT_TARGET_PIPS | 200 | Basket profit target in Static mode, also used as a fallback when no AI target exists. |
| MARTINGALE_LOSS_TARGET_PIPS | 8000 | Basket loss limit. The whole basket is closed if the loss reaches this. |
| MARTINGALE_MULTIPLIER | 1.15 | Lot multiplier per grid level: lot(k) = base × multiplierk−1. Higher values recover faster but raise risk sharply. |
| MARTINGALE_MAX_ORDERS | 10 | Maximum number of grid orders in one basket. |
| MARTINGALE_ORDER_SPACING_PIPS | 250 | Base distance between grid orders, used when the EA builds the grid. |
15. Risk Protection Controls
| Input | Default | Description |
|---|---|---|
| ENABLE_ADVANCED_RISK_PROTECTION | true | Turns on the drawdown limits in group 16. Keeping this on is strongly recommended. |
| ENABLE_ORDER_PRICE_VALIDATION | false | Extra check that rejects AI entry prices that are too close to or too far from the current price. |
16. Drawdown Limits
| Input | Default | Description |
|---|---|---|
| MAX_TOTAL_DRAWDOWN_PERCENT | 5.0 | Maximum floating loss of the basket (% of balance) before an emergency close. |
| MAX_DRAWDOWN_WITH_3_POSITIONS | 4.0 | A tighter limit once 3 or more positions are open. |
| MAX_DRAWDOWN_WITH_5_POSITIONS | 3.5 | A tighter limit once 5 or more positions are open. |
| MAX_SINGLE_POSITION_LOSS_PERCENT | 3.0 | Emergency close threshold for a single position (% of balance). |
7. The dashboard panel
- Header: the provider and model, and a live status (idle, analysing or error). Drag the header to move the panel; click the button to collapse it.
- Market: price, spread, ATR and session.
- AI Verdict:
- bias, confidence bar and decision (TRADE or SKIP)
- invalidation level
- current AI step and a countdown to the next analysis
- the last error, if there was one
- Market Structure: trend and last event (BOS, CHoCH or sweep) for D1, H4, H1 and M15.
- Key Zones: the nearest support and resistance zones with their strength.
- Basket: open positions, profit and loss, the active AI take-profit and drawdown.
- AI Summary and a footer with the news status and time.
8. Strategy Tester note
MetaTrader 5 does not allow WebRequest in the Strategy Tester, so the AI cannot be called during a backtest. In the tester the EA runs a built-in simulation of its grid logic. Backtest results therefore do not represent live AI decisions. Evaluate AI MAP on a demo account in real time.
9. Troubleshooting
| Message in the Experts log | Cause | Fix |
|---|---|---|
| WebRequest blocked / error 4014 | The URL is not allowed | Add the URLs from step 2 of the installation under Tools → Options → Expert Advisors. |
| HTTP 401 | Wrong, revoked or expired API key | Create a new key and paste it again, with no spaces. |
| HTTP 402 / credits | No credit left on your AI account | Add credit in your xAI or OpenRouter account. |
| HTTP 429 | Rate limit (common with free models) | Wait, or switch to a paid model. |
| Timeout after ... s / HTTP 1003 | The model is too slow | Use a faster model, or raise AI_TIMEOUT_SEC . |
| AI hit max_tokens | The answer was cut off | Set AI_MAX_TOKENS = 0. |
| API key is empty | The key is missing for the selected provider | Fill in the key in group 2 or 3 matching AI_PROVIDER . For Grok also set CustomAPI = true. |
| SKIP - AI found no valid setup | No clean setup (this is normal) | No action needed. The EA checks again next cycle. |
| No analysis starts | Outside trading hours, news pause, an open basket, or the hourly interval | Check the trading hours (server time) and the news filter. A new analysis starts only when no basket is open. |
