Add group

AddGroup

Description: Creates a new trading group with common settings, security-group overrides, and symbol-level margin overrides.

Requires set_accounts. The target group name and brand must match the manager scope loaded from the cached staff manager record.

Request Parameters

Name	Type	Required	Description
group	string	Yes	Unique group name
brand	string	No	Brand namespace for accounts in this trading group
account_mode	int	No	Account mode for self-service opening: 0 = DEMO, 1 = REAL
public_opening	int	No	Allows customer self-service opening for this group when set to 1
currency	string	Yes	Group base currency
enable	int	Yes	Enable flag
margin_call	int	Yes	Margin call level
margin_mode	int	Yes	Margin mode
margin_type	int	Yes	Margin type
margin_stopout	int	Yes	Margin stop-out level
margin_call_recovery_buffer	double	No	Buffer above margin_call required to leave Margin Call. Percentage points for percent margin, account currency for currency margin. Default: 5.0
margin_stopout_recovery_buffer	double	No	Buffer above margin_stopout required to leave Stop Out. Percentage points for percent margin, account currency for currency margin. Default: 5.0
margin_recovery_hold_ms	int	No	Continuous time the recovery threshold must remain satisfied before lowering margin-state severity. Range: 0–600000; default: 3000 ms
default_leverage	int	Yes	Default leverage
default_deposit	double	Yes	Default deposit
secgroups	array	Yes	Security-group overrides
secmargins	array	Yes	Symbol margin overrides
credit	double	No	Credit value
bonus_usage_policy	int	No	Bonus policy bitmask 0–7. Default 7: trading equity (1), conversion (2), revoke with open positions (4)
use_swap	int	No	Swap enabled flag
hedge_prohibited	int	No	Hedge prohibited flag
allow_negative_margin_hedge	int	No	Controls opening when current free margin is negative: 1 allows a trade only when projected free margin does not worsen; 0 rejects the trade. Allowed values: 0 or 1; default: 1
allow_sl_tp_slippage	int	No	Allows market-price slippage when SL/TP triggers: 1 = enabled, 0 = close exactly at SL/TP level
stopout_skip_hedged	int	No	Skip stop-out for hedged positions
close_reopen	int	No	Close/reopen flag
interestrate	int	No	Interest rate
hedge_largeleg	int	No	Hedge large leg mode
archive_pending_period	int	No	Archive period for pending orders
maxpositions	int	No	Max positions

secgroups Items

secgroups must be an array of objects. Each item must contain:

Field	Type	Required
sec_index	int	Yes

Supported optional fields: - show - trade - execution - comm_base - comm_agent - comm_type - comm_lots - comm_agent_type - comm_tax - lot_min - lot_max - lot_step - spread_diff - confirmation - ie_deviation - ie_quick_mode - trade_rights - autocloseout_mode - freemargin_mode

secmargins Items

secmargins must be an array of objects. Each item must contain:

Field	Type	Required
symbol	string	Yes

Supported optional fields: - swap_long - swap_short - margin_divider - spread_enable - spread - spread_balance

Request Example

{
  "group": "standard",
  "brand": "ion4",
  "account_mode": 1,
  "public_opening": 0,
  "currency": "USD",
  "enable": 1,
  "margin_call": 50,
  "margin_mode": 0,
  "margin_type": 0,
  "margin_stopout": 30,
  "margin_call_recovery_buffer": 5.0,
  "margin_stopout_recovery_buffer": 5.0,
  "margin_recovery_hold_ms": 3000,
  "default_leverage": 100,
  "default_deposit": 500.0,
  "bonus_usage_policy": 7,
  "allow_negative_margin_hedge": 1,
  "allow_sl_tp_slippage": 1,
  "secgroups": [
    {
      "sec_index": 1,
      "show": 1,
      "trade": 1,
      "execution": 0,
      "lot_min": 100,
      "lot_max": 100000,
      "lot_step": 100
    }
  ],
  "secmargins": [
    {
      "symbol": "EURUSD",
      "swap_long": -3.5,
      "swap_short": 2.1,
      "margin_divider": 1.0
    }
  ]
}

Margin-state recovery hysteresis

Transitions to a more severe state (OK → MC, MC → SO) are applied immediately. Recovery requires the calculated value to remain strictly above the corresponding level plus its recovery buffer for margin_recovery_hold_ms continuously.

For margin_type = 0 (percent), the calculated value is margin_level and buffers are percentage points. For margin_type = 1 (currency), the calculated value is margin_free and buffers use the account currency.

The hold period is evaluated during full account margin recalculations. If no new quote or other recalculation trigger arrives, recovery is committed on the first subsequent recalculation after the hold period. Closing all open exposure returns the account to OK immediately.

Negative free-margin hedge policy

allow_negative_margin_hedge is evaluated when a market trade is opened or a pending order is activated. It has no effect while current free margin is non-negative: the projected free margin must still remain non-negative.

When current free margin is already negative, 1 preserves the recovery-oriented behavior and allows the operation only if projected free margin is not lower than its current value, with the server money tolerance applied. 0 rejects the operation with RET_TRADE_NO_MONEY. A pending order rejected for insufficient money remains pending and can be retried on a later activation attempt.

Response Parameters

Name	Type	Description
data	string	Returns "OK" on success

Response Example

{
  "data": "OK"
}

Validation Errors

If validation fails, the method returns HTTP 400-style error payload:

{
  "error": "INVALID_DATA",
  "message": "secgroups must be an array"
}

If business validation fails in the backend, the method returns FormatErrorCode(ret) and FormatError(ret) from Core::AddGroup(...).