1. Home
  2. API Reference 2.0
  3. Protobuf Messages Reference
  4. Open API Model Messages

Open API Model Messages

  API Reference 2.0   Getting Started   Open Authentication   Protocol Buffers   Protobuf Messages Reference   Open API Messages   Open API Model Messages   Open API Error Codes   Example Projects   .NET   JAVA   Spotware Proxy Cloud   API Reference 1.0   Getting Started   OAuth Services Description   Accounts API   Trading API   Developer Library   Protobuf Protocol Intro   Common Messages   Common Model Messages   Open API Messages   Open API Model Messages   Trading Events Flow example   Going Live   Available Resources   Test Environment   Code Samples   Getting Started in C#   Getting Started in JS and Node.js   Getting Started in Java   Getting Started in Xamarin   Playground   Terms of Use   Privacy Policy   Tutorials   Lesson 1. Your First App   Lesson 2. Get Trading Data   Lesson 3. Get Market Data   Lesson 4. Using Trading API   Frequently Asked Questions   Terms of Use

Open API Model Messages .proto file

ProtoOAAsset

The asset entity

Required Type Field Name Description
required int64 assetId The unique asset ID.
required string name The asset name.
optional string displayName User friendly name.


ProtoOASymbol

Trading symbol entity.

Required Type Field Name Description
required int64 symbolId The unique identifier of the symbol in specific server environment within cTrader platform. Different servers have different IDs.
required int32 digits Number of price digits to be displayed.
required int32 pipPosition Pip position on digits.
optional bool enableShortSelling If TRUE then the short selling with the symbol is enabled.
optional bool guaranteedStopLoss If TRUE then setting of guaranteedStopLoss is available for limited risk accounts.
optional ProtoOADayOfWeek swapRollover3Days Day of the week when 3x rollover is charged.
optional double swapLong SWAP charge for the long positions.
optional double swapShort SWAP charge for the short positions.
optional int64 maxVolume Maximum allowed volume for an order with a symbol.
optional int64 minVolume Minimum allowed volume for an order with a symbol.
optional int64 stepVolume Multiplier of the volume for an order.
optional uint64 maxExposure Value of max exposure per symbol, per account. Blocks execution if breached.
repeated ProtoOAInterval schedule Symbol trading interval, specified in seconds starting from SUNDAY 00:00 in specified time zone.
required int64 commission Commission base amount. Total commission depends on commissionType.
optional ProtoOACommissionType commissionType Commission type. See ProtoOACommissionType for details.
optional uint32 slDistance Minimum allowed distance between stop loss and current market price.
optional uint32 tpDistance Minimum allowed distance between take profit and current market price.
optional uint32 gslDistance Minimum allowed distance between guaranteed stop loss and current market price.
optional int64 gslCharge Guaranteed Stop Loss fee.
optional ProtoOASymbolDistanceType distanceSetIn Unit of the distance measure for slDistance, tpDistance, gslDistance.
optional int64 minCommission Minimum commission amount per trade.
optional ProtoOAMinCommissionType minCommissionType Minimum commission Type. See ProtoOAMinCommissionType for details.
optional string minCommissionAsset Currency for minimum commission. (USD or quote currency).
optional int64 rolloverCommission Amount of commission per trade for the Shariah Compliant accounts in deposit currency (swapFree = TRUE).
optional int32 skipRolloverDays Initial period before the first rolloverCommission will be charged on the account.
optional string scheduleTimeZone Time zone for the symbol trading intervals.
optional ProtoOATradingMode tradingMode Rules for trading with the symbol. See ProtoOATradingMode for details.
optional ProtoOADayOfWeek rolloverCommission3Days Day of the week (in UTC) when Administrative Fee charge amount will be tripled. Applied only if RolloverChargePeriod = 0 or 1.


ProtoOALightSymbol

Lightweight symbol entity.

