Skip to content

MT5Sugar - Complete API Reference

High-level convenience methods for MetaTrader 5 trading automation in C#

MT5Sugar extends MT5Service with convenient methods for:

  • 🎯 Risk-based position sizing (fixed dollar risk)
  • 📊 Automatic volume and price normalization
  • 🔄 Bulk operations (close all positions, cancel all orders)
  • 📈 DOM (Market Depth) - order book analysis
  • ✅ Pre-flight order validation and margin checking
  • 📉 P&L monitoring and position statistics

📖 Important: How to Work with Streaming Subscriptions - Complete guide to real-time data streams

[01] 🔧 INFRASTRUCTURE

Basic infrastructure for working with symbols

Method Description Documentation
EnsureSelected() Ensures symbol is selected and synchronized in MT5 → Docs

[02] 📸 SNAPSHOTS

Instant snapshots of account and symbol state

Method Description Documentation
GetAccountSnapshot() Complete account snapshot (balance, margin, equity) → Docs
GetSymbolSnapshot() Complete symbol snapshot (prices, spread, limits) → Docs

Data classes:

  • AccountSnapshot - account data structure
  • SymbolSnapshot - symbol data structure

[03] 🔢 NORMALIZATION & UTILS

Utilities for price normalization and unit conversion

Method Description Documentation
GetPointAsync() Get point size for symbol → Docs
GetDigitsAsync() Number of decimal places → Docs
NormalizePriceAsync() Normalize price by TickSize → Docs
PointsToPipsAsync() Convert points to pips → Docs
GetSpreadPointsAsync() Current spread in points → Docs

[04] 📜 HISTORY HELPERS

Retrieve order and position history with pagination

Method Description Documentation
OrdersHistoryLast() Closed orders history for N days → Docs
PositionsHistoryPaged() Position history with pagination → Docs

[05] 🌊 STREAMS HELPERS

Bounded streaming - reading ticks and trades with limits

Method Description Documentation
ReadTicks() Read N ticks or until timeout → Docs
ReadTrades() Read N trade events or until timeout → Docs

[06] 💹 TRADING — MARKET & PENDING

Placing and managing market and pending orders

Method Description Documentation
PlaceMarket() Place market order (BUY/SELL) → Docs
PlacePending() Place pending order (Limit/Stop) → Docs
ModifySlTpAsync() Modify SL/TP of existing order → Docs
CloseByTicket() Close position by ticket → Docs
CloseAll() Close all positions (with filters) → Docs

[07] ⚖️ VOLUME & PRICE UTILITIES

Critical utilities for volume calculation and price operations

Method Description Documentation
CalcVolumeForRiskAsync() PRIMARY METHOD - calculate volume by risk → Docs
GetVolumeLimitsAsync() Get Min/Max/Step for symbol volume → Docs
NormalizeVolumeAsync() Normalize volume to broker limits → Docs
GetTickValueAndSizeAsync() Get TickValue and TickSize → Docs
PriceFromOffsetPointsAsync() Calculate price from point offset → Docs

[08] 📍 PENDING HELPERS (BY POINTS)

Pending orders with point-based distance

Method Description Documentation
BuyLimitPoints() Buy Limit N points below Ask → Docs
SellLimitPoints() Sell Limit N points above Bid → Docs
BuyStopPoints() Buy Stop N points above Ask → Docs
SellStopPoints() Sell Stop N points below Bid → Docs

[09] 💰 MARKET BY RISK

Market orders with fixed dollar risk

Method Description Documentation
BuyMarketByRisk() BUY with automatic volume calculation by risk → Docs
SellMarketByRisk() SELL with automatic volume calculation by risk → Docs

Example: 

// Risk exactly $100 with 50-point SL
await svc.BuyMarketByRisk("EURUSD", stopPoints: 50, riskMoney: 100);

[10] 🧹 BULK CONVENIENCE

Bulk operations with orders and positions

Method Description Documentation
CancelAll() Cancel all pending orders → Docs
CloseAllPositions() Close all market positions → Docs
CloseAllPending() Close/cancel all pending orders → Docs

