# User Manual: Version 1.17 [Download Markdown](https://aljamalgold.app/uploads/products/aljamalgold/Al_Jamal_Gold_User_Manual-v1.17.md) | [Download optional news toolkit](https://aljamalgold.app/uploads/products/aljamalgold/news-bridge-1.17.zip) | [Release notes](https://aljamalgold.app/release-notes/) The toolkit contains Python scripts and setup documentation, not API keys or the large ONNX asset bundle. News fetching now runs inside the EA; use tokenize_ea_news.py only if enabling FinBERT. Obtain the licensed EA through MQL5 Market. Prepared September 28, 2026. ## Start with the technical engine ### Release and scope Al-Jamal Gold 1.17 | MT5 | XAUUSD | September 28, 2026. Prepared for MQL5 Market submission; publication and platform validation are pending. Standard Trend is the default mode. Strong Trend is the stricter alternative. This release retains the technical trading logic and adds optional external-data workflows. ### 1. Install and open safely Install the purchased EA using your own MT5 Market account. Refresh Navigator and attach it to the broker's XAUUSD M30 chart. To inspect the dashboard first, set InpAutoStart=false. No API key, Python collector or ONNX model is required for the baseline technical engine. ### 2. Review the inputs Default RiskMode is risk percent, RiskPerTrade_Percent=1.0, MaxLotLimit=0.5 and MinLotBehavior=SKIP_IF_TOO_SMALL. Review symbol specifications and broker minimum volume. For a demo trial, use risk suitable for the account; the audited 1% setting is a test condition, not a universal recommendation. ### 3. Check the safety controls Defaults: EnableSafetyMode=true, MaxDailyLoss_Percent=4.8, MaxDrawdown_Percent=9.8, MaxSpreadAllowed=45 points, CloseAllOnSafety=true and HardStop_Equity=0.0. Confirm these inputs and any prop-firm constraints before enabling execution. Limits are operational controls, not a guarantee that gaps or execution cannot exceed them. ### 4. Start a monitored demo Keep all optional data features off initially. The dashboard now has FRED Macro, Trading Economics and FinBERT Shadow status rows. The panel starts expanded. Trading Economics and FinBERT share one row, and the log list is 134 pixels high instead of 44 within the same 500 x 585 window. Automatic chart-height minimization is suppressed; the manual minimize/restore buttons remain available. If the chart is smaller than the panel, enlarge the chart to see the lower controls. Its minimized title remains below the top-left price block. Enable MT5 Algo Trading and review the EA trading permissions, then enable InpAutoStart when ready. Check Experts / Journal for initialization, entry rejection and trade-management messages. Save your chosen .set file before updating. Do not run duplicate EA instances with the same account, symbol and magic number without understanding their interaction. ### Original news protection InpEnableNews controls the existing high-impact economic-news blackout. TE and FinBERT do not replace it. The production news function is bypassed in Strategy Tester, so the published baseline does not measure this blackout. ## Optional FRED macro entry filter ### What it does Enable_FRED_Macro is the single customer-facing FRED switch and defaults to false. The legacy Enable_AI_Macro_Flash switch is hidden and fixed off in this customer build. If migrating an old preset that enabled only the legacy switch, explicitly set Enable_FRED_Macro=true. ### Setup Obtain your own FRED API key. In MT5 Tools > Options > Expert Advisors, allow WebRequest for https://api.stlouisfed.org. Set FRED_API_Key in the EA inputs, then Enable_FRED_Macro=true. The default FRED_Update_Interval is 4 hours. On the dashboard, FRED Macro reports OFF, NO KEY, WAITING, READY or ERROR; hover over its status for the last successful refresh in server time. READY does not guarantee freshness. Store and manage the key privately; saved MT5 input presets may contain it. ### Data series The filter reads DFII10 (10-year real yield), DTWEXBGS (broad dollar index), DGS10 (10-year nominal yield) and T10YIE (10-year breakeven inflation). Each series requires two usable observations; missing FRED values are skipped. Macro decisions are based on the existing profile, not a trained model. ### Availability and failure behavior With no key or macro data not ready, the macro check permits the technical engine to continue. Network access is bypassed in Strategy Tester. There is no new stale-data expiry guard in the FRED module. A ready state alone is not proof that the latest observations are fresh; monitor refresh attempts and available data. ### Optional OpenAI-compatible macro confirmation The customer Inputs include a separate **Optional OpenAI-Compatible Macro Confirmation** group. It defaults to off and is independent of Trading Economics and FinBERT. | Input | Meaning | | --- | --- | | Enable_Macro_AI_Fallback | Enable AI confirmation for ambiguous FRED scores 3 or 4 | | AI_API_URL | Full provider Chat Completions endpoint, including its path | | AI_Model | Exact model ID supported by that provider | | AI_API_Key | Your provider's Bearer token; may be empty for an unauthenticated endpoint | Enable_FRED_Macro must also be on, with a valid FRED key and ready data. Add the AI endpoint's origin to MT5 Tools > Options > Expert Advisors > WebRequest allowlist. Fill the endpoint and model, then enable Enable_Macro_AI_Fallback. The EA sends a non-streaming Chat Completions JSON request containing the proposed BUY/SELL entry, current and previous values of the four FRED series and the directional score. It does not fetch news or share your FRED key with the AI provider. AI services and their usage charges are supplied by the customer. FRED scores 5–7 pass and scores 0–2 are blocked by the existing deterministic logic. Only scores 3–4 call AI. Only the first assistant choice with finish_reason=stop and text exactly YES (ignoring case and surrounding whitespace) passes. NO, explanatory text, missing/non-text output, malformed JSON, truncation, HTTP errors and timeout block that candidate when AI is configured. This is an entry check; it does not close existing trades or alter SL/TP. Requests may occupy the EA event loop for up to 10 seconds per ambiguous candidate. There is no AI request cache or daily budget in this build. When AI is off or its endpoint/model is missing, ambiguous FRED scores pass without an AI call. When FRED is off, its key is missing or its data is unready, the whole macro gate is bypassed. FRED and AI network gating are bypassed in normal Strategy Tester and optimization. FRED dashboard READY describes FRED data, not successful AI authorization; inspect Experts logs for AI allowed/blocked results. Keep saved presets private because they may contain keys. The separate no-network MT5 self-test validates the production gate core, request construction and simulated API replies, including all 16 directional combinations of the four FRED series. It does not establish real provider connectivity, model quality or improved trading performance. Research journal and future-bar labeling remain hidden and fixed off. ### Confirm before live use Check Experts / Journal for WebRequest failures and macro status after attaching the EA. Use a demo account to verify the intended entry-filter behavior. The YTD performance chart has FRED off and cannot be used to claim FRED increased profit or reduced drawdown. ## Trading Economics API inside the EA ### Requirements Use your own Trading Economics API key with News API entitlement. The customer EA calls the official API directly; the Python collector is no longer required for fetching news. No key means no Trading Economics requests or usable TE news in the EA. The technical trading engine continues normally. News is observation only, not a trade filter. ### 1. Allow WebRequest In MT5 Tools > Options > Expert Advisors, enable WebRequest for listed URLs and add https://api.tradingeconomics.com. Network calls are disabled in Strategy Tester and optimization. ### 2. Fill the EA inputs Open EA properties with F7. In Optional Trading Economics News, set Enable_TE_News_Shadow=true and enter your own key in TE_API_Key (displayed as Your Trading Economics API key). TE_Poll_Minutes defaults to 480 (8 hours); TE_Monthly_Request_Budget defaults to 450. Keep saved presets private because MT5 may store input keys in them. ### 3. Read the dashboard Trading Economics displays OFF, NO KEY, WAIT, OK (article count), NO NEWS, SHARED, STALE, BUSY or ERROR. Hover over the status for the detailed reason. READY means a usable response was read, not that every relevant gold headline was collected. 401, 403 and 429 errors distinguish authentication, News API access and rate limiting. ### Polling, quota and failure behavior The EA sends the key in an Authorization header, not in the URL. The local quota and next request time persist in Common/Files across restarts, sharing state by key on the same PC. Failed calls count and do not immediately retry. This counter does not know requests from other programs or PCs. The latest endpoint fetches up to 30 articles per request and keeps only news from the preceding 24 hours. It does not catch up all missed headlines. A request can occupy the EA event loop for up to its 5-second timeout. ### FinBERT handoff and testing The EA writes Common/Files/AlJamalGold/te_api_news.tsv. Do not run the old API collector alongside this direct mode. Only FinBERT tokenization still needs Python; its helper reads this file with no API key. 19 no-network MT5 checks and 7 Python transport checks passed. Authenticated live News API access is not yet verified. ## FinBERT ONNX: observation only ### What is implemented Enable_FinBERT_Shadow defaults to false. The EA runs ProsusAI/finbert on English financial title + description text and records positive, negative and neutral probabilities. These are sentiment labels, not gold BUY/SELL signals. No trade veto, direction mapping, daily aggregate or target threshold is deployed. ### Assets and tokenizer Use the separate verified FinBERT asset bundle supplied for this build: approximately 418 MiB FP32 ONNX plus manifest and tokenizer files. It is not included in the small website toolkit ZIP or the EA EX5. The toolkit includes build_finbert.py and pinned revision instructions for developers who export it themselves. Tokenization converts text into the token IDs and masks expected by the model; it runs in Python outside MT5. ### Install and collect Install Python tokenizer dependencies with python -m pip install -r requirements-tokenizer.txt. Place the verified bundle under assets/finbert in the toolkit folder. Run ./install_finbert.ps1 to copy the model and manifests to Common/Files/AlJamalGold/finbert. Then run: python tokenize_ea_news.py --news "COMMON_PATH/AlJamalGold/te_api_news.tsv" --assets assets/finbert --output "COMMON_PATH/AlJamalGold" --watch. Replace COMMON_PATH with MT5 Common/Files. This helper only tokenizes EA-fetched text; it makes no API requests and needs no key. ### EA paths Enable_FinBERT_Shadow=true. These fixed Common/Files paths are hidden from customer inputs: FinBERT_Model_File=AlJamalGold\finbert\finbert.onnx, FinBERT_Manifest_File=AlJamalGold\finbert\manifest.tsv, FinBERT_Tokens_File=AlJamalGold\finbert_tokens.tsv and FinBERT_Log_File=AlJamalGold\finbert_shadow.csv. Restart the tokenizer helper and EA after replacing an asset bundle. The FinBERT Shadow row reports readiness or processing errors; it is separate from Trading Economics news transport. ### Runtime and monitoring The timer checks every 60 seconds and processes at most one new article per check. PARTIAL means the batch is not fully processed. Text longer than 256 tokens is truncated and flagged. Production readers reject stale, future, invalid and simulated transports and skip current external snapshots in Strategy Tester. Model and tokenizer identity must match. ### Resource cost and limits On this development machine inference took 0.77-1.20 seconds per article, with a median near 0.90 seconds. The EA event loop is occupied during inference. Loading also consumes time and RAM. Observe responsiveness on your VPS before enabling it alongside execution. Restart can repeat logged articles; audit with model, article ID, content hash and availability time. English is tested; other languages and trading benefit are not established. ## Baseline, troubleshooting and release record ### Audited 2026 YTD baseline January 1 - September 25, 2026; XAUUSD M30; Standard Trend; ICMarketsSC-Demo; $10,000 initial deposit, risk 1%, leverage 1:100. Net +$856.32 (+8.56%); final balance $10,856.32; profit factor 1.29; maximum equity drawdown $822.89 (7.33%); 101 closed trades (43 BUY / 58 SELL); 62 wins, 39 losses. ### How to read the result MT5 generated Every tick (Model 0), not recorded real ticks. Reported commission and swap are included; no added execution delay/slippage stress. FRED, macro AI fallback, TE and FinBERT are all off; original news blackout is bypassed in Tester. The run uses the 1.16 source with an end-of-test audit export. Release 1.17 retains the technical execution functions. Its customer input cleanup hides legacy/debug controls, disables research logging and uses direct TE API transport; optional features remain off. The final customer build was not separately backtested. It is not a separate 1.17 run or live-performance evidence. ### If no trades appear Check Algo Trading permissions, InpAutoStart, symbol/timeframe, market hours, spread, risk sizing, safety state and Experts / Journal. A rejected entry can be normal. Keep optional data features off while checking the core setup. Do not disable safety controls simply to force activity. ### If optional data does not load For FRED, check the key, WebRequest allowlist and refresh logs. For macro AI, check its separate enable switch, full endpoint, exact model ID, provider key, allowlist and Experts logs; it is only called at FRED scores 3/4. For TE, check the EA key, WebRequest allowlist, News API entitlement and quota. For FinBERT token input, check te_api_news.tsv and the local tokenizer helper. For FinBERT, verify the model bundle, token file, manifest identity, Python dependencies and available RAM. Keep the PC/VPS UTC clock correct. ### Updating and sharing diagnostics Save your .set file and review new defaults before installing an update. Do not place the EA EX5 on the public website; customers obtain their licensed copy through Market. Share version, sanitized settings and error messages through the product support channel. Remove keys and account-identifying information from diagnostics. ### Verification and further reading 21 offline Python collector/tokenizer tests passed; 22 MT5 FinBERT fixture checks passed. Synthetic tests validate parsing, inference parity and error handling, not authenticated news coverage or market profitability. Online manual: https://aljamalgold.app/manual/. Release notes: https://aljamalgold.app/release-notes/. Performance: https://aljamalgold.app/performance/.