Decrease balance

BalanceOut

Description: Subtracts a withdrawal from the user's account balance. Only negative values are accepted for the amount.

Credit is never directly withdrawable. Whether credit may support positions remaining after this balance withdrawal is controlled by the account group's credit_withdrawal_policy.

Access Control

Requires set_accounts_balance for manager/dealer sessions. The target account must also match the manager groups and brand scope loaded from the cached manager record. Token payload is used only for manager id and session type.

Request Parameters

Name	Type	Required	Description
login	int	Yes	User login ID from whose balance to withdraw
amount	double	Yes	Negative amount to withdraw (e.g., -100.0)
comment	string	No	Optional comment (default: "Finance")
order	int	No	Optional order ID for this balance operation. If set, the operation updates an existing finance transaction
open_time	int	No	Optional open timestamp
close_time	int	No	Optional close timestamp

Request Example

{
  "login": 123456,
  "amount": -250.00,
  "comment": "Manual withdrawal"
}

Withdrawal Policy

Before applying the transaction, the server calculates projected equity, free margin, Margin Call, and Stop Out state. The request is rejected when it exceeds client-owned withdrawable funds or violates withdrawal_margin_reserve.

For a direct BalanceOut command, this validation happens before an order is reserved. A rejected request therefore does not create a declined zero-effect finance transaction.

See Credit and Withdrawal Policy for policy values and formulas.

Response Parameters

Successful finance commands return the same accepted-command structure as trade commands. In the raw TCP response envelope, the fields below are returned inside data.

Name	Type	Description
accepted	bool	true when the command was accepted for processing
order	int	Server-assigned finance transaction order ID
state	int	Finance request state. New transactions return TS_FINANCE_OPEN_REQUEST (10); updates return TS_FINANCE_UPDATE_REQUEST (11)
login	int	Account login
cmd	int	Finance command type
amount	double	Operation amount

Response Example

{
  "accepted": true,
  "order": 1242280,
  "state": 10,
  "login": 123456,
  "cmd": 8,
  "amount": -250.0
}

⚠️ If a positive amount is passed, the request will be rejected due to validation rules:

{
  "error": "INVALID_DATA",
  "message": "Amount must be less than to 0"
}