Required Type Field Name Description
required int64 symbolId The unique identifier of the symbol in specific server environment within cTrader platform. Different servers have different IDs.
optional string symbolName Name of the symbol (e.g. EUR/USD).
optional bool enabled If TRUE then symbol is visible for traders.
optional int64 baseAssetId Base asset.
optional int64 quoteAssetId Quote asset.
optional int64 symbolCategoryId Id of the symbol category used for symbols grouping.
optional int64 description


ProtoOASymbolCategory

Symbol category entity.

Required Type Field Name Description
required int64 id The unique identifier of the symbol category.
required int64 assetClassId Link to the asset class. One asset class can have many symbol categories.
required string name Category name.


ProtoOAInterval

Symbol trading session entity.

Required Type Field Name Description
required uint32 startSecond Interval start, specified in seconds starting from SUNDAY 00:00 in specified time zone (inclusive to the interval).
required uint32 endSecond Interval end, specified in seconds starting from SUNDAY 00:00 in specified time zone (exclusive from the interval).


ProtoOATrader

Trading account entity.

Required Type Field Name Description
required int64 ctidTraderAccountId The unique Trader's Account ID used to match the responses to the Trader's Account.
required int64 balance Current account balance in cents (e.g. If USD 100.00 then value = 10000).
optional int64 balanceVersion Balance version used to identify the final balance. Increments each time when the trader's account balance is changed.
optional int64 managerBonus The amount of broker's bonus allocated to the account in cents.
optional int64 ibBonus The amount of introducing broker bonus allocated to the account cents.
optional int64 nonWithdrawableBonus Broker's bonus that cannot be withdrew from the account as cash.
optional ProtoOAAccessRights accessRights Access rights that an owner has to the account in cTrader platform. See ProtoOAAccessRights for details.
required int64 depositAssetId Deposit currency of the account.
optional bool swapFree If TRUE than account is Shariah compliant.
optional uint32 leverageInCents Account leverage (e.g. If leverage = 1:50 then value = 5000).
optional ProtoOATotalMarginCalculationType totalMarginCalculationType Margin computation type for the account (MAX, SUM, NET).
optional uint32 maxLeverage Maximum allowed leverage for the account. Used as validation when a Trader can change leverage value.
optional bool frenchRisk If TRUE then account is AMF compliant.
optional int64 traderLogin ID of the account that is unique per server (Broker).
optional ProtoOAAccountType accountType Account type: HEDGED, NETTED, etc.
optional string brokerName Some white label assigned to trader by broker at the moment of account creation.
optional int64 registrationTimestamp Unix timestamp of the account registration. Should be used as minimal date in historical data requests.


ProtoOAPosition

The trading position entity.

Required Type Field Name Description
required uint64 positionId The unique ID of the position. Note that a trader may have two positions with the same IDs, if the positions are taken from the different brokers accounts.
required ProtoOATradeData tradeData Position details. See ProtoOATradeData for details.
required ProtoOAPositionStatus positionStatus Current status of the position.
required int64 swap Total amount of charged swap on open position.
optional double price VWAP price of the position based on all executions (orders) linked to the position.
optional double stopLoss Current Stop Loss price.
optional double takeProfit Current Take Profit price.
optional int64 utcLastUpdateTimestamp The exact UTC time of the last change of the position, including amending Stop Loss or Take Profit of the position, execution of the related order, cancelling of the related order, etc.
optional int64 commission Current unrealized commission related to the position.
optional double marginRate The rate for used margin computation. Represented as Base/Deposit.
optional int64 mirroringCommission The amount of unrealized commission for copying the strategy.
optional bool guaranteedStopLoss If TRUE then the position Stop Loss is guaranteedStopLoss.
optional int64 usedMargin The amount of margin used for the position in the deposit currency.
optional ProtoOAOrderTriggerMethod stopLossTriggerMethod The stop trigger method for Stop Loss and Take Profit of the position.


ProtoOATradeData

The position/order trading details entity.

Required Type Field Name Description
required int64 symbolId The unique identifier of the symbol in specific server environment within cTrader platform. Different brokers have different IDs.
required int64 volume Volume in cents.
required ProtoOATradeSide tradeSide Trading direction - Buy or Sell.
optional int64 openTimestamp The exact time when the position was opened or the order was created.
optional string label The text label specified during the order request.
optional bool guaranteedStopLoss If TRUE then the position/order Stop Loss is guaranteedStopLoss.


