Skip to content

MT5Sugar · Convenience Layer - Complete Overview

High-level convenience methods for common trading operations. Simplified API with auto-normalization, risk management, and batch operations. ~50 methods organized in 11 functional groups.

📁 What lives here

1. Symbol Helpers (12 methods)

Essential symbol information and normalization utilities.

2. Market Orders (2 methods)

Instant execution at market price.

3. Pending Orders (4 methods)

Entry orders with exact price.

4. Pending Orders with Points (4 methods)

Simplified pending orders via offset.

5. Position Management (5 methods)

Modify and close positions.

6. Advanced Batch Operations (3 methods)

Separate positions vs orders control.

7. Risk Management (3 methods)

Position sizing from $ risk.

8. Advanced Helpers (4 methods)

Additional utilities.

9. Account & Position Helpers (10 methods)

Quick account state access.

10. Snapshot Helpers (2 methods + 2 classes)

Complete state snapshots.

11. History Helpers (2 methods)

Historical data retrieval.

🧭 Plain English

What is MT5Sugar?

Convenience layer on top of MT5Service/MT5Account with:

  • Auto-normalization (volumes, prices)
  • Auto symbol selection
  • Simplified APIs
  • Built-in risk management
  • Batch operations

When to use:

  • ✅ Production trading bots
  • ✅ Quick prototypes
  • ✅ Risk-managed trading
  • ✅ Beginners

When NOT to use:

  • ❌ Need exact control over parameters
  • ❌ Custom normalization logic
  • ❌ Advanced order types (STOP_LIMIT)

Rule of thumb: Start with MT5Sugar → drop down only when needed.

Quick choose

Trading

Need Use Inputs
Open BUY at market buyMarket symbol, vol, SL, TP
Open SELL at market sellMarket symbol, vol, SL, TP
BUY at price (below) buyLimit symbol, vol, price, SL, TP
SELL at price (above) sellLimit symbol, vol, price, SL, TP
BUY on breakout (above) buyStop symbol, vol, price, SL, TP
SELL on breakdown (below) sellStop symbol, vol, price, SL, TP
BUY with points offset buyLimitPoints symbol, vol, offset, SL pts, TP pts
BUY with auto volume ($risk) buyByRisk symbol, SL pts, $risk, TP pts

Position Management

Need Use Inputs
Change SL/TP modifyPosition ticket, SL, TP
Close position closePosition ticket (+ vol)
Close all for symbol closeAll symbol, isBuy filter
Close all BUY closeAllBuy symbol
Close all SELL closeAllSell symbol
Close only positions closeAllPositions symbol, isBuy
Cancel only pending orders closeAllPending symbol, isBuy

Symbol & Account Info

Need Use Returns
Current Bid/Ask getBid / getAsk double
Point size getPoint double
Spread getSpread int (points)
Normalize price/volume normalizePrice/Volume double
Full symbol snapshot getSymbolSnapshot SymbolSnapshot
Account balance/equity getBalance/Equity double
Full account snapshot getAccountSnapshot AccountSnapshot

Risk Management

Need Use Inputs
Calculate lot size from $risk calculateVolume symbol, SL pts, $risk
Open BUY with auto volume buyByRisk symbol, SL pts, $risk, TP
Open SELL with auto volume sellByRisk symbol, SL pts, $risk, TP

❌ Cross-refs & gotchas

Auto-normalization

  • Volumes/prices normalized automatically
  • Symbols added to Market Watch automatically
  • May change input values slightly

SL/TP rules

BUY: SL below entry, TP above entry SELL: SL above entry, TP below entry

Pending: * BUY LIMIT: below Ask, triggers on drop * SELL LIMIT: above Bid, triggers on rise * BUY STOP: above Ask, triggers on rise (breakout) * SELL STOP: below Bid, triggers on drop (breakdown)

Execution prices

  • BUY executes at Ask (higher)
  • SELL executes at Bid (lower)
  • Spread = Ask - Bid (cost on entry)

Risk management

  • Uses points, not pips
  • Check broker min/max volume limits
  • 2% rule: max 2% risk per trade

Batch operations

  • Continue on failures
  • Return count of successful ops
  • Failed ops logged to System.err

Points vs Pips

  • 5-digit: 1 pip = 10 points
  • 3-digit: 1 pip = 1 point
  • All methods use points

null vs 0

  • null = keep current / no SL-TP
  • 0 / 0.0 = no SL-TP / remove

Errors

  • Throw ApiExceptionMT5 on failure
  • Code 10009 = success
  • Common: invalid stops, market closed

🟢 Minimal snippets

// Market orders
long ticket = sugar.buyMarket("EURUSD", 0.1, 1.08000, 1.09000);
long ticket = sugar.sellMarket("GBPUSD", 0.1, 1.27000, 1.26000);

// Pending with price
double entry = sugar.getAsk("EURUSD") - (50 * sugar.getPoint("EURUSD"));
long ticket = sugar.buyLimit("EURUSD", 0.1, entry, null, null);

// Pending with points offset
long ticket = sugar.buyLimitPoints("EURUSD", 0.1, -50, 40, 120);

// Risk-based
double risk = sugar.getBalance() * 0.02;
long ticket = sugar.buyByRisk("EURUSD", 50, risk, 100);

// Close positions
sugar.closePosition(123456789);
int closed = sugar.closeAll("EURUSD");
int closed = sugar.closeAllBuy(null);

// Modify
sugar.modifyPosition(123456789, newSL, newTP);

// Info
double balance = sugar.getBalance();
double bid = sugar.getBid("EURUSD");
var snapshot = sugar.getAccountSnapshot();
var symSnap = sugar.getSymbolSnapshot("EURUSD");

// Calculate volume
double vol = sugar.calculateVolume("EURUSD", 50, 100.0);

// History
var history = sugar.getOrdersHistoryLastDays(7, null);
var posHistory = sugar.getPositionsHistoryPaged(0, 50);