Risk Management

Overview

Risk Management includes 4 tools for this workflow area.

Available tools: calculate_lot_size, check_portfolio_exposure, get_correlation_matrix, get_risk_summary.

Use the parameter tables and examples below as the canonical request contract.

calculate_lot_size

Calculates the appropriate lot size for a trade based on account equity and risk parameters. Uses live account equity and symbol contract specs from the connected terminal. Returns the recommended lot size, risk amount in account currency, and pip value. Returns LOT_TOO_SMALL if the computed lots are below the symbol minimum. Available at Free+ tier (no analytics capability required).

Parameters

Example Request

{
  "tool": "calculate_lot_size",
  "arguments": {
    "symbol": "EURUSD",
    "risk_percent": 1,
    "stop_loss_pips": 1
  }
}

check_portfolio_exposure

Evaluates aggregate portfolio exposure across open positions plus an optional proposed position against configurable caps, and returns a proceed | caution | block verdict. Currency exposure uses resolveSymbolCurrencies (NOT get_risk_summary's symbol.slice(0,3), which drops quote-currency exposure) -- a resolved FX pair applies +direction to the base currency and -direction to the quote; an unresolvable symbol forces caution and is never allowed to read as proceed. Clusters are formed by single-linkage correlation (over each position's own D1/20-bar history) at cluster_threshold. open_risk_pct sums distance-to-SL risk (in the account's own currency) for positions that have a stop AND whose symbol's quote currency matches the account currency; a position without a stop (sl === 0) is marked unbounded_risk:true, and one whose quote currency differs from the account currency is excluded from the sum (no cross-rate conversion is fabricated) and reported via unconverted_currency/UNCONVERTED_RISK_CURRENCY -- both cap the verdict at caution. Notional is volume * contract_size * price, included in a currency bucket only when that currency equals the account's own currency (never a fabricated cross-rate conversion); a symbol whose OTHER resolved currency doesn't match is silently excluded from that bucket alone (e.g. EURUSD's EUR leg on a USD account), while a symbol where NEITHER resolved currency matches (e.g. EURGBP, or a non-USD-denominated index, on a USD account) is excluded from all notional/cluster aggregation and reported via UNCONVERTED_NOTIONAL/fail_safe_reasons, capping the verdict at caution. notional_pct_equity is leverage-adjusted (((notional / leverage) / equity) * 100, approximating margin committed rather than face value) using the account's own leverage, returned as the top-level leverage field. When leverage is unavailable or <= 0, LEVERAGE_UNAVAILABLE is added to fail_safe_reasons (capping verdict at caution), leverage and every currency's notional_pct_equity report null for that call, and max_currency_notional_pct is excluded from breaches (every other cap still evaluates normally) -- the old unadjusted ratio is never silently reintroduced as a fallback. Response distinguishes current (open positions only) from projected (including the proposed position). Default caps: max_currency_notional_pct=30, max_cluster_notional_pct=40, max_open_risk_pct=5; caps are per-call parameters and are never persisted. Distinct open symbols (plus the proposed symbol, if any) are capped at 12 for the EA dispatch fan-out, same as get_correlation_matrix -- an account with more open symbols than that has the excess reported in skipped_for_clustering with reason SYMBOL_CAP_EXCEEDED, which forces the verdict to at best caution. Advisory only: never opens, closes, or modifies any order or position, regardless of verdict. Requires the analytics capability (Team+ tier).

Parameters

Example Request

{
  "tool": "check_portfolio_exposure",
  "arguments": {}
}

get_correlation_matrix

Returns the full symmetric NxN Pearson correlation matrix for 2-12 symbols. Dispatches exactly one GET_BARS per symbol (never one per pair). Defaults to correlating log returns (method=returns), not price levels, because level correlation reports near-1.0 for any two trending series regardless of true co-movement -- the false negative that can make a concentrated book look diversified. method=close is available for parity with get_correlation's default (get_correlation also accepts method=returns to match this tool's default instead); the two tools' own defaults still differ and may disagree for the same pair unless the same method is passed to both. Symbols the terminal cannot supply are excluded from the matrix and listed in skipped[]; mismatched histories truncate to the common overlap (bars_used). Fewer than 2 usable symbols after skips is returned as an error naming the usable count, not a degenerate matrix. Cached 15 minutes per (symbols, timeframe, bars, method). Advisory only: never opens, closes, or modifies any order or position. Requires the analytics capability (Team+ tier).

Parameters

Example Request

{
  "tool": "get_correlation_matrix",
  "arguments": {
    "symbols": [],
    "timeframe": "M1"
  }
}

Usage Notes

• Start with a smaller count/bars value while iterating, then increase once the workflow is stable.
• Use one timeframe for quick checks and multiple timeframes only when you need cross-timeframe analysis.

get_risk_summary

Returns a portfolio risk overview: aggregate currency exposure and margin utilisation. Currency exposure resolves each symbol to its base/quote currencies (via resolveSymbolCurrencies, same as check_portfolio_exposure) and reports net lots signed by direction -- an FX pair contributes to both its base and quote currency, not just the first 3 characters of the symbol. A symbol that cannot be resolved to any currency (e.g. an unrecognized share CFD) is omitted from currency_exposure and listed in unresolved_symbols instead of silently dropped. margin_level is derived server-side as equity/margin*100 (null when margin is 0), since MT5 does not report it directly. Requires the analytics capability (Team+ tier).

Parameters

No parameters.

Example Request

{
  "tool": "get_risk_summary",
  "arguments": {}
}