Open API Common Model Messages

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.


ProtoOADayOfWeek

Name Number Description
NONE 0
MONDAY 1
TUESDAY 2
WEDNESDAY 3
THURSDAY 4
FRIDAY 5
SATURDAY 6
SUNDAY 7


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).


ProtoOACommissionType

Name Number Description
USD_PER_MIL_USD 1 USD per million USD volume - usually used for FX. Example: 50 USD for 1 mil USD of trading volume. In cents.
USD_PER_LOT 2 USD per 1 lot - usually used for CFDs and futures for commodities, and indices. Example: 15 USD for 1 contract. In cents.
PERCENTAGE 3 Percentage of trading volume - usually used for Equities. Example: 0.005% of notional trading volume. Multiplied by 100,00.
QUOTE_CCY_PER_LOT 4 Quote ccy of Symbol per 1 lot - will be used for CFDs and futures for commodities, and indices. Example: 15 EUR for 1 contract of DAX. In cents.


ProtoOASymbolDistanceType

Name Number Description
SYMBOL_DISTANCE_IN_POINTS 1
SYMBOL_DISTANCE_IN_PERCENTAGE 2


ProtoOAMinCommissionType

Name Number Description
CURRENCY 1
QUOTE_CURRENCY 2


ProtoOATradingMode

Name Number Description
ENABLED 0
DISABLED_WITHOUT_PENDINGS_EXECUTION 1
DISABLED_WITH_PENDINGS_EXECUTION 2
CLOSE_ONLY_MODE 3


ProtoOAAccessRights

Name Number Description
FULL_ACCESS 0 Enable all trading.
CLOSE_ONLY 1 Only closing trading request are enabled.
NO_TRADING 2 View only access.
NO_LOGIN 3 No access.


ProtoOATotalMarginCalculationType

Name Number Description
MAX 0
SUM 1
NET 2


ProtoOAAccountType

Name Number Description
HEDGED 0 Allows multiple positions on a trading account for a symbol.
NETTED 1 Only one position per symbol is allowed on a trading account.
SPREAD_BETTING 2 Spread betting type account.


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.


ProtoOAPositionStatus

Position status ENUM.

Name Number Description
POSITION_STATUS_OPEN 1
POSITION_STATUS_CLOSED 2
POSITION_STATUS_CREATED 3 Empty position is created for pending order.
POSITION_STATUS_ERROR 4


Trader side ENUM. Used for order, position, deal.

Order's time in force ENUM.

Name Number Description
BUY 1
SELL 2


ProtoOAOrderType

Order type ENUM.

Name Number Description
MARKET 1
LIMIT 2
STOP 3
STOP_LOSS_TAKE_PROFIT 4
MARKET_RANGE 5
STOP_LIMIT 6


ProtoOATimeInForce

Order's time in force ENUM.

Name Number Description
GOOD_TILL_DATE 1
GOOD_TILL_CANCEL 2
IMMEDIATE_OR_CANCEL 3
FILL_OR_KILL 4
MARKET_RANGE 5


ProtoOAOrderStatus

Order status ENUM.

Name Number Description
ORDER_STATUS_ACCEPTED 1 Order request validated and accepted for execution
ORDER_STATUS_FILLED 2 Order is fully filled.
ORDER_STATUS_REJECTED 3 Order is rejected due to validation.
ORDER_STATUS_EXPIRED 4 Order expired. Might be valid for orders with partially filled volume that were expired on LP.
ORDER_STATUS_CANCELLED 5 Order is cancelled. Might be valid for orders with partially filled volume that were cancelled by LP.


ProtoOAOrderTriggerMethod

Name Number Description
TRADE 1 Stop Order: buy is triggered by ask, sell by bid; Stop Loss Order: for buy position is triggered by bid and for sell position by ask.
OPPOSITE 2 Stop Order: buy is triggered by bid, sell by ask; Stop Loss Order: for buy position is triggered by ask and for sell position by bid.
DOUBLE_TRADE 3 The same as TRADE, but trigger is checked after the second consecutive tick.
DOUBLE_OPPOSITE 4 The same as OPPOSITE, but trigger is checked after the second consecutive tick.


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

Position/order trading details entity.

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.


ProtoOAExecutionType

Execution event type ENUM.

