BalanceIn

Description: Adds a deposit entry to a user account. Only positive values are accepted for the amount.

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 to which the balance operation applies
amount	double	Yes	Positive amount to deposit
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": 1000.00,
  "comment": "Initial deposit"
}

Response Parameters

Updating metadata without changing the amount

For an existing transaction, send its order and its unchanged amount to edit comment or other supported metadata. This does not add the amount again and does not change balance, credit or bonus. The accepted response still has state 11; completion is delivered as a TCP trade:event with type EV_RECORD_UPDATE and data state 3 (TS_CLOSED_NORMAL). Correlate completion using data.order and data.login. The same zero-delta completion rule applies to existing BalanceOut, CreditIn and CreditOut transactions. New zero-amount operations remain invalid. Do not retry an accepted operation merely because observation timed out.

Example accepted TCP response for a comment-only update:

{
  "extID": "BalanceIn_comment_edit_1",
  "status": 200,
  "data": {
    "accepted": true,
    "order": 1242279,
    "state": 11,
    "login": 123456,
    "cmd": 6,
    "amount": 1000.0
  }
}

Accepted response fields

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": 1242279,
  "state": 10,
  "login": 123456,
  "cmd": 6,
  "amount": 1000.0
}

⚠️ If the operation fails, an error response is returned:

{
  "error": "ADD_BALANCE_ERROR",
  "message": "Invalid login or insufficient permissions"
}