Server message spec

Basic server message structure

Description

Server messages are used to deliver results of client requests, real-time updates, or system errors. They are always wrapped in the server_message envelope inside the message_type field. The server may respond with either a success payload or an error type, depending on the operation outcome.

JSON Structure (Success)

{
  "message_id": "string",
  "message_response_id": "string | null",
  "message_type": {
    "server_message": {
      "success": {
        "accounts": {
          "snapshot": {
            "data": [ /* list of accounts */ ]
          }
        }
      }
    }
  }
}

---

JSON Structure (Error)

{
  "message_id": "string",
  "message_response_id": null,
  "message_type": {
    "server_message": {
      "error": "unauthorized"
    }
  }
}

Server Message Envelope Fields

Field	Type	Description
message_id	string	Unique UUID of the outgoing server message
message_response_id	string (opt)	UUID of the original client message (for responses)
message_type	object	Server message wrapper, with either success or error keys

---

UpdateBalanceErrorCode

This enum defines possible error reasons that can occur when updating an account balance through the update_balance request.

Enum Variants

Value	Description
account_not_found	The specified account does not exist.
receiver_account_not_found	The target (receiver) account in a transfer was not found.
trading_settings_not_found	Trading configuration (e.g. profile) is missing or invalid.
not_enough_balance	The account does not have sufficient funds to complete the operation.
invalid_balance_transfer_amount	The provided amount is negative, zero, or otherwise invalid.
invalid_collateral	The collateral currency does not match the account or is unsupported.
account_duplicate	A duplicate account record was detected during processing.
sender_account_disabled	The sending account is disabled and cannot initiate a transfer.
reciever_account_disabled	The receiving account is disabled and cannot accept a transfer.
undefinded	An unknown or unspecified error occurred.

Enum: YftManagerApiServerMessageType

Variant	Description (EN)
success	Contains a successful response or snapshot/update message
error	Contains an error code if the server fails to process request

YftServerMessageType

Description

YftServerMessageType<T> is a generic envelope that defines the semantic context of a server message payload.

It can represent:

• a full snapshot of current state (e.g. initial list of positions),

• an event update (e.g. an order was created, canceled, updated),

• a response to a direct client request.

This design allows clients to understand:

• whether data is intended to replace the full state,

• append to or modify it,

• or simply acknowledge a request.

JSON Structure

Snapshot

{
  "message_id": "string",
  "message_response_id": null,
  "message_type": {
    "server_message": {
      "success": {
        "positions": {
          "snapshot": {
            "data": [
              { /* ManagerApiPosition */ },
              { /* ManagerApiPosition */ }
            ]
          }
        }
      }
    }
  }
}

Response to a request

{
  "message_id": "generated-response-id",
  "message_response_id": "original-request-id",
  "message_type": {
    "server_message": {
      "success": {
        "orders": {
          "response": {
            "data": [
              { /* ManagerApiOrder */ }
            ]
          }
        }
      }
    }
  }
}

General Event JSON Example

{
  "message_id": "string",
  "message_response_id": null,
  "message_type": {
    "server_message": {
      "success": {
        "<payload_type>": {
          "<event_type>": {
            "data": [
              { /* domain object */ }
            ]
          }
        }
      }
    }
  }
}

Example placeholders:

• <payload_type>: orders, positions, accounts, last_prices, trades, etc.

• <event_type>: snapshot, created, updated, response, etc.

---

Supported Event Types in YftServerMessageType<T>

Event Type	Description	Typical Use Case
snapshot	Represents the full current state of a resource	Initial list of positions or accounts
response	Direct reply to a specific client request (linked via message_response_id)	Get orders / balances by request
created	A new entity has been created	New order, position placed. Account added.
updated	An existing entity has been modified	Order or position updated
canceled	An entity has been canceled	Order canceled by user or system
closed	A process has completed and the entity was closed	Position closed
executed	The entity has been executed	Order fully or partially executed
failed	The operation related to the entity failed	Order failed due to rejection

---

Struct: YftServerMessage<T>

Field	Type	Description
data	Vec<T>	List of data items returned

AuthResult

The response to a successful authentication request. It confirms whether a session has been established and may include a session ID used for tracking or authorization purposes.

JSON Structure

{
  "message_id": "string",
  "message_type": "server_message",
  "message_response_id": "string",
  "server_message": {
    "success": {
      "auth_result": {
        "session_id": "string" // optional
      }
    }
  }
}

Field Reference

Field	Type	Description
message_id	string	Unique identifier of the message from the server.
message_type	string	Type of message, always "server_message" in server responses.
message_response_id	string	ID of the original client request this message responds to.
session_id	string (optional)	The session ID issued upon successful authentication. May be null if not used.

ServerTime

