cTrader messages
49 documented messages of the cTrader Open API, grouped by what they do. Each has its fields, payload type and the source it was read from.
Independent and unofficialNewest check
Risk warning: CFDs and spread bets are complex instruments and come with a high risk of losing money rapidly due to leverage. You can lose money on these products, and each provider publishes its own loss figure under FCA rules. You should consider whether you understand how they work and whether you can afford to take the high risk of losing your money. Automated and API trading can amplify losses through bugs, connectivity failures and runaway orders.
These are messages sent over an open TCP or WebSocket connection, not HTTP endpoints: none has a method or a path. For that reason they are in no OpenAPI file on this site and the request builder does not list them. A message that is not listed is not recorded here, which is not evidence that it does not exist.
Account
4 messages
- ProtoOAReconcileReqAsks for the account's open positions and pending orders as they stand now.
- ProtoOAReconcileResReturns the account's open positions and its pending orders in one message.
- ProtoOATraderReqAsks for the data of one trading account.
- ProtoOATraderResReturns the trading account's data as a ProtoOATrader entity.
Authorisation
10 messages
- ProtoOAAccountAuthReqOpens a session for one trading account on a connection where the application is already authorised, using the access token granted for that account.
- ProtoOAAccountAuthResConfirms that the session for the trading account is open, naming the account.
- ProtoOAAccountLogoutReqAsks to end the session of one trading account on this connection.
- ProtoOAAccountLogoutResAcknowledges the logout request. The definition says the logout itself is complete only when ProtoOAAccountDisconnectEvent arrives.
- ProtoOAApplicationAuthReqAuthorises the application on a newly opened connection, with the client id and client secret it was registered with. An account session can be opened only on a connection where this has been done.
- ProtoOAApplicationAuthResConfirms that the application is authorised on this connection. It carries nothing beyond its payload type.
- ProtoOAGetAccountListByAccessTokenReqAsks which trading accounts an access token was granted for.
- ProtoOAGetAccountListByAccessTokenResLists the trading accounts the access token covers, with the scope of permission the token carries.
- ProtoOARefreshTokenReqExchanges a refresh token for a new access token for the granted trading account.
- ProtoOARefreshTokenResReturns the new access token, how long it lasts and a new refresh token.
Connection
7 messages
- ProtoHeartbeatEventA message with no content that shows the connection is alive. The server sends it when nothing else is being sent, and a client can send it to keep a connection open through a quiet spell of more than 30 seconds.
- ProtoOAAccountDisconnectEventSent when the server drops the session of one trading account. The account has to be authorised again before it can be used.
- ProtoOAAccountsTokenInvalidatedEventSent when the server ends the session of particular trading accounts while the connection and its other account sessions carry on. The definition gives the causes: the account or the cTrader ID was deleted, or the token was refreshed or revoked.
- ProtoOAClientDisconnectEventSent when the server ends the connection with the application. Every trading account session on the connection ends with it.
- ProtoOAErrorResThe general answer when a request fails. It names the error and can say when maintenance ends or how long a rate limited payload type stays blocked.
- ProtoOAVersionReqAsks the server for its version, which the definition says can be used to check the current version of the Open API scheme.
- ProtoOAVersionResReturns the version of the server application.
Historical data
4 messages
- ProtoOAGetTickDataReqAsks for historical ticks of one symbol, bid or ask, in a period of time.
- ProtoOAGetTickDataResReturns the historical ticks, newest first, one page at a time.
- ProtoOAGetTrendbarsReqAsks for historical bars of one size for one symbol, by period of time or by count.
- ProtoOAGetTrendbarsResReturns the historical bars that were asked for.
Live prices
7 messages
- ProtoOASpotEventCarries a live price for a subscribed symbol. The first one after subscribing holds the latest prices even when the market is closed.
- ProtoOASubscribeLiveTrendbarReqSubscribes to live bars of one size for one symbol. The definition says the symbol's live prices have to be subscribed to first, and the bars arrive inside ProtoOASpotEvent.
- ProtoOASubscribeLiveTrendbarResAcknowledges the subscription to live bars.
- ProtoOASubscribeSpotsReqSubscribes to the live prices of one or more symbols. The definition says a first ProtoOASpotEvent with the latest price follows, and then one for each price update.
- ProtoOASubscribeSpotsResAcknowledges that the subscription has been queued. The definition says the first ProtoOASpotEvent with the current price arrives shortly after.
- ProtoOAUnsubscribeSpotsReqStops the live prices of one or more symbols. The definition suggests it as a way to cut traffic, most of all when markets are volatile.
- ProtoOAUnsubscribeSpotsResAcknowledges that the request to stop live prices has been queued. The definition says a few more ProtoOASpotEvent messages can still arrive until it is done.
Orders and positions
13 messages
- ProtoOAAmendOrderReqChanges a pending order: its size, its prices, its expiry or its stop loss and take profit. The definition allows it only where the access token has trade permission for the account.
- ProtoOAAmendPositionSLTPReqChanges the stop loss and take profit of an open position. The definition allows it only where the access token has trade permission for the account.
- ProtoOACancelOrderReqCancels a pending order. The definition allows it only where the access token has trade permission for the account.
- ProtoOAClosePositionReqCloses an open position, in full or in part. The definition allows it only where the access token has trade permission for the account.
- ProtoOADealListReqAsks for the account's deals in a period of time. A deal is one execution, so this is the trade history.
- ProtoOADealListResReturns the deals in the period, one page at a time.
- ProtoOAExecutionEventSent when the server accepts or executes an order. It is the answer to the new order, cancel, amend and close requests, and it is also sent when a deposit or withdrawal takes place.
- ProtoOAExpectedMarginReqAsks for an estimate of the margin a trade would need under the account's leverage profile, which the definition says can be done before a new order is sent.
- ProtoOAExpectedMarginResReturns the margin estimate for buying and for selling, for each size that was asked about.
- ProtoOANewOrderReqSends a new order. The definition allows it only where the access token has trade permission for the account.
- ProtoOAOrderErrorEventSent when an order request meets an error. It names the error and, where they apply, the order and the position.
- ProtoOAOrderListReqAsks for the account's orders in a period of time.
- ProtoOAOrderListResReturns the orders in the period, one page at a time.
Symbols
4 messages
- ProtoOASymbolByIdReqAsks for the full details of one or more symbols, by id.
- ProtoOASymbolByIdResReturns each requested symbol with its full set of fields.
- ProtoOASymbolsListReqAsks for the symbols a trading account can use. Each comes back in a light form with a limited set of fields.
- ProtoOASymbolsListResReturns the account's symbols in their light form, and archived symbols where they were asked for.