Parameters

Plugin Parameters

Configure these parameters in MT5 Administrator under the plugin settings.

Parameter	Type	Default	Description
`API_Key`	String	(empty)	REST API key for authentication. Leave empty to disable the API.
`API_Port`	String	`8447`	HTTP port the API listens on
`Drawdown_Interval`	Integer	`5`	Seconds between drawdown protection checks
`Comment_Prefix`	String	`bm`	Comment tag on all credit operations (used for recursion prevention)

Campaign Configuration

Campaigns are created and managed via the REST API. Each campaign defines the rules for automatic bonus grants.

Core Fields

Field	Type	Default	Description
`name`	String	(required)	Campaign display name
`status`	Integer	`1`	`0` = paused, `1` = active, `2` = ended
`bonus_type`	Integer	`0`	`0` = credit (standard), `1` = convertible
`bonus_percentage`	Float	(required)	Percentage of deposit to grant as credit
`max_bonus_amount`	Float	`0`	Cap per individual bonus. `0` = no cap
`group_mask`	String	(required)	MT5 group wildcard (e.g. `real\*`)

Deposit Filters

Field	Type	Default	Description
`min_deposit`	Float	`0`	Minimum qualifying deposit amount. `0` = any
`max_deposit`	Float	`0`	Maximum qualifying deposit amount. `0` = no cap

Limits

Field	Type	Default	Description
`one_per_account`	Boolean	`false`	Prevent duplicate bonuses from the same campaign per account
`max_concurrent`	Integer	`0`	Max active bonuses per account. `0` = unlimited
`expiry_days`	Integer	`0`	Days until bonus expires after grant. `0` = never

Withdrawal & Protection

Field	Type	Default	Description
`withdrawal_mode`	Integer	`0`	`0` = remove all credit on withdrawal, `1` = proportional reduction
`drawdown_mode`	Integer	`0`	`0` = disabled, `1` = tradeable (lenient), `2` = non-tradeable (strict)

Convertible Bonus Fields

These fields apply only when bonus_type is 1 (convertible):

Field	Type	Default	Description
`lots_required`	Float	`0`	Total lots needed for full conversion
`lot_scope`	Integer	`0`	`0` = all trades, `1` = post-bonus only, `2` = symbol filtered, `3` = per-trade threshold
`symbol_filter`	String	`*`	Comma-separated symbols for `lot_scope=2`
`per_trade_min_lots`	Float	`0`	Min lots per trade for `lot_scope=3`

Campaign Examples

30% Credit Bonus for All Real Groups

{
  "name": "Standard 30%",
  "group_mask": "real\\*",
  "bonus_percentage": 30.0,
  "max_bonus_amount": 5000.0,
  "min_deposit": 100.0,
  "withdrawal_mode": 1,
  "drawdown_mode": 2,
  "one_per_account": true
}

Grants 30% credit (capped at $5,000) on deposits of $100+ across all real groups. Credit is reduced proportionally on withdrawal. Non-tradeable drawdown protection enabled.

Convertible Bonus — Trade to Unlock

{
  "name": "Trade & Earn 50%",
  "group_mask": "real\\vip\\*",
  "bonus_type": 1,
  "bonus_percentage": 50.0,
  "lots_required": 10.0,
  "lot_scope": 1,
  "expiry_days": 30,
  "max_concurrent": 1
}

Grants 50% convertible credit for VIP groups. Credit converts to real balance as the client trades 10 lots (post-bonus trades only). Expires after 30 days. One active bonus per account.

Drawdown Protection

Tradeable Mode (`drawdown_mode: 1`)

Lenient — the bonus acts as extra margin. The client can trade using the bonus as a buffer.

Trigger: Equity drops to $0
Action: Close all positions, remove all bonus credit

Non-Tradeable Mode (`drawdown_mode: 2`)

Strict — prevents clients from trading purely on bonus funds.

Trigger: Equity falls below total credit
Action: Close all positions, remove all bonus credit

💡

TipNon-tradeable mode is recommended for most brokers. It prevents clients from gambling entirely with bonus funds and protects the broker from excessive risk.

Orphaned Credit Cleanup

The plugin periodically scans for accounts where:

Account balance is near zero
MT5 credit is still positive
No active bonus records exist

Orphaned credit is automatically removed with a bm:cleanup comment tag.

Expiry

Bonuses with expiry_days > 0 are automatically checked periodically. Expired bonuses have their remaining credit removed and are marked as expired.

Next Steps

API Reference — Manage campaigns, bonuses, and stats via REST
Introduction — Back to the plugin overview