ProtoOAOrder

Trade order entity.

Required Type Field Name Description
required int64 orderId The unique ID of the order. Note: trader might have two orders with the same ID if orders are taken from accounts from different brokers.
required ProtoOATradeData tradeData Detailed trader data.
required ProtoOAOrderType orderType Order type.
required ProtoOAOrderStatus orderStatus Order status.
optional int64 expirationTimestamp If the order has time in force GTD then expiration is specified.
optional double executionPrice Price at which an order was executed. For order with FILLED status.
optional int64 executedVolume Part of the volume that was filled.
optional int64 utcLastUpdateTimestamp The exact UTC time the order was last updated.
optional double baseSlippagePrice Used for the Market Range order with combination of slippageInPoints to specify the price range where the order can be executed.
optional int64 slippageInPoints Used for the Market Range and the STOP_LIMIT orders to specify the price range where the order can be executed.
optional bool closingOrder If TRUE then the order is closing the part of the whole position. Should have specified positionId.
optional double limitPrice Valid only for the LIMIT orders.
optional double stopPrice Valid only for the STOP and the STOP_LIMIT orders.
optional double stopLoss The absolute Stop Loss price.
optional double takeProfit The absolute Take Profit price.
optional string clientOrderId Optional Client Order ID. Maximum length - 50 characters.
optional ProtoOATimeInForce timeInForce Order's Time in Force. Depends on the order type.
optional int64 positionId The unique ID of the position linked to the order (e.g. closing order, order that increase volume of a specific position, etc.)
optional int64 relativeStopLoss Relative Stop Loss that can be specified instead of absolute one. Specified in 1/100'000 of a unit of the price. For BUY stopLoss = Entry Price - Relative Stop Loss. For SELL Stop Loss = Entry Price + Relative Stop Loss.
optional int64 relativeTakeProfit Relative Take Profit that can be specified instead of the absolute one. Specified in 1/100'000 of a unit of the price. For BUY Take Profit = Entry Price + Relative Take Profit. For SELL Take Profit = Entry Price - Relative Take Profit.
optional bool isStopOut If TRUE then order was stopped out from server side.
optional bool trailingStopLoss If TRUE then the order is a Trailing Stop Loss. Valid for the STOP_LOSS_TAKE_PROFIT orders.
optional ProtoOAOrderTriggerMethod stopTriggerMethod Trigger method for the order. Valid only for the STOP and the STOP_LIMIT orders.


ProtoOABonusDepositWithdraw

Bonus deposit/withdrawal entity.

Required Type Field Name Description
required ProtoOAChangeBonusType operationType Type of the operation - Deposit or Withdrawal.
required int64 bonusHistoryId The unique ID of the bonus deposit/withdrawal operation.
required int64 managerBonus The total amount of the broker's bonus after the operation.
required int64 managerDelta The amount of bonus deposited/withdrew by a manager.
required int64 ibBonus The total amount of an introducing broker's bonus after the operation.
required int64 ibDelta The amount of bonus deposited/withdrew by an introducing broker.
required int64 changeBonusTimestamp The time when the bonus operation was executed.
required int64 externalNote The note added to the operation. Visible to a trader.
required int64 introducingBrokerId The unique ID of an introducing broker who deposited/withdrew the bonus.


ProtoOADepositWithdraw

The account deposit/withdrawal operation entity.

Required Type Field Name Description
required ProtoOAChangeBalanceType operationType The operation type - deposit or withdrawal.
required int64 balanceHistoryId The unique ID of the deposit/withdrawal operation.
required int64 balance Account balance after the operation was executed.
required int64 delta The amount of deposit or withdrawal operation.
required int64 changeBalanceTimestamp The exact time when deposit or withdrawal operation was executed.
optional string externalNote The note added to an operation. Visible to a trader.
required int64 balanceVersion The balance version used to identify the final balance. Increments each time when a trader's account balance is changed.
required int64 equity The total account equity after a balance operation was executed.