Returns the current server time. Used by clients to synchronize clocks, validate latency, or test connectivity.

JSON Structure

{
  "message_id": "string",
  "message_type": "server_message",
  "message_response_id": "string",
  "server_message": {
    "success": {
      "server_time": {
        "server_time": "string (RFC3339 format)"
      }
    }
  }
}

Field Reference

Field	Type	Description
message_id	string	Unique identifier of this server message.
message_type	string	Always "server_message" for server responses.
message_response_id	string	Corresponds to the original client message this is replying to.
server_time	string	Server time in ISO 8601 / RFC 3339 format, e.g. "2025-06-05T19:38:17.000+03:00".

UpdateBalance

Used to confirm the result of a balance update operation (e.g., deposit, withdrawal, correction). This response either returns the updated account or an error code explaining why the update failed.

JSON Structure

{
  "message_id": "string",
  "message_type": "server_message",
  "message_response_id": "string",
  "server_message": {
    "success": {
      "update_balance": {
        "ok": {
          "id": "string",
          "trader_id": "string",
          "currency": "string",
          "balance": "number",
          "equity": "number",
          "margin": "number",
          "free_margin": "number",
          "margin_level": "number",
          "leverage": "number",
          "trading_group": "string",
          "last_update_date": "string (RFC3339)",
          "metadata": {
            "key": "value"
          },
          "status": "enum",
          "hedge_mode": "enum"
        }
        // OR
        "err": "string (UpdateBalanceErrorCode)"
      }
    }
  }
}

Field Reference

Field	Type	Description
ok	ManagerApiAccount	Present if the update was successful. Returns the full updated account.
err	UpdateBalanceErrorCode	Present if the update failed.
UpdateBalanceErrorCode	enum	Possible values: account_not_found, invalid_balance_transfer_amount, not_enough_balance, etc.

📌 See the ManagerApiAccount model for details on the account structure. 📌 See the UpdateBalanceErrorCode enum for all possible failure reasons.

Accounts

Returns a list of trading accounts associated with the authenticated trader. Each account contains full margin, balance, leverage, and configuration details.

---

JSON Response Structure

{
  "message_id": "string",
  "message_type": "server_message",
  "message_response_id": "string (opt)",
  "server_message": {
    "success": {
      "accounts": {
        "response": {
          "data": [
            {
              "id": "string",
              "trader_id": "string",
              "currency": "string",
              "balance": 0.0,
              "equity": 0.0,
              "margin": 0.0,
              "free_margin": 0.0,
              "margin_level": 0.0,
              "leverage": 0.0,
              "trading_group": "string",
              "last_update_date": "UTC timestamp",
              "metadata": {
                "string": "string"
              },
              "status": 0,
              "hedge_mode": 0
            }
          ]
        }
      }
    }
  }
}

---

Field Reference

📌 See the ManagerApiAccount model for details on the account structure.

AccountBalabceOperation

The account_balance_operation server message type communicates a change in a trader’s account balance. It may include both the updated account snapshot and the specific operation that caused the balance change, such as a trade, deposit, or commission.

This message is used for real-time event delivery and wraps data in one of the YftServerMessageType variants such as created, updated, or response.

JSON Structure

{
  "message_id": "string",                    // UUID that uniquely identifies this message
  "message_response_id": "string | null",   // Optional: links to original request
  "message_type": {
    "server_message": {
      "success": {
        "account_balance_operation": {
          "<event_type>": {
            "data": [
              {
                "account": {
                  "id": "string",
                  "trader_id": "string",
                  "currency": "USD",
                  "balance": 1000.0,
                  "equity": 950.0,
                  "margin": 50.0,
                  "free_margin": 900.0,
                  "margin_level": 1900.0,
                  "leverage": 100.0,
                  "trading_group": "group-1",
                  "last_update_date": 1717685000000,
                  "metadata": {},
                  "status": "active",
                  "hedge_mode": "netting"
                },
                "operation": {
                  "id": "string",
                  "trader_id": "string",
                  "account_id": "string",
                  "reason": "trading | deposit | withdrawal | transfer | balance_correction | commission",
                  "process_id": "string | null",
                  "delta": "float",
                  "date": "int (timestamp in ms)",
                  "comment": "string | null",
                  "reference_operation_id": "string | null"
                }
              }
            ]
          }
        }
      }
    }
  }
}

Field Explanation

Field	Type	Description
account	ManagerApiAccount	The updated account state after applying the balance operation.
operation	ManagerApiAccountBalanceUpdateOperation | null	The balance-changing operation. Can be omitted in some cases.

See ManagerApiAccount Contains full details of the trading account structure, including margin, leverage, and metadata.

See ManagerApiAccountBalanceUpdateOperation Describes the type, amount, and context of the balance update that affected the account.

Positions