[11] 📊 MARKET DEPTH (DOM)

Level II market data - order book analysis

Method Description Documentation
SubscribeToMarketBookAsync() Subscribe to order book (returns IDisposable) → Docs
GetMarketBookSnapshotAsync() Get order book snapshot → Docs
GetBestBidAskFromBookAsync() Best Bid/Ask from order book → Docs
CalculateLiquidityAtLevelAsync() Calculate liquidity at price level → Docs

Data class:

  • MarketBookSubscription - subscription management

[12] ✅ ORDER VALIDATION

Pre-flight checks to prevent errors

Method Description Documentation
ValidateOrderAsync() Full order validation before sending → Docs
CalculateBuyMarginAsync() Calculate margin for BUY order → Docs
CalculateSellMarginAsync() Calculate margin for SELL order → Docs
CheckMarginAvailabilityAsync() Check free margin sufficiency → Docs

[13] ⏰ SESSION TIME

Trading and quote session information

Method Description Documentation
GetQuoteSessionAsync() Quote session time (when prices are visible) → Docs
GetTradeSessionAsync() Trading session time (when trading is allowed) → Docs

[14] 📈 POSITION MONITORING

Monitoring and analyzing open positions

Method Description Documentation
GetProfitablePositionsAsync() Get all profitable positions → Docs
GetLosingPositionsAsync() Get all losing positions → Docs
GetTotalProfitLossAsync() Total P&L across all positions → Docs
GetPositionCountAsync() Number of open positions → Docs
GetPositionStatsBySymbolAsync() Position statistics by symbol → Docs

🎯 Common Use Cases

Simple market order

// Buy 0.10 lots EURUSD
var result = await svc.PlaceMarket("EURUSD", 0.10, isBuy: true);
Console.WriteLine($"Order #{result.Order} at {result.Price:F5}");

Order with fixed risk ($100)

// Risk $100, stop 50 points, take 150 points
await svc.BuyMarketByRisk("EURUSD",
    stopPoints: 50,
    riskMoney: 100,
    tpPoints: 150);

Margin check before trading

var (hasEnough, free, required) = await svc.CheckMarginAvailabilityAsync(
    "EURUSD", volume: 1.0, isBuy: true);

if (hasEnough)
{
    await svc.PlaceMarket("EURUSD", 1.0, isBuy: true);
}
else
{
    Console.WriteLine($"Insufficient margin: need ${required}, have ${free}");
}

Emergency close on drawdown

double totalPL = await svc.GetTotalProfitLossAsync();

if (totalPL < -500)
{
    Console.WriteLine("🚨 Drawdown $500 - closing all positions!");
    await svc.CloseAllPositions();
}

Order book (DOM) analysis

using (await svc.SubscribeToMarketBookAsync("EURUSD"))
{
    var book = await svc.GetMarketBookSnapshotAsync("EURUSD");
    var (bestBid, bestAsk) = await svc.GetBestBidAskFromBookAsync("EURUSD");

    var liquidity = await svc.CalculateLiquidityAtLevelAsync(
        "EURUSD", bestBid, isBuy: true);

    Console.WriteLine($"Liquidity at {bestBid}: {liquidity} lots");
}

📦 Architecture

MT5Sugar (Extension Methods) ← You are here
    ↓ Risk-based trading, DOM, bulk operations
    ↓
MT5Service (Mid-level)
    ↓ Typed wrappers, snapshots, validation
    ↓
MT5Account (Low-level)
    ↓ Direct gRPC/Protobuf calls
    ↓
MetaTrader 5 Terminal

📝 Conventions

  • All methods are asynchronous (async Task<T>)
  • Extend MT5Service class (extension methods)
  • Parameter timeoutSec - RPC operation timeout (default 10-20 sec)
  • Parameter ct - CancellationToken for operation cancellation
  • Prices are always absolute, not relative
  • Volumes are always in lots, not currency units
  • Points - minimum price increment
  • Pips - standard unit for traders (1 pip = 10 points for 5-digit)

🎉 Ready to use!