Name Number Description
ORDER_ACCEPTED 2 Order passed validation.
ORDER_FILLED 3 Order filled.
ORDER_REPLACED 4 Pending order is changed with a new one.
ORDER_CANCELLED 5 Pending order is changed with a new one.
ORDER_EXPIRED 6 Order with GTD time in force is expired.
ORDER_REJECTED 7 Order is rejected due to validations.
ORDER_CANCEL_REJECTED 8 Cancel order request is rejected.
SWAP 9 Type related to SWAP execution events.
DEPOSIT_WITHDRAW 10 Type related to event of deposit or withdrawal cash flow operation.
ORDER_PARTIAL_FILL 11 Order is partially filled.
BONUS_DEPOSIT_WITHDRAW 12 Type related to event of bonus deposit or bonus withdrawal.


ProtoOABonusDepositWithdraw

The account deposit/withdrawal operation entity.

Required Type Field Name Description
required ProtoOAChangeBalanceType operationType The operation type - deposit or withdrawal.
required int64 bonusHistoryId The unique ID of the bonus deposit/withdrawal operation.
required int64 managerBonus Total amount of broker's bonus after the operation.
required int64 managerDelta Amount of bonus deposited/withdrew by manager.
required int64 isBonus Total amount of introducing broker's bonus after the operation.
required int64 isDelta Amount of bonus deposited/withdrew by introducing broker.
required int64 changeBonusTimestamp The exact time when bonus operation was executed.
optional string externalNote The note added to an operation. Visible to a trader.
required int64 introducingBrokerId ID of introducing broker who deposited/withdrew bonus.


ProtoOAChangeBonusType

Name Number Description
BONUS_DEPOSIT 1
BONUS_WITHDRAW 2


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.


ProtoOAChangeBalanceType

Name Number Description
BALANCE_DEPOSIT 1 Cash deposit.
BALANCE_WITHDRAW 2 Cash withdrawal.
BALANCE_DEPOSIT_STRATEGY_COMMISSION_INNER 1 Received mirroring commission.
BALANCE_WITHDRAW_STRATEGY_COMMISSION_INNER 2 Paid mirroring commission.
BALANCE_DEPOSIT_IB_COMMISSIONS 1 For IB account. Commissions paid by trader.
BALANCE_WITHDRAW_IB_SHARED_PERCENTAGE 2 For IB account. Withdrawal of commissions shared with broker.
BALANCE_DEPOSIT_IB_SHARED_PERCENTAGE_FROM_SUB_IB 1 For IB account. Commissions paid by sub-ibs.
BALANCE_DEPOSIT_IB_SHARED_PERCENTAGE_FROM_BROKER 2 or IB account. Commissions paid by broker.
BALANCE_DEPOSIT_REBATE 1 Deposit rebate for trading volume for period.
BALANCE_WITHDRAW_REBATE 2 Withdrawal of rebate.
BALANCE_DEPOSIT_STRATEGY_COMMISSION_OUTER 1 Mirroring commission.
BALANCE_WITHDRAW_STRATEGY_COMMISSION_OUTER 2 Mirroring commission.
BALANCE_WITHDRAW_BONUS_COMPENSATION 1 For IB account. Share commission with the Broker.
BALANCE_WITHDRAW_IB_SHARED_PERCENTAGE_TO_BROKER 2 IB commissions.
BALANCE_DEPOSIT_DIVIDENDS 1 Deposit dividends payments.
BALANCE_WITHDRAW_DIVIDENDS 2 Negative dividend charge for short position.
BALANCE_WITHDRAW_GSL_CHARGE 1 Charge for guaranteedStopLoss.
BALANCE_WITHDRAW_ROLLOVER 2 Charge of rollover fee for Shariah compliant accounts.
BALANCE_DEPOSIT_NONWITHDRAWABLE_BONUS 1 Broker's operation to deposit bonus.
BALANCE_WITHDRAW_NONWITHDRAWABLE_BONUS 2 Broker's operation to withdrawal bonus.
BALANCE_DEPOSIT_SWAP 1 Deposits of negative SWAP.
BALANCE_WITHDRAW_SWAP 2 SWAP charges.
BALANCE_DEPOSIT_MANAGEMENT_FEE 1 Mirroring commission.
BALANCE_WITHDRAW_MANAGEMENT_FEE 2 Mirroring commission.
BALANCE_DEPOSIT_PERFORMANCE_FEE 1 Mirroring commission.
BALANCE_WITHDRAW_INACTIVITY_FEE 2 Withdraw of inactivity fee from the balance.


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.