Add balance sync

BalanceInSync

Description: Adds a deposit entry and keeps the TCP request open until the matching trade:event is broadcast by the trading runtime.

BalanceInSync is a manager TCP API method for integrations that need the final finance trade payload in the command response instead of accepting an order and waiting for a separate event subscription.

SEO

BalanceInSync is the synchronous TCP deposit method for ScaleTrade manager API integrations. Use this endpoint when a CRM, payment gateway, or backoffice connector must create a balance-in operation and receive the resulting trade transaction payload by order.

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	Account login ID
amount	double	Yes	Positive deposit amount
comment	string	No	Optional comment. Default: "Finance"
order	int	No	Existing finance transaction order to update. If omitted or not found, the server creates a new finance transaction
open_time	int	No	Optional open timestamp
close_time	int	No	Optional close timestamp

Request Example

{
  "command": "BalanceInSync",
  "extID": "deposit-req-1001",
  "data": {
    "login": 1001,
    "amount": 250.0,
    "comment": "Payment gateway deposit"
  }
}

Runtime Flow

1. Handler validates request data.
2. Handler calls the same backend path as BalanceIn.
3. Backend reserves or reuses the finance order.
4. TCP server stores a pending sync waiter by order, extID, event type and active session.
5. mainLoop processes the finance trade and emits trade:event.
6. TCP server matches trade:event.data.order and sends the matched event data to the original TCP session.

The handler returns the usual successful internal status and adds a service __deferred object into response data. TCP transport intercepts this key, registers a pending response and does not send the intermediate handler response to the client.

Success Response

On success the response contains only the data object from the matching trade:event; it does not wrap the full event envelope.

{
  "extID": "deposit-req-1001",
  "status": 200,
  "data": {
    "order": 1242279,
    "login": 1001,
    "cmd": 6,
    "state": 3,
    "profit": 250.0,
    "comment": "Payment gateway deposit"
  }
}

Event Matching

For a new finance transaction, TCP waits for trade:event with:

Field	Value
event	trade:event
type	EV_RECORD_ADD
data.order	Reserved finance order

For an existing finance transaction update, TCP waits for EV_RECORD_UPDATE with the same data.order.

Timeout

The default timeout is 5000 ms. If no matching trade event arrives before timeout, TCP returns:

{
  "extID": "deposit-req-1001",
  "status": 504,
  "data": {
    "error": "SYNC_TIMEOUT",
    "kind": "trade",
    "order": 1242279
  }
}

Error Response

Validation and immediate backend errors are returned synchronously:

{
  "extID": "deposit-req-1001",
  "status": 401,
  "data": {
    "error": "ADD_BALANCE_ERROR",
    "message": "Invalid login or insufficient permissions"
  }
}

Notes

• The method is available to SESSION_MANAGER, SESSION_ADMIN, and SESSION_DEALER.
• The regular trade:event broadcast still exists as part of the platform event stream.
• This method is the first implementation of the generic TCP deferred response flow and can be reused for future sync trading methods such as MngOpenTradeSync.