This is an old revision of the document!
T4 Protocol Message Reference
This document provides a reference for all messages in the T4 Protocol. The protocol uses Protocol Buffers (protobuf) for message serialization.
Client/Server Message Envelopes
All communication in the T4 Protocol is done via a pair of envelope messages: ClientMessage (client to server) and ServerMessage (server to client). These messages encapsulate all other message types using Protocol Buffers' oneof field.
ClientMessage
The ClientMessage is sent from the client to the server and can contain any of the following payloads:
| Field | Type | Description |
|---|---|---|
| heartbeat | Heartbeat | A simple heartbeat to maintain connection |
| login_request | LoginRequest | Authentication request |
| market_depth_subscribe | MarketDepthSubscribe | Request to subscribe to market depth data |
| market_by_order_subscribe | MarketByOrderSubscribe | Request to subscribe to market by order data |
| account_subscribe | AccountSubscribe | Request to subscribe to account data |
| order_submit | OrderSubmit | Submit a new order |
| order_revise | OrderRevise | Modify an existing order |
| order_pull | OrderPull | Cancel an existing order |
| create_uds | CreateUDS | Create a user-defined strategy |
ServerMessage
The ServerMessage is sent from the server to the client and can contain any of the following payloads:
| Field | Type | Description |
|---|---|---|
| heartbeat | Heartbeat | A simple heartbeat to maintain connection |
| login_response | LoginResponse | Authentication response |
| market_depth_subscribe_reject | MarketDepthSubscribeReject | Rejection of market depth subscription |
| market_by_order_subscribe_reject | MarketByOrderSubscribeReject | Rejection of market by order subscription |
| market_details | MarketDetails | Details about a market |
| market_depth | MarketDepth | Market depth data |
| market_depth_trade | MarketDepthTrade | Trade data for a market |
| market_high_low | MarketHighLow | High/low prices for a market |
| market_price_limits | MarketPriceLimits | Price limits for a market |
| market_settlement | MarketSettlement | Settlement data for a market |
| market_snapshot | MarketSnapshot | Complete snapshot of a market |
| market_by_order_snapshot | MarketByOrderSnapshot | Complete snapshot of order book |
| market_by_order_update | MarketByOrderUpdate | Update to the order book |
| account_subscribe_response | AccountSubscribeResponse | Response to account subscription |
| account_currency | AccountCurrency | Account currency information |
| account_position | AccountPosition | Position data for an account |
| account_update | AccountUpdate | Update to account data |
| account_details | AccountDetails | Detailed account information |
| account_snapshot | AccountSnapshot | Complete snapshot of account data |
| order_update | OrderUpdate | Update to an order |
| order_update_multi | OrderUpdateMulti | Multiple order updates |
| order_update_failed | OrderUpdateFailed | Failed order update |
| order_update_status | OrderUpdateStatus | Order status update |
| order_update_trade | OrderUpdateTrade | Trade update for an order |
| order_update_trade_leg | OrderUpdateTradeLeg | Trade leg update for a complex order |
| create_uds_response | CreateUDSResponse | Response to user-defined strategy creation |
Heartbeat
The Heartbeat message is used to maintain an active connection between client and server.
| Field | Type | Description |
|---|---|---|
| timestamp | int64 | UTC timestamp in milliseconds |
Login Messages (auth.proto)
LoginRequest
The LoginRequest message is used to authenticate with the server. It supports either API key authentication or username/password authentication.
| Field | Type | Description |
|---|---|---|
| api_key | string | API key for authentication (if used, this is the only required field) |
| firm | string | Firm name/identifier for username/password authentication |
| username | string | Username for authentication |
| password | string | Password for authentication |
| app_name | string | Application name |
| app_license | string | Application license key |
LoginResponse
The LoginResponse message is the server's response to a login request.
| Field | Type | Description |
|---|---|---|
| result | LoginResult | Result of the login attempt |
| session_id | string | Session identifier for the authenticated session |
| user_id | string | User identifier |
| firm_id | string | Firm identifier |
| roles | repeated string | List of roles the user has |
| error_message | string | Error message if login failed |
| exchanges | repeated Exchange | List of exchanges the user has access to |
| accounts | repeated Account | List of accounts the user has access to |
LoginResponse.Exchange
The Exchange message inside LoginResponse contains details about an exchange the user has access to.
| Field | Type | Description |
|---|---|---|
| exchange_id | string | Exchange identifier |
| user_id | string | User identifier for this exchange |
| market_data_type | MarketDataType | Type of market data available |
| has_executing_account | bool | Whether the user has an executing account on this exchange |
| primary_user_id | string | Primary user identifier |
| secondary_user_id | string | Secondary user identifier |
| location | string | Location identifier |
| smp_id | string | SMP identifier |
| extra_detail | map<string, string> | Additional exchange-specific details |
LoginResponse.Account
The Account message inside LoginResponse contains details about an account the user has access to.
| Field | Type | Description |
|---|---|---|
| account_id | string | Account identifier |
| account_number | string | Account number |
| account_name | string | Account name |
| display_name | string | Display name for the account |
| mode | AccountMode | Account mode |
Quote Feed Messages (market.proto)
MarketDepthSubscribe
The MarketDepthSubscribe message is used to subscribe to market depth data for a specific market.
| Field | Type | Description |
|---|---|---|
| exchange_id | string | Exchange identifier |
| contract_id | string | Contract identifier |
| market_id | string | Market identifier |
| buffer | DepthBuffer | Type of depth buffer to subscribe to |
| depth_levels | DepthLevels | Number of depth levels to receive |
MarketDepthSubscribeReject
The MarketDepthSubscribeReject message is sent when a market depth subscription request is rejected.
| Field | Type | Description |
|---|---|---|
| market_id | string | Market identifier |
| time | google.protobuf.Timestamp | Time of rejection |
| mode | MarketMode | Current market mode |
MarketByOrderSubscribe
The MarketByOrderSubscribe message is used to subscribe to market-by-order data for a specific market.
| Field | Type | Description |
|---|---|---|
| exchange_id | string | Exchange identifier |
| contract_id | string | Contract identifier |
| market_id | string | Market identifier |
| subscribe | bool | Whether to subscribe (true) or unsubscribe (false) |
MarketByOrderSubscribeReject
The MarketByOrderSubscribeReject message is sent when a market-by-order subscription request is rejected.
| Field | Type | Description |
|---|---|---|
| market_id | string | Market identifier |
| time | google.protobuf.Timestamp | Time of rejection |
| mode | MarketMode | Current market mode |
MarketDetails
The MarketDetails message contains detailed information about a specific market.
| Field | Type | Description |
|---|---|---|
| market_id | string | Market identifier |
| exchange_id | string | Exchange identifier |
| contract_id | string | Contract identifier |
| expiry_date | int32 | Expiry date of the contract |
| contract_type | ContractType | Type of contract |
| decimals | int32 | Number of decimal places in prices |
| point_value | Decimal | Value of one price point |
| min_price_increment | Price | Minimum price increment |
| order_types | int32 | Bitfield of supported order types |
| activation_date | google.protobuf.Timestamp | Activation date of the market |
| last_trading_date | google.protobuf.Timestamp | Last trading date of the market |
| last_client_update_time | google.protobuf.Timestamp | Time of last client update |
| delist_date | int64 | Date when market will be delisted |
| exchange_delist_date | int64 | Exchange's delist date for the market |
| market_ref | string | Market reference |
| group | string | Market group |
| legs | repeated LegItem | Market legs (for multi-leg markets) |
| details | string | Additional market details |
| strategy_type | StrategyType | Type of strategy (for multi-leg markets) |
| price_code | string | Price code |
| real_decimals | int32 | Actual number of decimal places |
| display_decimals | int32 | Number of decimal places to display |
| clearing_decimals | int32 | Number of decimal places for clearing |
| min_cab_price | Price | Minimum cabinet price |
| strike_price | Price | Strike price (for options) |
| volume_increment | int32 | Volume increment |
| strategy_ratio | double | Strategy ratio |
| disabled | bool | Whether the market is disabled |
| underlying_market_id | string | Identifier of the underlying market |
| vtt | string | Variance Time Trading identifier |
| maint_intra_margin | double | Maintenance intraday margin |
| maint_margin | double | Maintenance margin |
| maint_vol_scan | double | Maintenance volume scan |
MarketDetails.LegItem
The LegItem message is a component of MarketDetails and describes a leg in a multi-leg market.
| Field | Type | Description |
|---|---|---|
| market_id | string | Market identifier of the leg |
| group | int32 | Group identifier |
| volume | int32 | Volume/ratio of the leg |
| delta | string | Delta value |
| price | Price | Price of the leg |
MarketDepth
The MarketDepth message contains market depth information for a specific market.
| Field | Type | Description |
|---|---|---|
| market_id | string | Market identifier |
| depth_levels | DepthLevels | Number of depth levels provided |
| depth_buffer | DepthBuffer | Type of depth buffer |
| time | google.protobuf.Timestamp | Time of the update |
| delayed | bool | Whether the data is delayed |
| bids | repeated DepthLine | Bid depth levels |
| offers | repeated DepthLine | Offer depth levels |
| implied_bids | repeated DepthLine | Implied bid depth levels |
| implied_offers | repeated DepthLine | Implied offer depth levels |
| mode | MarketMode | Current market mode |
| flags | MarketFlags2 | Market flags |
| trade_data | TradeData | Trade data |
MarketDepth.DepthLine
The DepthLine message is a component of MarketDepth and describes a single depth level.
| Field | Type | Description |
|---|---|---|
| price | Price | Price at this depth level |
| volume | int32 | Volume available at this depth level |
| num_orders | int32 | Number of orders at this depth level |
MarketDepth.TradeData
The TradeData message is a component of MarketDepth and contains trade information.
| Field | Type | Description |
|---|---|---|
| total_traded_volume | int32 | Total traded volume |
| total_trade_count | int32 | Total number of trades |
| last_trade_price | Price | Price of the last trade |
| last_trade_volume | int32 | Volume of the last trade |
| last_trade_total_volume | int32 | Cumulative volume of the last trade |
| last_trade_spd_price | Price | Price of the last spread trade |
| last_trade_spd_volume | int32 | Volume of the last spread trade |
| last_trade_spd_total_volume | int32 | Cumulative volume of the last spread trade |
| due_to_spread | bool | Whether the trade was due to a spread |
| at_bid_or_offer | BidOffer | Whether the trade was at the bid or offer |
| time | google.protobuf.Timestamp | Time of the trade |
MarketDepthTrade
The MarketDepthTrade message contains information about a trade in a specific market.
| Field | Type | Description |
|---|---|---|
| market_id | string | Market identifier |
| time | google.protobuf.Timestamp | Time of the trade |
| total_traded_volume | int32 | Total traded volume |
| last_trade_volume | int32 | Volume of the last trade |
| due_to_spread | bool | Whether the trade was due to a spread |
| at_bid_or_offer | BidOffer | Whether the trade was at the bid or offer |
| delayed | bool | Whether the data is delayed |
| order_volumes | repeated int32 | Volumes of individual orders in the trade |
| total_trade_count | int32 | Total number of trades |
| last_trade_price | Price | Price of the last trade |
| mode | MarketMode | Current market mode |
MarketHighLow
The MarketHighLow message contains high/low price information for a specific market.
| Field | Type | Description |
|---|---|---|
| market_id | string | Market identifier |
| open_price | Price | Opening price |
| high_price | Price | Highest price |
| low_price | Price | Lowest price |
| trade_date | int64 | Trade date |
| time | google.protobuf.Timestamp | Time of the update |
| delayed | bool | Whether the data is delayed |
MarketPriceLimits
The MarketPriceLimits message contains price limit information for a specific market.
| Field | Type | Description |
|---|---|---|
| market_id | string | Market identifier |
| high_price | Price | Upper price limit |
| low_price | Price | Lower price limit |
| time | google.protobuf.Timestamp | Time of the update |
| delayed | bool | Whether the data is delayed |
MarketSettlement
The MarketSettlement message contains settlement information for a specific market.
| Field | Type | Description |
|---|---|---|
| exchange_id | string | Exchange identifier |
| market_id | string | Market identifier |
| delayed | bool | Whether the data is delayed |
| settlement_price | Price | Settlement price |
| settlement_time | google.protobuf.Timestamp | Time of settlement |
| settlement_trade_date | google.protobuf.Timestamp | Trade date of settlement |
| settlement_held_price | string | Held settlement price |
| settlement_held_time | google.protobuf.Timestamp | Time of held settlement |
| settlement_held_trade_date | google.protobuf.Timestamp | Trade date of held settlement |
| implied_price | Price | Implied price |
| implied_held_price | Price | Held implied price |
| implied_time | google.protobuf.Timestamp | Time of implied price |
| open_interest | int32 | Open interest |
| open_interest_time | google.protobuf.Timestamp | Time of open interest update |
| open_interest_trade_date | google.protobuf.Timestamp | Trade date of open interest |
| cleared_volume | int32 | Cleared volume |
| cleared_volume_time | google.protobuf.Timestamp | Time of cleared volume update |
| cleared_volume_trade_date | google.protobuf.Timestamp | Trade date of cleared volume |
| vwap_price | Price | Volume-weighted average price |
| vwap_time | google.protobuf.Timestamp | Time of VWAP update |
| vwap_trade_date | google.protobuf.Timestamp | Trade date of VWAP |
MarketSnapshotMessage
The MarketSnapshotMessage message is a container for different types of market update messages.
| Field | Type | Description |
|---|---|---|
| payload | oneof | One of the following message types: MarketDepth, MarketDepthTrade, MarketHighLow, MarketPriceLimits, MarketSettlement |
MarketSnapshot
The MarketSnapshot message contains a complete snapshot of a market's state.
| Field | Type | Description |
|---|---|---|
| market_id | string | Market identifier |
| mode | MarketMode | Current market mode |
| due_to_connection | bool | Whether the snapshot is due to a new connection |
| delayed | bool | Whether the data is delayed |
| messages | repeated MarketSnapshotMessage | Market update messages |
MarketByOrderSnapshot
The MarketByOrderSnapshot message contains a complete snapshot of a market's order book.
| Field | Type | Description |
|---|---|---|
| market_id | string | Market identifier |
| time | google.protobuf.Timestamp | Time of the snapshot |
| mode | MarketMode | Current market mode |
| last_sequence | uint64 | Last sequence number |
| orders | repeated Order | Orders in the book |
MarketByOrderSnapshot.Order
The Order message is a component of MarketByOrderSnapshot and describes a single order in the book.
| Field | Type | Description |
|---|---|---|
| order_id | uint64 | Order identifier |
| bid_offer | BidOffer | Whether the order is a bid or offer |
| price | Price | Price of the order |
| volume | int32 | Volume of the order |
| priority | uint64 | Priority of the order |
MarketByOrderUpdate
The MarketByOrderUpdate message contains updates to a market's order book.
| Field | Type | Description |
|---|---|---|
| market_id | string | Market identifier |
| time | google.protobuf.Timestamp | Time of the update |
| mode | MarketMode | Current market mode |
| sequence | uint64 | Sequence number |
| updates | repeated Update | Order updates |
MarketByOrderUpdate.Update
The Update message is a component of MarketByOrderUpdate and describes an update to an order in the book.
| Field | Type | Description |
|---|---|---|
| update_type | UpdateType | Type of update |
| order_id | uint64 | Order identifier |
| bid_offer | BidOffer | Whether the order is a bid or offer |
| price | Price | Price of the order |
| volume | int32 | Volume of the order |
| priority | uint64 | Priority of the order |
Account Feed Messages (account.proto)
AccountSubscribe
The AccountSubscribe message is used to subscribe to account data.
| Field | Type | Description |
|---|---|---|
| subscribe | AccountSubscribeType | Type of subscription |
| subscribe_all_accounts | bool | Whether to subscribe to all accessible accounts |
| account_id | repeated string | List of specific account IDs to subscribe to |
AccountSubscribeResponse
The AccountSubscribeResponse message is the server's response to an account subscription request.
| Field | Type | Description |
|---|---|---|
| success | bool | Whether the subscription request was successful |
| errors | repeated string | Error messages if the request failed |
AccountCurrency
The AccountCurrency message contains currency information for an account.
| Field | Type | Description |
|---|---|---|
| currency | string | Currency code |
| rate | double | Exchange rate |
| import_factor | double | Import factor for the currency |
AccountPosition
The AccountPosition message contains position information for a specific market in an account.
| Field | Type | Description |
|---|---|---|
| account_id | string | Account identifier |
| exchange_id | string | Exchange identifier |
| contract_id | string | Contract identifier |
| market_id | string | Market identifier |
| buys | int32 | Number of buy trades |
| sells | int32 | Number of sell trades |
| working_buys | int32 | Number of working buy orders |
| working_sells | int32 | Number of working sell orders |
| rpl | double | Realized profit/loss |
| overnight_upl | double | Overnight unrealized profit/loss |
| margin | double | Margin requirement |
| mp | double | Market price |
| overnight_position | int32 | Overnight position |
| currency_rate | double | Currency exchange rate |
| trade_date | google.protobuf.Timestamp | Trade date |
| premium | double | Option premium |
| total_open_volume | int32 | Total open volume |
| fees_and_commissions | double | Fees and commissions |
| long_mp | double | Long market price |
| short_mp | double | Short market price |
| prev_position | int32 | Previous position |
| prev_margin | double | Previous margin requirement |
| prev_rpl | double | Previous realized profit/loss |
| prev_upl | double | Previous unrealized profit/loss |
| day_buys | int32 | Number of buy trades today |
| day_sells | int32 | Number of sell trades today |
| average_open_price | Price | Average open price |
| total_open_price | Price | Total open price |
| total_buy_fill_price | Price | Total buy fill price |
| total_sell_fill_price | Price | Total sell fill price |
| day_total_buy_fill_price | Price | Today's total buy fill price |
| day_total_sell_fill_price | Price | Today's total sell fill price |
| total_overnight_price | Price | Total overnight price |
| risk_status | ContractRiskStatus | Risk status of the position |
| margin_time | google.protobuf.Timestamp | Time of last margin calculation |
| alerting_margin | double | Alerting margin level |
| alerting_time | google.protobuf.Timestamp | Time of last alerting |
| day_margin | double | Today's margin requirement |
| full_margin | double | Full margin requirement |
| pre_trade_margin | double | Pre-trade margin requirement |
AccountUpdate
The AccountUpdate message contains updated information for an account.
| Field | Type | Description |
|---|---|---|
| account_id | string | Account identifier |
| status | AccountStatus | Account status |
| balance | double | Account balance |
| rpl | double | Realized profit/loss |
| overnight_upl | double | Overnight unrealized profit/loss |
| margin | double | Margin requirement |
| day_margin | double | Today's margin requirement |
| full_margin | double | Full margin requirement |
| base_margin | double | Base margin requirement |
| alerting_margin | double | Alerting margin level |
| pre_trade_margin | double | Pre-trade margin requirement |
| mp | double | Market price |
| premium | double | Option premium |
| long_mp | double | Long market price |
| short_mp | double | Short market price |
| fees_and_commissions | double | Fees and commissions |
| prev_margin | double | Previous margin requirement |
| imported_net_liq | double | Imported net liquidation value |
| imported_net_liq_date | google.protobuf.Timestamp | Date of imported net liquidation value |
| prev_imported_net_liq | double | Previous imported net liquidation value |
| prev_imported_net_liq_date | google.protobuf.Timestamp | Date of previous imported net liquidation value |
| filled_delta | double | Filled delta |
| working_delta | double | Working delta |
| margin_time | google.protobuf.Timestamp | Time of last margin calculation |
| alerting_time | google.protobuf.Timestamp | Time of last alerting |
AccountDetails
The AccountDetails message contains detailed information about an account.
| Field | Type | Description |
|---|---|---|
| account_id | string | Account identifier |
| account_name | string | Account name |
| account | string | Account number |
| enabled | AccountEnabled | Account enabled status |
| deleted | bool | Whether the account is deleted |
| max_clip_size | int32 | Maximum clip size |
| pre_trade_disabled | bool | Whether pre-trade checks are disabled |
| position_rollover | bool | Whether position rollover is enabled |
| pl_rollover | bool | Whether P&L rollover is enabled |
| firm_id | string | Firm identifier |
| min_balance | double | Minimum balance requirement |
| margin_pc | int32 | Margin percentage |
| loss_limit | double | Loss limit |
| loss_limit_pc | int32 | Loss limit percentage |
| overnight_margin_pc | int32 | Overnight margin percentage |
| order_routing | bool | Whether order routing is enabled |
| active_time_start | string | Start of active trading time |
| active_time_stop | string | End of active trading time |
| warning_threshold_pl | int32 | P&L warning threshold |
| warning_threshold_loss_limit | int32 | Loss limit warning threshold |
| warning_threshold_margin | int32 | Margin warning threshold |
| firm | string | Firm name |
| mode | AccountMode | Account mode |
| max_account_position | int32 | Maximum account position |
| day_loss_limit | double | Day loss limit |
| display_name | string | Display name |
| wide_market | int32 | Wide market setting |
| use_pl_for_margin | bool | Whether to use P&L for margin calculations |
| margin_type | AccountMarginType | Margin type |
| risk_details | string | Risk details |
| price_banding | int32 | Price banding setting |
| day_loss_limit_pc | int32 | Day loss limit percentage |
| options_settlement | bool | Whether options settlement is enabled |
| group_name | string | Group name |
| use_premium_for_margin | bool | Whether to use premium for margin calculations |
| warning_threshold_min_net_equity | double | Minimum net equity warning threshold |
AccountSnapshotMessage
The AccountSnapshotMessage message is a container for different types of account update messages.
| Field | Type | Description |
|---|---|---|
| payload | oneof | One of the following message types: AccountPosition, AccountUpdate, AccountDetails, AccountCurrency, MarketDetails, OrderUpdateMulti |
AccountSnapshot
The AccountSnapshot message contains a complete snapshot of an account's state.
| Field | Type | Description |
|---|---|---|
| account_id | string | Account identifier |
| last_update_requested | int64 | Timestamp of last update request |
| last_update_supplied | int64 | Timestamp of last update supplied |
| status | AccountStatus | Account status |
| due_to_connection | bool | Whether the snapshot is due to a new connection |
| messages | repeated AccountSnapshotMessage | Account update messages |