# Usage guide

## Purpose

Smart Lot Calculator calculates a suggested trading volume according to:

- account value;
- selected risk percentage or fixed monetary risk;
- entry price;
- Stop Loss price;
- operation direction;
- symbol volume rules defined by the broker.

The library does not open trades.

## Calculating by percentage

```cpp
string error = "";

double volume = CSmartLotCalculator::CalculateByRiskPercent(
   _Symbol,
   ORDER_TYPE_BUY,
   entry_price,
   stop_price,
   1.0,
   RISK_BASE_EQUITY,
   error
);
```

The example risks 1% of the account equity.

Available risk bases:

```cpp
RISK_BASE_BALANCE
RISK_BASE_EQUITY
RISK_BASE_FREE_MARGIN
```

## Calculating by fixed money

```cpp
string error = "";

double volume = CSmartLotCalculator::CalculateByMoney(
   _Symbol,
   ORDER_TYPE_BUY,
   entry_price,
   stop_price,
   100.00,
   error
);
```

The example requests a volume whose estimated Stop Loss is approximately 100 units of the account currency.

## Sell calculation

For a sell operation, the Stop Loss must be above the entry price:

```cpp
double volume = CSmartLotCalculator::CalculateByRiskPercent(
   _Symbol,
   ORDER_TYPE_SELL,
   entry_price,
   stop_price,
   1.0,
   RISK_BASE_EQUITY,
   error
);
```

## Error handling

Always check whether the returned volume is greater than zero:

```cpp
if(volume <= 0.0)
{
   Print("Calculation error: ", error);
   return;
}
```

A zero return can indicate:

- invalid prices;
- invalid risk percentage;
- unsupported order type;
- unavailable symbol information;
- calculated volume below the broker minimum;
- failure in MetaTrader's profit calculation.

## Volume normalization

The library rounds the calculated volume down according to:

- `SYMBOL_VOLUME_MIN`;
- `SYMBOL_VOLUME_MAX`;
- `SYMBOL_VOLUME_STEP`.

Rounding down is intentional so the normalized volume does not exceed the requested risk.

## Limitations

The final result depends on the symbol specifications and prices supplied by the broker.

Slippage, commission, swap, gaps and execution differences may cause the actual loss to differ from the estimate.

Always validate the result before using it in a live account.