Skip to content

"Vibe-Trading: Your Personal Trading Agent"

fix(mt5): resolve broker symbols in symbol search

lorenzozanee7ada7acd6693
diff --git a/README.md b/README.md
index ef102f9b4..4e0c56fb8 100644
--- a/README.md
+++ b/README.md
@@ -1574,6 +1574,12 @@ Configure `~/.vibe-trading/mt5.json` (create it yourself; `chmod 600` where supp
}
```
+For broker-confirmed `search_symbol` results, set `terminal_path` in this file
+to the selected terminal executable. Symbol search reads only `symbol_info`
+and `symbols_get`, passes no login credentials, and does not read account or
+position data or alter Market Watch. Without an explicit path it returns no
+MT5 candidate.
+
Then:
```bash
diff --git a/agent/src/tools/symbol_search_tool.py b/agent/src/tools/symbol_search_tool.py
index 6f42c4a87..f3fdb92e2 100644
--- a/agent/src/tools/symbol_search_tool.py
+++ b/agent/src/tools/symbol_search_tool.py
@@ -113,6 +113,8 @@ def _metal_or_fx_legs(value: str) -> tuple[str, str] | None:
clean = str(value or "").strip().upper()
if clean.endswith("=X"):
clean = clean[:-2]
+ if clean.endswith(".FX"):
+ clean = clean[:-3]
if "-" in clean or "/" in clean:
base, _, quote = (
clean.partition("-") if "-" in clean else clean.partition("/")
@@ -290,6 +292,10 @@ class SymbolSearchTool(BaseTool):
)
sources["fx_normalizer"] = "ok"
+ if connector_source == "mt5":
+ # The selected terminal must confirm an MT5 identity.
+ candidates = [c for c in candidates if c.get("source") == "mt5"]
+
if crypto_pair is not None:
# A pair query is an exact instrument assertion. Near-string Yahoo
# hits such as AETHUSDT-USD are different assets and must not enter
@@ -511,7 +517,9 @@ def _search_selected_connector(
limit: int,
) -> tuple[List[Dict[str, Any]], str | None, str | None]:
"""Resolve an explicit pair against the active crypto connector, if supported."""
- if _canonical_crypto_pair(query) is None:
+ crypto_pair = _canonical_crypto_pair(query)
+ mt5_pair = _metal_or_fx_legs(query)
+ if crypto_pair is None and mt5_pair is None:
return [], None, None
# Lazy imports keep the generic symbol tool usable when optional connector
@@ -526,7 +534,11 @@ def _search_selected_connector(
logger.debug("selected connector lookup failed for %r: %s", query, exc)
return [], None, None
- if profile.connector != "binance":
+ if profile.connector == "binance" and crypto_pair is None:
+ return [], None, None
+ if profile.connector == "mt5" and mt5_pair is None:
+ return [], None, None
+ if profile.connector not in {"binance", "mt5"}:
return [], None, None
source = profile.connector
@@ -551,6 +563,34 @@ def _search_selected_connector(
rows = payload.get("instruments")
rows = rows if isinstance(rows, list) else []
candidates: List[Dict[str, Any]] = []
+ if profile.connector == "mt5" and mt5_pair is not None:
+ requested_base = "".join(mt5_pair)
+ for row in rows:
+ if not isinstance(row, dict):
+ continue
+ native_symbol = str(
+ row.get("native_symbol") or row.get("symbol") or ""
+ ).strip()
+ resolved_base = native_symbol.upper()
+ if resolved_base.endswith(".FX"):
+ resolved_base = resolved_base[:-3]
+ if not resolved_base.startswith(requested_base):
+ continue
+ candidates.append(
+ {
+ "symbol": query.strip().upper(),
+ "name": str(row.get("name") or native_symbol).strip() or None,
+ "market": str(row.get("market") or "forex"),
+ "type": str(row.get("type") or "cfd"),
+ "exchange": str(row.get("exchange") or row.get("venue") or "MT5"),
+ "venue": str(row.get("venue") or row.get("exchange") or "MT5"),
+ "source": source,
+ "profile_id": profile.id,
+ "native_symbol": native_symbol,
+ }
+ )
+ return candidates, source, "ok"
+
for row in rows:
if not isinstance(row, dict):
continue
diff --git a/agent/src/trading/connectors/mt5/_client.py b/agent/src/trading/connectors/mt5/_client.py
index a5babac48..f9fd9cc08 100644
--- a/agent/src/trading/connectors/mt5/_client.py
+++ b/agent/src/trading/connectors/mt5/_client.py
@@ -2,9 +2,9 @@
The ``MetaTrader5`` Python API is process-global and stateful: one
``initialize()`` per process, module-level functions, ``shutdown()`` to
-detach. Every operation therefore runs inside :func:`_session` — a lock,
-initialize, bidirectional profile/identity verification, work, shutdown —
-so no read or write can ever execute against the wrong account class.
+detach. Account-bound operations run inside :func:`_session` with profile
+identity verification. Symbol search uses a separate terminal-path-only
+session and reads symbol metadata without account or trading operations.
"""
from __future__ import annotations
@@ -272,6 +272,23 @@ def _session(cfg: MT5Config) -> Iterator[Any]:
pass
+@contextmanager
+def _catalog_session(cfg: MT5Config) -> Iterator[Any]:
+ """Attach by terminal path for symbol metadata without account access."""
+ if not cfg.terminal_path:
+ raise MT5ConfigError("terminal_path is required for MT5 symbol search")
+ mt5 = _require_mt5()
+ with _MT5_LOCK:
+ if not mt5.initialize(cfg.terminal_path, timeout=int(cfg.timeout * 1000)):
+ raise MT5ConnectionError(
+ f"MT5 initialize failed ({_last_error(mt5)})"
+ )
+ try:
+ yield mt5
+ finally:
+ mt5.shutdown()
+
+
def _assert_profile(cfg: MT5Config, account: Any, mt5: Any) -> None:
"""Hard bidirectional identity guard, run inside every session.
diff --git a/agent/src/trading/connectors/mt5/reads.py b/agent/src/trading/connectors/mt5/reads.py
index fc5ebd755..2d1585e36 100644
--- a/agent/src/trading/connectors/mt5/reads.py
+++ b/agent/src/trading/connectors/mt5/reads.py
@@ -1,7 +1,8 @@
"""MT5 read operations: status, account, positions, orders, quote, history.
-Every read runs through :func:`_client._session` (identity guard included)
-and returns a fail-closed ``{"status": "error", ...}`` envelope instead of
+Account-bound reads use :func:`_client._session` and its identity guard.
+Symbol search reads only metadata through :func:`_client._catalog_session`.
+Both return a fail-closed ``{"status": "error", ...}`` envelope instead of
raising, so tools and CLI degrade cleanly when the SDK/terminal is absent.
"""
@@ -23,6 +24,7 @@ from src.trading.connectors.mt5._client import (
_resolve_symbol,
_usd_contract_value,
)
+from src.trading.connectors.mt5.symbols import classify_mt5_symbol
_MT5_ERRORS = (MT5DependencyError, MT5ConfigError, MT5ConnectionError, MT5ProfileMismatchError)
@@ -238,6 +240,70 @@ def get_quote(symbol: str, *, config: MT5Config | None = None, **_: Any) -> dict
return _envelope(cfg, symbol=clean, resolved_symbol=name, quote=quote)
+def search_instruments(
+ query: str,
+ *,
+ config: MT5Config | None = None,
+ limit: int = 10,
+) -> dict[str, Any]:
+ """Resolve one explicit symbol against the configured terminal catalog."""
+ cfg = config or _client.load_config()
+ raw = str(query or "").strip().upper()
+ base = raw[:-2] if raw.endswith("=X") else raw
+ base = _client.normalize_base(base)
+ if not base or not base.isalnum():
+ return _error(cfg, "symbol search requires an explicit symbol", instruments=[])
+
+ try:
+ bounded_limit = max(1, min(int(limit), 50))
+ except (TypeError, ValueError, OverflowError):
+ bounded_limit = 10
+
+ try:
+ with _client._catalog_session(cfg) as mt5:
+ candidates = []
+ if cfg.symbol_suffix:
+ candidates.append(base + cfg.symbol_suffix)
+ candidates.append(base)
+ info = None
+ for name in candidates:
+ info = mt5.symbol_info(name)
+ if info is not None:
+ break
+ if info is None:
+ matches = sorted(
+ (
+ item
+ for item in (mt5.symbols_get(group=f"{base}*") or ())
+ if str(getattr(item, "name", "")).upper().startswith(base)
+ ),
+ key=lambda item: (
+ len(str(getattr(item, "name", ""))),
+ str(getattr(item, "name", "")),
+ ),
+ )
+ info = matches[0] if matches else None
+ except _MT5_ERRORS as exc:
+ return _error(cfg, str(exc), instruments=[])
+
+ instruments = []
+ if info is not None:
+ name = str(getattr(info, "name", "") or "").strip()
+ if name:
+ instrument_type, _ = classify_mt5_symbol(name)
+ instruments.append(
+ {
+ "symbol": name,
+ "native_symbol": name,
+ "market": "fx" if instrument_type.value == "forex" else "mt5",
+ "type": instrument_type.value,
+ "exchange": cfg.server or "MT5",
+ "venue": cfg.server or "MT5",
+ }
+ )
+ return _envelope(cfg, query=query, instruments=instruments[:bounded_limit])
+
+
def get_historical_bars(
symbol: str,
*,
diff --git a/agent/src/trading/connectors/mt5/sdk.py b/agent/src/trading/connectors/mt5/sdk.py
index 11e9b4599..114d7c081 100644
--- a/agent/src/trading/connectors/mt5/sdk.py
+++ b/agent/src/trading/connectors/mt5/sdk.py
@@ -36,6 +36,7 @@ from src.trading.connectors.mt5.reads import (
get_open_orders,
get_positions,
get_quote,
+ search_instruments,
)
__all__ = [
@@ -62,4 +63,5 @@ __all__ = [
"get_open_orders",
"get_positions",
"get_quote",
+ "search_instruments",
]
diff --git a/agent/src/trading/service.py b/agent/src/trading/service.py
index b641ad48a..b60cd12d1 100644
--- a/agent/src/trading/service.py
+++ b/agent/src/trading/service.py
@@ -377,6 +377,16 @@ def search_instruments(
limit=limit,
),
)
+ if profile.connector == "mt5" and profile.transport == "broker_sdk":
+ module = _sdk_module(profile.connector)
+ return _with_profile(
+ profile,
+ module.search_instruments(
+ query,
+ config=_sdk_config(profile, module, overrides),
+ limit=limit,
+ ),
+ )
if profile.connector != "etoro":
return _unsupported_etoro(profile, "instruments.search")
module = _sdk_module(profile.connector)
diff --git a/agent/tests/test_mt5_connector.py b/agent/tests/test_mt5_connector.py
index e0f70863d..19cbc49ab 100644
--- a/agent/tests/test_mt5_connector.py
+++ b/agent/tests/test_mt5_connector.py
@@ -246,6 +246,55 @@ class TestNormalizeBase:
assert normalize_base(" ") == ""
[email protected]("query", ["XAUUSD", "XAU/USD", "XAUUSD=X", "XAUUSD.FX"])
+def test_symbol_search_uses_selected_terminal_without_account_or_write_calls(
+ fake_mt5: FakeMT5, query: str
+) -> None:
+ from src.trading.connectors.mt5 import sdk
+
+ def forbidden_account_read() -> Any:
+ raise AssertionError("symbol search must not read account information")
+
+ def forbidden_write(*_args: Any, **_kwargs: Any) -> Any:
+ raise AssertionError("symbol search must not call trading operations")
+
+ fake_mt5.account_info = forbidden_account_read # type: ignore[method-assign]
+ fake_mt5.symbol_select = forbidden_write # type: ignore[method-assign]
+ fake_mt5.order_check = forbidden_write # type: ignore[method-assign]
+ fake_mt5.order_send = forbidden_write # type: ignore[method-assign]
+ result = sdk.search_instruments(
+ query,
+ config=_paper_config(terminal_path="C:/mt5/terminal64.exe"),
+ )
+
+ assert result["status"] == "ok"
+ assert result["instruments"] == [
+ {
+ "symbol": "XAUUSDm",
+ "native_symbol": "XAUUSDm",
+ "market": "mt5",
+ "type": "cfd",
+ "exchange": "Exness-MT5Trial8",
+ "venue": "Exness-MT5Trial8",
+ }
+ ]
+ assert fake_mt5.initialize_calls[-1] == {
+ "args": ("C:/mt5/terminal64.exe",),
+ "kwargs": {"timeout": 15_000},
+ }
+ assert fake_mt5.shutdown_calls == 1
+
+
+def test_symbol_search_without_terminal_path_fails_closed(fake_mt5: FakeMT5) -> None:
+ from src.trading.connectors.mt5 import sdk
+
+ result = sdk.search_instruments("XAUUSD", config=_paper_config())
+
+ assert result["status"] == "error"
+ assert result["instruments"] == []
+ assert fake_mt5.initialize_calls == []
+
+
class TestSplitSuffix:
def test_splits_broker_suffix(self) -> None:
assert split_suffix("EURUSDM") == ("EURUSD", "M")
diff --git a/agent/tests/test_sdk_connectors.py b/agent/tests/test_sdk_connectors.py
index 16cbbfbb2..0c307e9ed 100644
--- a/agent/tests/test_sdk_connectors.py
+++ b/agent/tests/test_sdk_connectors.py
@@ -21,6 +21,7 @@ from src.trading.connectors.alpaca import sdk as al
from src.trading.connectors.alpaca.classification import ALPACA_TOOL_CLASS
from src.trading.connectors.binance import sdk as bn
from src.trading.connectors.binance.classification import BINANCE_TOOL_CLASS
+from src.trading.connectors.mt5 import sdk as mt5
from src.trading.connectors.dhan import sdk as dh
from src.trading.connectors.dhan.classification import DHAN_TOOL_CLASS
from src.trading.connectors.futu import sdk as ft
@@ -606,6 +607,26 @@ def test_service_routes_instrument_search_to_selected_binance_profile(monkeypatc
assert result["connector"] == "binance"
+def test_service_routes_instrument_search_to_selected_mt5_profile(monkeypatch) -> None:
+ captured = {}
+
+ def _build_config(profile_config, overrides):
+ return SimpleNamespace(profile=profile_config["profile"])
+
+ def _search(query, *, config, limit):
+ captured.update(query=query, profile=config.profile, limit=limit)
+ return {"status": "ok", "instruments": [{"symbol": "XAUUSDm"}]}
+
+ monkeypatch.setattr(mt5, "build_config", _build_config)
+ monkeypatch.setattr(mt5, "search_instruments", _search)
+
+ result = service.search_instruments("XAUUSD", "mt5-paper-sdk", limit=3)
+
+ assert captured == {"query": "XAUUSD", "profile": "paper", "limit": 3}
+ assert result["profile_id"] == "mt5-paper-sdk"
+ assert result["connector"] == "mt5"
+
+
def test_binance_service_unconfigured(monkeypatch, tmp_path) -> None:
monkeypatch.setattr(bn, "get_runtime_root", lambda: tmp_path)
result = service.check_connection("binance-paper-sdk")
diff --git a/agent/tests/test_symbol_search_tool.py b/agent/tests/test_symbol_search_tool.py
index 56203f39f..459fed237 100644
--- a/agent/tests/test_symbol_search_tool.py
+++ b/agent/tests/test_symbol_search_tool.py
@@ -12,6 +12,7 @@ from unittest.mock import patch
import pytest
+from src.agent.grounding.ledger import GroundingLedger
from src.trading import profiles as trading_profiles
from src.trading import service as trading_service
from src.tools import symbol_search_tool as ss
@@ -808,6 +809,102 @@ class TestFxPairAlignment:
assert ss._canonical_crypto_pair("BTC/USDT") == "BTC-USDT"
assert ss._canonical_crypto_pair("BTCUSDT") == "BTC-USDT"
+ @pytest.mark.parametrize("query", ["XAUUSD", "XAU/USD", "XAUUSD=X", "XAUUSD.FX"])
+ def test_selected_mt5_profile_resolves_broker_confirmed_metal(
+ self, monkeypatch, tmp_path, query: str
+ ) -> None:
+ monkeypatch.setattr(
+ trading_profiles, "load_selected_profile_id", lambda: "mt5-paper-sdk"
+ )
+ monkeypatch.setattr(
+ trading_service,
+ "search_instruments",
+ lambda query, profile_id, *, limit: {
+ "status": "ok",
+ "instruments": [
+ {
+ "symbol": "XAUUSD",
+ "native_symbol": "XAUUSDm",
+ "market": "mt5",
+ "type": "cfd",
+ "exchange": "Exness-MT5Trial8",
+ }
+ ],
+ },
+ )
+ with patch.object(
+ ss.eastmoney_client,
+ "get_json",
+ return_value={"QuotationCodeTable": {"Data": []}},
+ ), patch.object(
+ ss.yahoo_client,
+ "search",
+ return_value=[
+ {
+ "symbol": "XAUUSD=X",
+ "shortname": "Gold",
+ "exchange": "CCY",
+ "quoteType": "CURRENCY",
+ }
+ ],
+ ):
+ result = ss.SymbolSearchTool().execute(query=query)
+ data = json.loads(result)["data"]
+
+ assert data["sources"]["mt5"] == "ok"
+ assert data["count"] == 1
+ candidate = data["candidates"][0]
+ assert candidate["symbol"] == query.upper()
+ assert candidate["native_symbol"] == "XAUUSDm"
+ assert candidate["venue"] == "Exness-MT5Trial8"
+ assert candidate["profile_id"] == "mt5-paper-sdk"
+
+ ledger = GroundingLedger(run_dir=tmp_path, user_message=f"Quote {query}")
+ ledger.ingest_tool_result(
+ tool_name="search_symbol",
+ arguments={"query": query},
+ result=result,
+ call_id="resolve-mt5-symbol",
+ success=True,
+ )
+ assert ledger.identity_status == "locked"
+
+ @pytest.mark.parametrize(
+ "response",
+ [
+ {"status": "ok", "instruments": []},
+ {"status": "error", "error": "terminal unavailable", "instruments": []},
+ ],
+ )
+ def test_mt5_no_match_does_not_create_candidate(
+ self, monkeypatch, response: dict
+ ) -> None:
+ monkeypatch.setattr(
+ trading_profiles, "load_selected_profile_id", lambda: "mt5-paper-sdk"
+ )
+ monkeypatch.setattr(
+ trading_service, "search_instruments", lambda *args, **kwargs: response
+ )
+ with patch.object(
+ ss.eastmoney_client,
+ "get_json",
+ return_value={"QuotationCodeTable": {"Data": []}},
+ ), patch.object(
+ ss.yahoo_client,
+ "search",
+ return_value=[
+ {
+ "symbol": "XAUUSD=X",
+ "shortname": "Gold",
+ "exchange": "CCY",
+ "quoteType": "CURRENCY",
+ }
+ ],
+ ):
+ data = json.loads(ss.SymbolSearchTool().execute(query="XAUUSD"))["data"]
+
+ assert data["candidates"] == []
+
def test_fx_query_returns_canonical_candidate_when_yahoo_unavailable(self) -> None:
"""A throttled/failed Yahoo must not turn a canonical pair into nothing."""
with patch.object(