Bonus transactions

Bonus is broker-provided funds stored separately from client balance and credit. Its trading behavior is controlled by the account group's bonus_usage_policy. It is never directly withdrawable.

Group bonus policy

bonus_usage_policy is a bitmask from 0 to 7:

Flag	Value	Behavior when enabled
BONUS_USAGE_AS_TRADING_EQUITY	1	Bonus participates in equity, free margin, Margin Call, and Stop Out
BONUS_USAGE_ALLOW_CONVERSION	2	ConvertBonusToBalance is allowed
BONUS_USAGE_ALLOW_REVOKE_WITH_OPEN_POSITIONS	4	A policy-safe BonusOut is allowed while positions are open

The default value is 7, preserving all currently implemented bonus behavior. With flag 1 disabled, bonus remains visible in the separate bonus bucket but does not support trading. With flag 4 enabled, revocation still has to pass projected equity and margin checks.

Command	Value	Meaning	Signed amount
OP_BONUS_IN	14	Grant bonus	positive
OP_BONUS_OUT	15	Revoke bonus	negative

Executed bonus transactions keep the signed amount in the trade profit field. BalanceFix reconstructs the bonus bucket from completed bonus transactions.

BonusIn

Requires manager permission set_bonuses.

{
  "command": "BonusIn",
  "login": 2000066,
  "amount": 500.0,
  "comment": "Welcome bonus",
  "gw_uuid": "bonus-grant-2000066-1"
}

amount must be greater than zero. gw_uuid is optional for an ordinary grant.

BonusOut

Requires manager permission set_bonuses.

{
  "command": "BonusOut",
  "login": 2000066,
  "amount": -100.0,
  "comment": "Bonus correction",
  "gw_uuid": "bonus-revoke-2000066-1"
}

amount must be less than zero. The server rejects an operation that would make bonus negative or leave an account with open exposure outside the permitted equity and margin state. When group flag 4 is disabled, revocation with open positions is rejected outright.

ConvertBonusToBalance

Conversion is an explicit domain operation, not an in-place bucket edit. The server creates two finance trades:

1. OP_BONUS_OUT for the negative conversion amount.
2. OP_BALANCE_IN for the same positive amount.

Both trades have TR_REASON_BONUS_CONVERSION, use the same required gw_uuid, and are persisted together. The balance leg references the bonus leg through parent_order. The pair is immutable through the ordinary single-trade update/delete commands.

{
  "command": "ConvertBonusToBalance",
  "login": 2000066,
  "amount": 250.0,
  "comment": "Turnover condition met",
  "gw_uuid": "bonus-conversion-2000066-1"
}

Accepted response:

{
  "accepted": true,
  "login": 2000066,
  "amount": 250.0,
  "bonus_order": 1246800,
  "balance_order": 1246801,
  "gw_uuid": "bonus-conversion-2000066-1"
}

gw_uuid is the idempotency and correlation key. Reusing it for the same account is rejected. Conversion requires group flag 2 and is rejected if the requested amount exceeds the current bonus. When bonus is trading equity, conversion changes only the composition of funds. When flag 1 is disabled, conversion moves dormant bonus into withdrawable balance and therefore increases trading equity.

DeleteBonus

{
  "command": "DeleteBonus",
  "order": 1246799
}

The command deletes an ordinary bonus grant or revocation subject to the same projected equity and margin invariants. A conversion leg cannot be deleted independently.