Returns a list of active trading positions for a trader or account. These records are used to display open positions in the trading interface and to calculate margin, profit, and risk in real time.

---

JSON Response Structure

{
  "message_id": "string",                  // UUID of the request
  "message_type": "server_message",       
  "message_response_id": "string (optional)", 
  "server_message": {
    "success": {
      "positions": {
        "response": {
          "data": [
            {
              "id": "string",
              "trader_id": "string",
              "account_id": "string",
              "asset_pair": "string",
              "collateral": "string",
              "lots_amount": 0.0,
              "is_buy": true,
              "sl_price": 0.0,
              "tp_price": 0.0,
              "metadata": {
                "key": "value"
              },
              "order_id": "string",
              "margin_bidask": {
                "id": "string",
                "bid": 0.0,
                "ask": 0.0
              },
              "open_bidask": {
                "id": "string",
                "bid": 0.0,
                "ask": 0.0
              },
              "profit_bidask": {
                "id": "string",
                "bid": 0.0,
                "ask": 0.0
              },
              "open_price": 0.0,
              "open_time": 0,
              "swap": 0.0,
              "net_pl": 0.0,
              "gross_pl": 0.0,
              "leverage": 0.0,
              "is_abook": true
            }
          ]
        }
      }
    }
  }
}

---

See the ManagerApiPosition model for details on the account structure.

HistoryPositions

Returns a list of closed (historical) trading positions for a trader or account. These records are used for reporting, historical performance analysis, and audit trails.

---

JSON Response Structure

{
  "message_id": "string",                  // UUID of the request
  "message_type": "server_message",
  "message_response_id": "string (optional)",
  "server_message": {
    "success": {
      "closed_position": {
        "response": {
          "data": [
            {
              "id": "string",
              "trader_id": "string",
              "account_id": "string",
              "asset_pair": "string",
              "collateral": "string",
              "lots_amount": 0.0,
              "is_buy": true,
              "sl_price": 0.0,
              "tp_price": 0.0,
              "metadata": {
                "key": "value"
              },
              "order_id": "string",
              "margin_bidask": {
                "id": "string",
                "bid": 0.0,
                "ask": 0.0
              },
              "open_bidask": {
                "id": "string",
                "bid": 0.0,
                "ask": 0.0
              },
              "profit_bidask": {
                "id": "string",
                "bid": 0.0,
                "ask": 0.0
              },
              "close_bidask": {
                "id": "string",
                "bid": 0.0,
                "ask": 0.0
              },
              "open_price": 0.0,
              "close_price": 0.0,
              "open_time": 0,
              "close_time": 0,
              "swap": 0.0,
              "net_pl": 0.0,
              "gross_pl": 0.0,
              "leverage": 0.0,
              "is_abook": true,
              "close_reason": "string"
            }
          ]
        }
      }
    }
  }
}

---

See the ManagerApiPosition model for details on the position structure.

LastPrices

Returns the most recent bid/ask prices for a list of trading instruments. This data is used to display real-time market quotes and to calculate floating profit and margin requirements for open positions.

---

JSON Response Structure

{
  "message_id": "string",                  // UUID of the request
  "message_type": "server_message",
  "message_response_id": "string (optional)",
  "server_message": {
    "success": {
      "last_prices": {
        "response": {
          "data": [
            {
              "id": "string",             // Instrument identifier
              "bid": 0.0,                 // Latest bid price
              "ask": 0.0                  // Latest ask price
            }
          ]
        }
      }
    }
  }
}

---

See the ManagerBidAsk model for details on the price structure.

Orders

Returns a list of active (pending) orders for a trader or account. This data is used to display open orders in the trading interface and to manage order execution, cancellation, or modification.

---

JSON Response Structure

{
  "message_id": "string",                  // UUID of the request
  "message_type": "server_message",
  "message_response_id": "string (optional)",
  "server_message": {
    "success": {
      "orders": {
        "response": {
          "data": [
            {
              "id": "string",
              "trader_id": "string",
              "account_id": "string",
              "asset_pair": "string",
              "collateral": "string",
              "lots_amount": 0.0,
              "is_buy": true,
              "price": 0.0,
              "created": 0,               // Unix timestamp
              "order_type": "string",     // e.g. "market", "limit", "stop"
              "metadata": {
                "key": "value"
              },
              "status": "string",         // e.g. "active", "executed", "canceled"
              "is_abook": true
            }
          ]
        }
      }
    }
  }
}

---

See the ManagerApiOrder model for details on the order structure.

Trades

Returns a list of executed trades for a trader or account. Trades represent matched executions from submitted orders and are used for reporting, profit calculations, and auditing.

---

JSON Response Structure