ProtoOADeal

The execution entity.

Required Type Field Name Description
required int64 dealId The unique ID of the execution deal.
required int64 orderId Source order of the deal.
required int64 positionId Source position of the deal.
required int64 volume Volume sent for execution, in cents.
required int64 filledVolume Filled volume in cents.
required int64 symbolId The unique identifier of the symbol in specific server environment within cTrader platform. Different servers have different IDs.
required int64 createTimestamp The exact time when the deal was sent for execution.
required int64 executionTimestamp The exact time when the deal was executed.
optional int64 utcLastUpdateTimestamp The exact time when the deal was created, executed or rejected.
optional double executionPrice Execution price.
required ProtoOATradeSide tradeSide The trading direction - Buy or Sell.
required ProtoOADealStatus dealStatus The current status of the deal.
optional double marginRate The rate for used margin computation. Represented as Base/Deposit.
optional int64 commission The amount of trading commission associated with the deal.
optional double baseToUsdConversionRate Base to USD conversion rate on the time of deal execution.
optional ProtoOAClosePositionDetail closePositionDetail Closing position details. Valid only for the closing deal.


ProtoOAClosePositionDetail

Trading details for closing deal.

Required Type Field Name Description
required double entryPrice Position price at the moment of filling the closing order.
required int64 grossProfit The amount of realized gross profit after the closing deal execution.
required int64 swap The amount of realized swap in cents related to the closed volume.
required int64 commission Amount of realized commission in cents related to closed volume.
required int64 balance Account balance after the closing deal execution.
optional double quoteToDepositConversionRate Quote/Deposit currency conversion rate on the time of closing deal execution.
optional int64 closedVolume Closed volume in cents.
optional int64 alanceVersion Balance version of the account related to the closing deal operation.


ProtoOATrendbar

Historical Trendbar entity.

Required Type Field Name Description
required int64 volume The bar volume in ticks.
optional ProtoOATrendbarPeriod period Bar period.
optional int64 low The low price of the bar.
optional uint64 deltaOpen The delta between the open and the low price. Open = Low + Delta Open.
optional uint64 deltaClose The delta between the open and the low price. Close = Low + Delta Close.
optional uint64 deltaHigh The delta between the open and the low price. High = Low + Delta High.
optional uint32 utcTimestampInMinutes The timestamp of the bar. Equals to the timestamp of the open tick.


ProtoOAExpectedMargin

Expected margin computation entity.

Required Type Field Name Description
required int64 volume The volume used for computation.
required int64 buyMargin Buy margin amount in cents.
required int64 sellMargin Sell margin amount in cents.


ProtoOATickData

Historical tick data type.

Required Type Field Name Description
required int64 timestamp The tick timestamp.
required int64 tick The tick price.


ProtoOACtidProfile

Trader profile entity. Empty due to GDPR.

Required Type Field Name Description
required int64 userId The unique user ID.


ProtoOACtidTraderAccount

Trader account entity.

Required Type Field Name Description
required int64 ctidTraderAccountId Unique identifier of the trader's account. Used to match responses to trader's accounts.cTrader platform. Different brokers might have different ids
optional bool isLive If TRUE then the account is belong to Live environment and live host must be used to authorize it
optional int64 traderLogin Trading account number


ProtoOAAssetClass

The asset class entity.

Required Type Field Name Description
optional int64 id The unique asset ID.
optional string name The asset class name.


ProtoOADepthQuote

The depth of market entity.

Required Type Field Name Description
required uint64 id The quote ID.
required uint64 size The quote size in cents.
required uint64 bid The bid price for bid quotes.
required uint64 ask The ask price for ask quotes.

Copyright © 2019 Spotware Systems Ltd. cTrader®, cAlgo®, cBroker®, cMirror®. All rights reserved.

The services provided by Spotware Systems Ltd. are not available to citizens or residents of the USA. Neither is the information on our websites directed toward soliciting citizens or residents of the USA.