Client Messages spec

🇬🇧 English

This section describes all message types that a client can send to the server over the TCP socket. All client messages are encapsulated inside the message_type.client_message field in the YftManagerApiMessage structure.

YftManager API Client Messages

The YftManagerApiClientMessage enum defines the possible messages that can be sent to the YftManager API client. Below is a list of the available message types:

• AuthRequest: Initiates an authentication request.

• GetServerTime: Retrieves the current server time.

• GetAccounts: Requests account information.

• GetPositions: Fetches current positions.

• GetLastPrices: Obtains the latest prices.

• UpdateBalance: Updates the account balance.

• GetHistoryPositions: Retrieves historical positions.

• GetOrders: Requests order details.

• GetTrades: Retrieves trade information.

• Subscribe: Subscribes to specified updates.

AuthRequest

This message is used to authenticate the client. It must be sent as the first message after establishing a TCP connection.

JSON Structure

Input Example:

{
  "message_id": "string",
  "message_response_id": null,
  "message_type": {
    "client_message": {
      "auth_request": {
        "secret_key": "string"
      }
    }
  }
}

Field	Type	Description (EN)
secret_key	string	Secret key for authenticating client

This structure is used for client authentication requests by providing a secret key. Ensure that message_id and secret_key are filled with the appropriate values.

GetServerTime

This message is used by the client to request the current server time.

JSON Structure

{
  "message_id": "string",
  "message_type": {
    "client_message": {
      "get_server_time": {}
    }
  }
}

Parameters

Field	Type	Description
get_server_time	object	Empty object indicating the request.

GetAccounts

This message is used to request a list of trading accounts. The client may optionally filter by trader_id or a specific account_id.

JSON Structure

{
  "message_id": "string",
  "message_type": {
    "client_message": {
      "get_accounts": {
        "trader_id": "string | null",
        "account_id": "string | null"
      }
    }
  }
}

Field Explanation

Field	Type	Description
trader_id	string (opt)	If provided, only accounts belonging to this trader will be returned.
account_id	string (opt)	If provided, only the specific account will be returned.

GetPositions

This message is used to request a list of currently open trading positions. The client can filter results by trader_id, account_id, or asset_pair.

JSON Structure

{
  "message_id": "string",
  "message_type": {
    "client_message": {
      "get_positions": {
        "trader_id": "string | null",
        "account_id": "string | null",
        "asset_pair": "string | null"
      }
    }
  }
}

Field Explanation

Field	Type	Description
trader_id	string (opt)	Filter positions by trader ID.
account_id	string (opt)	Filter positions by account ID.
asset_pair	string (opt)	Filter positions by the symbol of the asset pair (e.g., "eurusd").

GetLastPrices

This message is used to request the latest bid/ask prices for asset pairs. The client may specify a particular asset_pair or leave it empty to retrieve all available prices.

JSON Structure

{
  "message_id": "string",
  "message_type": {
    "client_message": {
      "get_last_prices": {
        "asset_pair": "string | null"
      }
    }
  }
}

Field Explanation

Field	Type	Description
asset_pair	string (opt)	Symbol of the asset pair to filter (e.g., "eurusd"). If omitted, all prices will be returned.

UpdateBalance

This request is used to change a trader’s account balance manually. It may represent a deposit, withdrawal, balance correction, or similar adjustment. The request requires authorization and a valid reason.

JSON Structure

{
  "message_id": "string",
  "message_type": {
    "client_message": {
      "update_balance": {
        "trader_id": "string",
        "account_id": "string",
        "delta": "number",
        "comment": "string | null",
        "process_id": "string",
        "allow_negative_balance": "boolean",
        "reason": "enum",
        "reference_transaction_id": "string | null",
        "same_response_process_id": "boolean"
      }
    }
  }
}

Field Explanation

Field	Type	Description
trader_id	string	ID of the trader.
account_id	string	ID of the account to update.
delta	number	The balance change amount. Positive for credit, negative for debit.
comment	string (opt)	Optional comment explaining the adjustment.
process_id	string	Unique identifier for this process/request.
allow_negative_balance	boolean	Whether the update is allowed to cause a negative balance.
reason	string (enum)	Reason for the balance update (e.g., deposit, withdrawal, trading).
reference_transaction_id	string (opt)	Optional reference to another related transaction.
same_response_process_id	boolean	If true, the response will echo the same process_id.

reason enum

Variant	Description
trading	Adjustments due to trading operations.
deposit	Manual or external deposit.
withdrawal	Manual or external withdrawal.
transfer	Funds moved between accounts.
balance_correction	Correction of balance due to error or administrative action.

GetHistoryPosition

This request retrieves a list of previously closed (historical) positions. It allows filtering by trader ID, account ID, and asset pair. This request is often used for reporting, audit, or analytics purposes.

JSON Structure

{
  "message_id": "string",
  "message_type": {
    "client_message": {
      "get_history_positions": {
        "trader_id": "string | null",
        "account_id": "string | null",
        "asset_pair": "string | null"
      }
    }
  }
}

Field Explanation

Field	Type	Description
trader_id	string (opt)	Filter by trader ID.
account_id	string (opt)	Filter by specific account ID.
asset_pair	string (opt)	Filter by asset pair (e.g. eurusd).

GetOrders

This request retrieves a list of active orders. It can be filtered by trader ID, account ID, asset pair, or a specific position. This allows the client to get pending or currently open orders on the account.

JSON Structure

{
 "message_id": "string",
  "message_type": {
    "client_message": {
      "get_orders": {
        "trader_id": "string | null",
        "account_id": "string | null",
        "asset_pair": "string | null",
        "position_id": "string | null"
      }
    }
  }
}

Field Description

Field	Type	Description
trader_id	string (opt)	Filter by trader ID
account_id	string (opt)	Filter by account ID
asset_pair	string (opt)	Filter by asset pair (e.g., "eurusd")
position_id	string (opt)	Return orders associated with a specific position ID

GetTrades

This request retrieves a list of executed trades. You can filter them by trader ID, account ID, asset pair, position ID, or order ID. It allows clients to access the trade history related to specific entities.

JSON Structure

{
  "message_id": "string",
  "message_type": {
    "client_message": {
      "get_trades": {
        "trader_id": "string (opt)",
        "account_id": "string (opt)",
        "asset_pair": "string (opt)",
        "position_id": "string (opt)",
        "order_id": "string (opt)"
      }
    }
  }
}

Field Description

Field	Type	Description
trader_id	string (opt)	Filter by trader ID
account_id	string (opt)	Filter by account ID
asset_pair	string (opt)	Filter by trading pair (e.g., "btcusd")
position_id	string (opt)	Filter trades related to a specific position
order_id	string (opt)	Filter trades related to a specific order

Subscribe

This message is used by an authorized client to subscribe to real-time data streams (e.g., prices). Once subscribed, the client will receive updates automatically when the corresponding data changes.

JSON Structure

{
  "message_id": "string",
  "message_response_id": null,
  "message_type": {
    "client_message": {
      "subscribe": {
        "topic": "prices"
      }
    }
  }
}

Fields

Field	Type	Description
topic	string	One of predefined subscription topics. Currently supports only "prices"

Enum: SubscriptionTopic

enum SubscriptionTopic {
    Prices,
}

• JSON string values must match snake_case enum names.

• Deserialization is strict — invalid topics will result in error before request processing.