{
  "message_id": "string",                  // UUID of the request
  "message_type": "server_message",
  "message_response_id": "string (optional)",
  "server_message": {
    "success": {
      "trades": {
        "response": {
          "data": [
            {
              "id": "string",
              "order_id": "string",
              "position_id": "string",
              "trader_id": "string",
              "account_id": "string",
              "asset_pair": "string",
              "collateral": "string",
              "lots": 0.0,
              "price": 0.0,
              "is_buy": true,
              "is_abook": true,
              "execution_date": "ISO 8601 timestamp"
            }
          ]
        }
      }
    }
  }
}

---

See the ManagerApiTrade model for details on the trade structure.

TradingGroups

Returns a list of available trading groups configured in the system. Trading groups define common parameters (e.g. leverage, margin requirements) and are typically assigned to accounts to control trading behavior and risk.

---

JSON Response Structure

{
  "message_id": "string",                  // UUID of the request
  "message_type": "server_message",
  "message_response_id": "string (optional)",
  "server_message": {
    "success": {
      "trading_groups": {
        "response": {
          "data": [
            {
              "id": "string",
              "name": "string",
              "description": "string"
            }
          ]
        }
      }
    }
  }
}

---

See the ManagerApiTradingGroup model for details on the trading group structure.

TradingInstruments

Returns a list of trading instruments available in the system. Each instrument represents a tradable asset pair with specific settings used for pricing, trading limits, and UI rendering.

---

JSON Response Structure

{
  "message_id": "string",
  "message_type": "server_message",
  "message_response_id": "string (optional)",
  "server_message": {
    "success": {
      "trading_instruments": {
        "response": {
          "data": [
            {
              "id": "string",
              "name": "string",
              "digits": 0,
              "base": "string",
              "quote": "string",
              "tick_size": 0.0,
              "swap_schedule_id": "string (optional)",
              "group_id": "string",
              "weight": 0,
              "day_timeout": 0,
              "night_timeout": 0,
              "trading_disabled": false,
              "lot_size": 0,
              "day_off_profiles_id": ["string"]
            }
          ]
        }
      }
    }
  }
}

---

See the ManagerApiTradingInstrument model for details on the instrument structure.

TradingProfiles

Returns a list of trading profiles available in the system. A trading profile defines instrument-specific trading settings for a given trading group, including leverage, margin requirements, and commission rates.

---

JSON Response Structure

{
  "message_id": "string",
  "message_type": "server_message",
  "message_response_id": "string (optional)",
  "server_message": {
    "success": {
      "trading_profiles": {
        "response": {
          "data": [
            {
              "id": "string",
              "trading_group_id": "string",
              "instrument_id": "string",
              "leverage": 0.0,
              "initial_margin": 0.0,
              "maintenance_margin": 0.0,
              "commission_per_lot": 0.0,
              "min_lot": 0.0,
              "max_lot": 0.0,
              "lot_step": 0.0
            }
          ]
        }
      }
    }
  }
}

---

See the ManagerApiTradingProfile model for details on the profile structure.

TradingMarkups

Returns a list of trading markup profiles used to adjust bid/ask prices for specific instruments and trading groups. Markups are typically applied to reflect spreads, fees, or risk management policies.

---

JSON Response Structure

{
  "message_id": "string",
  "message_type": "server_message",
  "message_response_id": "string (optional)",
  "server_message": {
    "success": {
      "trading_markups": {
        "response": {
          "data": [
            {
              "id": "string",
              "trading_group_id": "string",
              "instrument_id": "string",
              "markup_bid": 0.0,
              "markup_ask": 0.0,
              "use_spread_only": false
            }
          ]
        }
      }
    }
  }
}

---

See the ManagerApiMarkupProfile model for details on the markup structure.

DayOffProfiles

Returns a list of day-off profiles that define time-based trading restrictions. Each profile includes one or more time windows during which trading is disabled for specific instruments (e.g. weekends, holidays, maintenance periods).

---

JSON Response Structure

{
  "message_id": "string",
  "message_response_id": "string (optional)",
  "message_type": {
    "server_message": {
      "success": {
        "day_off_profiles": {
          "response": {
            "data": [
              {
                "id": "string",
                "name": "string",
                "is_disabled": false,
                "days_off": [
                  {
                    "dow_from": 0,
                    "time_from": "string",
                    "dow_to": 0,
                    "time_to": "string"
                  }
                ]
              }
            ]
          }
        }
      }
    }
  }
}

---

See the ManagerApiDayOffProfile model for details on the profile structure.

SubscribeConfirmed

Sent by the server to confirm a successful subscription to one or more data streams. This message indicates that the client is now registered to receive real-time updates.

---

JSON Response Structure

{
  "message_id": "string",
  "message_type": "server_message",
  "message_response_id": "string (optional)",
  "server_message": {
    "success": {
      "subscribe_confirmed": {}
    }
  }
}