cTrader Open API

https://help.ctrader.com/open-api
Admin
cTrader Open API is a REST and Protobuf-based API that enables third-party applications to integrate...
Tokens:79,786
Snippets:659
Trust Score:9.6
Update:6 days ago
Show doc for...
Tokens:
Raw
### C#: Get conversion symbols and add to list

Source: https://help.ctrader.com/open-api/symbol-rate-conversion?q=

C# example that sends ProtoOASymbolsForConversionReq and stores the returned light symbols in a list. Includes a helper method GetConversionSymbols that returns a Task<ProtoOALightSymbol[]>.

```csharp
List<ProtoOALightSymbol> lightSymbolsForConversion = new List<ProtoOALightSymbol>();

var symbolsResult = await GetConversionSymbols(accountId, isLive, baseAssetId, quoteAssetId);

lightSymbolsForConversion.AddRange(symbolsResult);

public Task<ProtoOALightSymbol[]> GetConversionSymbols(long accountId, bool isLive, long baseAssetId, long quoteAssetId)
{
    VerifyConnection();

    var client = GetClient(isLive);

    var taskCompletionSource = new TaskCompletionSource<ProtoOALightSymbol[]>();

    IDisposable disposable = null;

    disposable = client.OfType<ProtoOASymbolsForConversionRes>().Where(response => response.CtidTraderAccountId == accountId)
        .Subscribe(response =>
        {
            taskCompletionSource.SetResult(response.Symbol.ToArray());

            disposable?.Dispose();
        });

    var requestMessage = new ProtoOASymbolsForConversionReq
    {
        CtidTraderAccountId = accountId,
        FirstAssetId = baseAssetId,
        LastAssetId = quoteAssetId
    };

    EnqueueMessage(requestMessage, ProtoOAPayloadType.ProtoOASymbolsForConversionReq, client);

    return taskCompletionSource.Task;
}
```

--------------------------------

### Install Python SDK with pip

Source: https://help.ctrader.com/open-api/python-SDK/python-sdk-index?q=

Run this command inside your project environment to install the ctrader-open-api package.

```bash
pip install ctrader-open-api

```

--------------------------------

### Install cTrader.OpenAPI.Net via NuGet

Source: https://help.ctrader.com/open-api/net_SDK/net-sdk-index

Run this command in the NuGet package manager console to install the cTrader.OpenAPI.Net package. Alternatively, search for the cTrader.OpenAPI.NET package in the NuGet package manager solution.

```powershell
Install-Package cTrader.OpenAPI.Net
```

--------------------------------

### Install cTrader.OpenAPI.Net package via NuGet

Source: https://help.ctrader.com/open-api/net_SDK/net-sdk-index?q=

Run this command in the NuGet package manager console to install the cTrader.OpenAPI.Net package. Alternatively, search for the cTrader.OpenAPI.NET package in the NuGet package manager solution.

```powershell
Install-Package cTrader.OpenAPI.Net

```

--------------------------------

### Send ProtoOASymbolsForConversionReq to get conversion chain (C# and Python)

Source: https://help.ctrader.com/open-api/symbol-rate-conversion

Send ProtoOASymbolsForConversionReq with firstAssetId and lastAssetId to obtain a conversion chain. The C# example stores the returned ProtoOALightSymbol array in a list; the Python example sends the request and then handles the ProtoOASymbolsForConversionRes response in the onMessageReceived callback. Note that the Python request uses 'firstAssedId' (typo in source) and the response handler extracts the 'symbol' field.

```csharp
List<ProtoOALightSymbol> lightSymbolsForConversion = new List<ProtoOALightSymbol>();

var symbolsResult = await GetConversionSymbols(accountId, isLive, baseAssetId, quoteAssetId);

lightSymbolsForConversion.AddRange(symbolsResult);

public Task<ProtoOALightSymbol[]> GetConversionSymbols(long accountId, bool isLive, long baseAssetId, long quoteAssetId)
{
    VerifyConnection();

    var client = GetClient(isLive);

    var taskCompletionSource = new TaskCompletionSource<ProtoOALightSymbol[]>();

    IDisposable disposable = null;

    disposable = client.OfType<ProtoOASymbolsForConversionRes>().Where(response => response.CtidTraderAccountId == accountId)
        .Subscribe(response =>
        {
            taskCompletionSource.SetResult(response.Symbol.ToArray());

            disposable?.Dispose();
        });

    var requestMessage = new ProtoOASymbolsForConversionReq
    {
        CtidTraderAccountId = accountId,
        FirstAssetId = baseAssetId,
        LastAssetId = quoteAssetId
    };

    EnqueueMessage(requestMessage, ProtoOAPayloadType.ProtoOASymbolsForConversionReq, client);

    return taskCompletionSource.Task;
}
```

```python
def sendProtoOASymbolsForConversionReq(accountId, firstAssetId, lastAssetId):
    request = ProtoOASymbolsForConversionReq()
    request.ctidTraderAccountId = accountId
    request.firstAssedId = firstAssetId
    request.lastAssetId = lastAssetId
```

```python
elif message.payloadType == ProtoOASymbolsForConversionRes().payloadType:
    ProtoOASymbolsForConversionRes = Protobuf.extract(message)
    conversionSymbols = ProtoOASymbolsForConversionRes.symbol
```

--------------------------------

### C#: ConnectWebSocket method

Source: https://help.ctrader.com/open-api/sending-receiving-protobuf

Sets up the WebSocket client with the host and port, disables text conversion and reconnection, and subscribes to message received and disconnection events. Starts the client asynchronously.

```csharp
private async Task ConnectWebSocket()
{
    DefaultInterpolatedStringHandler defaultInterpolatedStringHandler = new DefaultInterpolatedStringHandler(7, 2);
    defaultInterpolatedStringHandler.AppendLiteral("wss://");
    defaultInterpolatedStringHandler.AppendFormatted(Host);
    defaultInterpolatedStringHandler.AppendLiteral(":");
    defaultInterpolatedStringHandler.AppendFormatted(Port);
    Uri url = new Uri(defaultInterpolatedStringHandler.ToStringAndClear());
    _websocketClient = new WebsocketClient(url, () => new ClientWebSocket())
    {
        IsTextMessageConversionEnabled = false,
        ReconnectTimeout = null,
        IsReconnectionEnabled = false,
        ErrorReconnectTimeout = null
    };
    _webSocketMessageReceivedDisposable = _websocketClient.MessageReceived.Select((ResponseMessage msg) => ProtoMessage.Parser.ParseFrom(msg.Binary)).Subscribe(new Action<ProtoMessage>(OnNext));
    _webSocketDisconnectionHappenedDisposable = _websocketClient.DisconnectionHappened.Subscribe(new Action<DisconnectionInfo>(OnWebSocketDisconnectionHappened));
    await _websocketClient.StartOrFail();
}

```

--------------------------------

### Successful access token response example

Source: https://help.ctrader.com/open-api/account-authentication?q=

This is an example of a successful JSON response from the apps/token endpoint. It includes the accessToken, tokenType, expiresIn, refreshToken, and null values for errorCode and description.

```json
{
    "accessToken":"mos8Bw3D4EG0fRPd4Eqq0JxaFT4zjd8e4YijNezh_ag",
    "tokenType":"bearer",
    "expiresIn":2628000,
    "refreshToken":"VCuafFhy81AFZjsWkbuEzdOhhRj5YTWz8fWUwHam7KM",
    "errorCode":null,
    "description":null,
}

```

--------------------------------

### C#: Send ProtoBuf authentication messages

Source: https://help.ctrader.com/open-api/account-authentication?q=

C# example using OpenClient to send ProtoOAApplicationAuthReq, ProtoOAGetAccountListByAccessTokenReq, and ProtoOAAccountAuthReq. It subscribes to ProtoOAGetAccountListByAccessTokenRes and handles the response to send account auth. Placeholders like {your_client_id} and {access_token} must be replaced.

```csharp
private static RepeatedField<ProtoOACtidTraderAccount> _ctidTraderAccounts;

List<IDisposable> _disposables = new();
_disposables.Add(_client.OfType<ProtoOAGetAccountListByAccessTokenRes>().Subscribe(OnAccountIdReceived));

private static void OnAccountIdReceived(ProtoOAGetAccountListByAccessTokenRes response)
{

    Console.WriteLine($"\nMessage Received:\n{response}");

    _ctidTraderAccounts = response.CtidTraderAccount;

    var accountAuthReq = new ProtoOAAccountAuthReq
    {
        CtidTraderAccountId = (long)_ctidTraderAccounts[0].CtidTraderAccountId,
        AccessToken = _token.AccessToken,
    };

    _client.SendMessage(accountAuthReq);

}

var _client = new OpenClient(host, ApiInfo.Port, TimeSpan.FromSeconds(10), useWebSocket: false);
var applicationAuthReq = new ProtoOAApplicationAuthReq
{
    ClientId = {your_client_id}, // Add your client ID here
    ClientSecret = {your_app_secret}, // Add your app secret here
};
await _client.SendMessage(applicationAuthReq);
await Task.Delay(5000);
var getAccountListByAccessToken = new ProtoOAGetAccountListByAccessTokenReq 
{
    AccessToken = {access_token} // Add your access token here
}
var accountAuthReq = new ProtoOAAccountAuthReq 
{
    ctidTraderAccountId = {account_id}, // Add the ctidTraderAccountId of the account you want to authorize here
    AccessToken = {access_token} // Add your access token here
};
await _client.SendMessage(accountAuthReq);
```

--------------------------------

### Python: Send ProtoBuf authentication messages

Source: https://help.ctrader.com/open-api/account-authentication

Python example that sends ProtoOAApplicationAuthReq, ProtoOAGetAccountListByAccessTokenReq, and ProtoOAAccountAuthReq messages. It uses a Client with TcpProtocol and callbacks for connection, disconnection, and message handling, and schedules a user command after each message.

```python
currentAccountId = None
client = Client(EndPoints.PROTOBUF_LIVE_HOST if hostType.lower() == "live" else EndPoints.PROTOBUF_DEMO_HOST, EndPoints.PROTOBUF_PORT, TcpProtocol)

def connected(client): # Callback for client connection
    print("\nConnected")
    request = ProtoOAApplicationAuthReq()
    request.clientId = appClientId
    request.clientSecret = appClientSecret
    deferred = client.send(request)



def disconnected(client, reason): # Callback for client disconnection
    print("\nDisconnected: ", reason)

def onMessageReceived(client, message): # Callback for receiving all messages
    global currentAccountId
    if message.payloadType in [ProtoOASubscribeSpotsRes().payloadType, ProtoOAAccountLogoutRes().payloadType, ProtoHeartbeatEvent().payloadType]:
        return
    elif message.payloadType == ProtoOAApplicationAuthRes().payloadType:
        print("API Application authorized\n")
        if currentAccountId is not None:
            sendProtoOAAccountAuthReq()
            return
        accountListReq = ProtoOAGetAccountListByAccessTokenReq()
        accountListReq.accessToken = accessToken
        deferred = client.send(accountListReq)
    elif message.payloadType == ProtoOAGetAccountListByAccessTokenRes().payloadType:
        protoOAGetAccountListByAccessTokenRes = Protobuf.extract(message)
        currentAccountId = int(protoOAGetAccountListByAccessTokenRes.ctidTraderAccount[0].ctidTraderAccountId)
        accountAuthReq = ProtoOAAccountAuthReq()
        accountAuthReq.ctidTraderAccountId = currentAccountId
        accountAuthReq.accessToken = accessToken
        deferred = client.send(accountAuthReq)
    elif message.payloadType == ProtoOAAccountAuthRes().payloadType:
        protoOAAccountAuthRes = Protobuf.extract(message)
        print(f"Account {protoOAAccountAuthRes.ctidTraderAccountId} has been authorized\n")
        print("This acccount will be used for all future requests\n")
    else:
        print("Message received: \n", Protobuf.extract(message))
    reactor.callLater(3, callable=executeUserCommand)

def onError(failure): # Call back for errors
    print("Message Error: ", failure)
    reactor.callLater(3, callable=executeUserCommand)
```

--------------------------------

### Python serialization and length prefix for Protobuf messages

Source: https://help.ctrader.com/open-api/sending-receiving-protobuf?q=

Python example showing how to serialize a Protobuf message and prepend its length as a reversed byte array. Uses SerializeToString and struct.pack.

```Python
request = ProtoOAApplicationAuthReq() # Can be any message
requestAsString = request.SerializeToString() # This method is a part of the Google Protobuf SDK
requestAsInt32String = struct.pack("!H", len(requestAsString)) # The message is concatenated with the reversed array
```

--------------------------------

### Python client.send for sending Protobuf messages

Source: https://help.ctrader.com/open-api/sending-receiving-protobuf?q=

Python example using Twisted to create a client and send a Protobuf message. It creates a ProtoOAApplicationAuthReq message and sends it via the client.send method.

```Python
client = Client(EndPoints.PROTOBUF_LIVE_HOST if hostType.lower() == "live" else EndPoints.PROTOBUF_DEMO_HOST, EndPoints.PROTOBUF_PORT, TcpProtocol)
request = ProtoOAApplicationAuthReq() # Can be any message
deferred = client.send(request)
```

--------------------------------

### Refresh access token via Protobuf message in Python

Source: https://help.ctrader.com/open-api/account-authentication?q=

Python example for refreshing the access token using the auth.refreshToken method with the refresh token as a string argument.

```python
newToken = auth.refreshToken("refresh_Token")
```

--------------------------------

### Python: Send ProtoBuf authentication messages

Source: https://help.ctrader.com/open-api/account-authentication?q=

Python example using the cTrader Open API client with Twisted reactor. It defines callbacks for connection, disconnection, message reception, and errors. It sends ProtoOAApplicationAuthReq, then ProtoOAGetAccountListByAccessTokenReq, and finally ProtoOAAccountAuthReq, printing authorization status.

```python
currentAccountId = None
client = Client(EndPoints.PROTOBUF_LIVE_HOST if hostType.lower() == "live" else EndPoints.PROTOBUF_DEMO_HOST, EndPoints.PROTOBUF_PORT, TcpProtocol)

def connected(client): # Callback for client connection
    print("\nConnected")
    request = ProtoOAApplicationAuthReq()
    request.clientId = appClientId
    request.clientSecret = appClientSecret
    deferred = client.send(request)



def disconnected(client, reason): # Callback for client disconnection
    print("\nDisconnected: ", reason)

def onMessageReceived(client, message): # Callback for receiving all messages
    global currentAccountId
    if message.payloadType in [ProtoOASubscribeSpotsRes().payloadType, ProtoOAAccountLogoutRes().payloadType, ProtoHeartbeatEvent().payloadType]:
        return
    elif message.payloadType == ProtoOAApplicationAuthRes().payloadType:
        print("API Application authorized\n")
        if currentAccountId is not None:
            sendProtoOAAccountAuthReq()
            return
        accountListReq = ProtoOAGetAccountListByAccessTokenReq()
        accountListReq.accessToken = accessToken
        deferred = client.send(accountListReq)
    elif message.payloadType == ProtoOAGetAccountListByAccessTokenRes().payloadType:
        protoOAGetAccountListByAccessTokenRes = Protobuf.extract(message)
        currentAccountId = int(protoOAGetAccountListByAccessTokenRes.ctidTraderAccount[0].ctidTraderAccountId)
        accountAuthReq = ProtoOAAccountAuthReq()
        accountAuthReq.ctidTraderAccountId = currentAccountId
        accountAuthReq.accessToken = accessToken
        deferred = client.send(accountAuthReq)
    elif message.payloadType == ProtoOAAccountAuthRes().payloadType:
        protoOAAccountAuthRes = Protobuf.extract(message)
        print(f"Account {protoOAAccountAuthRes.ctidTraderAccountId} has been authorized\n")
        print("This acccount will be used for all future requests\n")
    else:
        print("Message received: \n", Protobuf.extract(message))
    reactor.callLater(3, callable=executeUserCommand)

def onError(failure): # Call back for errors
    print("Message Error: ", failure)
    reactor.callLater(3, callable=executeUserCommand)
```

--------------------------------

### ConnectTcp method implementation

Source: https://help.ctrader.com/open-api/connection

Shows the internal implementation of the TCP connection method called by OpenClient.Connect(). It creates a TcpClient, authenticates an SSL stream, and starts reading asynchronously.

```csharp
private async Task ConnectTcp()
{
    _tcpClient = new TcpClient
    {
        LingerState = new LingerOption(enable: true, 10)
    };
    await _tcpClient.ConnectAsync(Host, Port).ConfigureAwait(continueOnCapturedContext: false);
    _sslStream = new SslStream(_tcpClient.GetStream(), leaveInnerStreamOpen: false);
    await _sslStream.AuthenticateAsClientAsync(Host).ConfigureAwait(continueOnCapturedContext: false);
    Task.Run(delegate
    {
        ReadTcp(_cancellationTokenSource.Token);
    });
}
```

--------------------------------

### Refresh access token via Protobuf message in C#

Source: https://help.ctrader.com/open-api/account-authentication?q=

C# example for refreshing the access token using the ProtoOARefreshTokenReq and ProtoOARefreshTokenRes messages. Subscribe to the response, handle it by updating the token, and send the request with your refresh token.

```csharp
_disposables.Add(_client.OfType<ProtoOARefreshTokenRes>().Subscribe(OnRefreshTokenResponse));
private static void OnRefreshTokenResponse(ProtoOARefreshTokenRes response) 
{
    _token = new Token 
    {
        AccessToken = response.AccessToken,
        RefreshToken = response.RefreshToken,
        ExpiresIn = DateTimeOffset.FromUnixTimeMilliseconds(response.ExpiresIn),
        TokenType = response.TokenType,
    }
}
var refreshTokenReq = new ProtoOARefreshTokenReq
    {
        refreshToken = {your_refresh_token}, // Add your refresh token here
    };
await _client.SendMessage(applicationAuthReq);
```

--------------------------------

### C# WriteTcp method for sending Protobuf messages

Source: https://help.ctrader.com/open-api/sending-receiving-protobuf?q=

C# example showing how to send a Protobuf message over a TCP connection. It converts the message length to a byte array, reverses it, concatenates with the message, and writes to the SSL stream.

```C#
private async Task WriteTcp(byte[] messageByte, CancellationToken cancellationToken)
{
    byte[] array = BitConverter.GetBytes(messageByte.Length).Reverse().Concat(messageByte)
        .ToArray();
    await _sslStream.WriteAsync(array, 0, array.Length, cancellationToken).ConfigureAwait(continueOnCapturedContext: false);
    await _sslStream.FlushAsync(cancellationToken).ConfigureAwait(continueOnCapturedContext: false);
}
```

--------------------------------

### Handle ProtoOAVersionReq errors with twisted errback

Source: https://help.ctrader.com/open-api/error-handling

Subscribe to an error callback for every message sent when using the twisted library. This example shows sending a ProtoOAVersionReq and adding an errback that prints the failure and schedules executeUserCommand after 3 seconds.

```Python
def sendProtoOAVersionReq(clientMsgId = None):
    request = ProtoOAVersionReq()
    deferred = client.send(request, clientMsgId = clientMsgId)
    deferred.addErrback(onError)

def onError(failure):
    print("Message Error: ", failure)
    reactor.callLater(3, callable=executeUserCommand)
```

--------------------------------

### Example JSON string for ProtoOAApplicationAuthReq

Source: https://help.ctrader.com/open-api/sending-receiving-json

A valid JSON string representing the ProtoOAApplicationAuthReq message. It must contain the keys clientMsgId, payloadType, and payload. The clientMsgId is a unique ID generated on the client side, payloadType is the integer 2100 for this message, and payload is a nested JSON object with clientId and clientSecret.

```json
"{"clientMsgId": "cm_id_2", "payloadType": 2100, "payload": {"clientId": "34Rsd_T098asHkl","clientSecret": "validClientSecret"}}"
```

--------------------------------

### curl REST call to apps/token

Source: https://help.ctrader.com/open-api/account-authentication?q=

This example shows a GET request to the apps/token endpoint with the authorization_code grant type. It uses query parameters for code, redirect_uri, client_id, and client_secret. The request requires an Accept header of application/json and a Content-Type header of application/json.

```curl
curl -X GET 'https://openapi.ctrader.com/apps/token?grant_type=authorization_code&code=0ssdgds98as9_QSF56FVC_22dfdf&redirect_uri=https://spotware.com&client_id=5430012&client_secret=012sds23dlkjQsd' -H 'Accept: application/json' -H 'Content-Type: application/json'

```

--------------------------------

### Get deposit asset ID from ProtoOATrader (Python)

Source: https://help.ctrader.com/open-api/symbol-rate-conversion?q=

Get the deposit currency asset ID from a ProtoOATrader account object.

```python
depositAssetId = account.depositAssetId

```

--------------------------------

### Get deposit asset ID from ProtoOATrader (C#)

Source: https://help.ctrader.com/open-api/symbol-rate-conversion?q=

Get the deposit currency asset ID from a ProtoOATrader account object.

```csharp
int depositAssetId = account.DepositAssetId;

```

--------------------------------

### GET apps/token

Source: https://help.ctrader.com/open-api/account-authentication?q=

This snippet documents the GET /apps/token endpoint used to obtain an access token for cTrader Open API authentication.

```APIDOC
## GET apps/token

### Description
Attain an access token by exchanging an authorization code or refreshing an existing token. This endpoint is used to authenticate messages sent to cTrader Open API.

### Method
GET

### Endpoint
https://openapi.ctrader.com/apps/token

### Parameters
#### Query Parameters
- **grant_type** (string) - Required - The type of the token sent to this endpoint. Accepted values: `authorization_code` (an authorization code is sent to exchange it with an access token) or `refresh_token` (a refresh token is sent to refresh an existing access token).
- **code** (string) - Optional - The token sent to the endpoint. Mandatory if `grant_type=authorization_code`.
- **redirect_uri** (string) - Optional - A valid redirect URI specified in the settings of your application. Mandatory if `grant_type=authorization_code`.
- **client_id** (string) - Required - The unique identifier of your Open API application.
- **client_secret** (string) - Required - The secret key assigned to your Open API application.

### Request Example
```
curl -X GET 'https://openapi.ctrader.com/apps/token?grant_type=authorization_code&code=0ssdgds98as9_QSF56FVC_22dfdf&redirect_uri=https://spotware.com&client_id=5430012&client_secret=012sds23dlkjQsd' -H 'Accept: application/json' -H 'Content-Type: application/json'
```

### Response
#### Success Response (200)
- **accessToken** (string) - The access token that your application will use to authenticate the messages sent to cTrader Open API.
- **tokenType** (string) - The type of the access token (`"bearer"` should be the value of this key as the REST standard is used to make the request).
- **expiresIn** (integer) - The number of seconds that must pass before the access token expires (by default, the value equals `2628000`).
- **refreshToken** (string) - The refresh token that must be used for renewing the access token once it expires. The refresh token has no expiry time itself.
- **errorCode** (string/null) - The error code that describes why a request was unsuccessful. For a successful request, the value should be `null`.
- **description** (string/null) - The description of an error that has occurred during an unsuccessful request. For a successful request, the value should be `null`.

#### Response Example
```
{
    "accessToken":"mos8Bw3D4EG0fRPd4Eqq0JxaFT4zjd8e4YijNezh_ag",
    "tokenType":"bearer",
    "expiresIn":2628000,
    "refreshToken":"VCuafFhy81AFZjsWkbuEzdOhhRj5YTWz8fWUwHam7KM",
    "errorCode":null,
    "description":null
}
```
```

--------------------------------

### Subscribe to spot events in Python

Source: https://help.ctrader.com/open-api/symbol-rate-conversion?q=

Subscribes to ProtoOASpotEvent for a single symbol. Must be called for every light symbol in the conversion chain.

```python
def sendProtoOASubscribeSpotsReq(symbolId, subscribeToSpotTimestamp = False, clientMsgId = None):
    request = ProtoOASubscribeSpotsReq()
    request.ctidTraderAccountId = currentAccountId
    request.symbolId.append(int(symbolId))
    request.subscribeToSpotTimestamp = subscribeToSpotTimestamp if type(subscribeToSpotTimestamp) is bool else bool(subscribeToSpotTimestamp)
    deferred = client.send(request, clientMsgId = clientMsgId)
    deferred.addErrback(onError)
```

--------------------------------

### ConnectWebSocket method implementation

Source: https://help.ctrader.com/open-api/connection

Shows the internal implementation of the WebSocket connection method called by OpenClient.Connect(). It builds a wss:// URL, configures the WebsocketClient, and subscribes to message and disconnection events.

```csharp
private async Task ConnectWebScoket()
{
    DefaultInterpolatedStringHandler defaultInterpolatedStringHandler = new DefaultInterpolatedStringHandler(7, 2);
    defaultInterpolatedStringHandler.AppendLiteral("wss://");
    defaultInterpolatedStringHandler.AppendFormatted(Host);
    defaultInterpolatedStringHandler.AppendLiteral(":");
    defaultInterpolatedStringHandler.AppendFormatted(Port);
    Uri url = new Uri(defaultInterpolatedStringHandler.ToStringAndClear());
    _websocketClient = new WebsocketClient(url, () => new ClientWebSocket())
    {
        IsTextMessageConversionEnabled = false,
        ReconnectTimeout = null,
        IsReconnectionEnabled = false,
        ErrorReconnectTimeout = null
    };
    _webSocketMessageReceivedDisposable = _websocketClient.MessageReceived.Select((ResponseMessage msg) => ProtoMessage.Parser.ParseFrom(msg.Binary)).Subscribe(new Action<ProtoMessage>(OnNext));
    _webSocketDisconnectionHappenedDisposable = _websocketClient.DisconnectionHappened.Subscribe(new Action<DisconnectionInfo>(OnWebSocketDisconnectionHappened));
    await _websocketClient.StartOrFail();
}
```

--------------------------------

### JSON message example

Source: https://help.ctrader.com/open-api/protocol-buffers-json

Example of a JSON message structure used for serialisation in cTrader Open API. Shows string, integer, nested object, and list values. JSON is used when connecting to port 5036.

```json
{
    "clientMsgId": "cm_id_2",
    "payloadType": 2100,
    "payload": {
        "keyOne": [1, 2, 10,],
        "keyTwo": "valueTwo",
    }
}
```

--------------------------------

### JSON message example

Source: https://help.ctrader.com/open-api/protocol-buffers-json?q=

Example of a JSON message structure used for serialisation and deserialisation with the cTrader backend. It shows key-value pairs where keys are strings and values can be strings, integers, lists, or nested objects. The payloadType value 2100 is an integer, and the payload contains a nested object with a list of integers.

```json
{
    "clientMsgId": "cm_id_2",
    "payloadType": 2100,
    "payload": {
        "keyOne": [1, 2, 10,],
        "keyTwo": "valueTwo",
    }
}

```

--------------------------------

### ProtoOAGetAccountListByAccessTokenReq

Source: https://help.ctrader.com/open-api/messages?q=

Request message for getting the list of granted trader's accounts for the access token.

```APIDOC
## ProtoOAGetAccountListByAccessTokenReq

### Description
Request for getting the list of granted trader's account for the access token.

### Fields

| Field | Type | Label | Description |
|---|---|---|---|
| payloadType | ProtoOAPayloadType | Optional |  |
| accessToken | string | Required | The Access Token issued for providing access to the Trader's Account. |

```

--------------------------------

### Subscribe to ProtoOASpotEvent for conversion chain symbols (C#)

Source: https://help.ctrader.com/open-api/symbol-rate-conversion

Subscribe to spot events for all symbols in the conversion chain. The first method sends ProtoOASubscribeSpotsReq with the given symbol IDs and waits for ProtoOASubscribeSpotsRes. The second line subscribes to ProtoOASpotEvent and routes it to the OnSpotEvent handler, which updates bid/ask properties using GetPriceFromRelative.

```csharp
public Task<ProtoOASubscribeSpotsRes> SubscribeToSpots(long accountId, bool isLive, params long[] symbolIds)
{
    var client = GetClient(isLive);

    var taskCompletionSource = new TaskCompletionSource<ProtoOASubscribeSpotsRes>();

    IDisposable disposable = null;

    disposable = client.OfType<ProtoOASubscribeSpotsRes>().Where(response => response.CtidTraderAccountId == accountId).Subscribe(response =>
    {
        taskCompletionSource.SetResult(response);

        disposable?.Dispose();
    });

    var requestMessage = new ProtoOASubscribeSpotsReq
    {
        CtidTraderAccountId = accountId,
    };

    requestMessage.SymbolId.AddRange(symbolIds);

    EnqueueMessage(requestMessage, ProtoOAPayloadType.ProtoOaSubscribeSpotsReq, client);

    return taskCompletionSource.Task;
}
```

```csharp
client.OfType<ProtoOASpotEvent>().Subscribe(OnSpotEvent);
```

--------------------------------

### ProtoOAExpectedMarginReq

Source: https://help.ctrader.com/open-api/messages?q=

Request message for getting the margin estimate according to leverage profiles. Can be used before sending a new order request.

```APIDOC
## ProtoOAExpectedMarginReq

### Description
Request for getting the margin estimate according to leverage profiles. Can be used before sending a new order request. This doesn't consider ACCORDING_TO_GSL margin calculation type, as this calculation is trivial: usedMargin = (VWAP price of the position - GSL price) * volume * Quote2Deposit.

### Fields

| Field | Type | Label | Description |
|---|---|---|---|
| payloadType | ProtoOAPayloadType | Optional |  |
| ctidTraderAccountId | int64 | Required | Unique identifier of the trader's account. Used to match responses to trader's accounts. |
| symbolId | int64 | Required | Unique identifier of the Symbol in cTrader platform. |
| volume | RepeatedField<int64> | Repeated | Volume represented in 0.01 of a unit (e.g. 1000 in protocol means 10.00 units). |

```

--------------------------------

### C#: Subscribe to spot events

Source: https://help.ctrader.com/open-api/symbol-rate-conversion?q=

C# method that subscribes to ProtoOASubscribeSpotsRes for the given symbol IDs and returns the response.

```csharp
public Task<ProtoOASubscribeSpotsRes> SubscribeToSpots(long accountId, bool isLive, params long[] symbolIds)
{
    var client = GetClient(isLive);

    var taskCompletionSource = new TaskCompletionSource<ProtoOASubscribeSpotsRes>();

    IDisposable disposable = null;

    disposable = client.OfType<ProtoOASubscribeSpotsRes>().Where(response => response.CtidTraderAccountId == accountId).Subscribe(response =>
    {
        taskCompletionSource.SetResult(response);

        disposable?.Dispose();
    });

    var requestMessage = new ProtoOASubscribeSpotsReq
    {
        CtidTraderAccountId = accountId,
    };

    requestMessage.SymbolId.AddRange(symbolIds);

    EnqueueMessage(requestMessage, ProtoOAPayloadType.ProtoOaSubscribeSpotsReq, client);

    return taskCompletionSource.Task;
}
```

--------------------------------

### GET https://id.ctrader.com/my/settings/openapi/grantingaccess/

Source: https://help.ctrader.com/open-api/account-authentication

Redirect users to this URI to obtain an authorization code for a specific cTID. The user must permit the application to access their trading accounts.

```APIDOC
## [GET] https://id.ctrader.com/my/settings/openapi/grantingaccess/

### Description
Redirects the user to the cTrader ID authorization page to grant access to trading accounts. After the user allows access, they are redirected to the specified redirect_uri with an authorization code as a query parameter.

### Method
GET

### Endpoint
https://id.ctrader.com/my/settings/openapi/grantingaccess/

### Parameters
#### Query Parameters
- **client_id** (string) - Required - The unique identifier of your Open API application.
- **redirect_uri** (string) - Required - A valid redirect URI specified in the settings of your application.
- **scope** (string) - Required - The scope of permissions. Accepted values: `accounts` (view only) or `trading` (full access).
- **product** (string) - Optional - If set to `web`, the authorization screen lacks header and footer for better mobile display.

### Request Example
https://id.ctrader.com/my/settings/openapi/grantingaccess/?client_id={clientId}&redirect_uri={your_redirectURI}&scope={scope}&product=web

### Response
#### Success Response (302 Redirect)
Redirects to the specified redirect_uri with the authorization code as a query parameter, e.g., `https://my-redirect-uri.com/?code=123ASDASffdg_as234_GCllkoq14adRB7_tvN`.

#### Response Example
https://my-redirect-uri.com/?code=123ASDASffdg_as234_GCllkoq14adRB7_tvN

### Notes
- The authorization code must be exchanged with an access token before it expires.
- If additional accounts are created later, the user must be redirected again to authorize them.
- When using WebView with Google sign-in, ensure the `user-agent` is set to: `'user-agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36'`.
```

--------------------------------

### C#: OnNext callback for ProtoMessage

Source: https://help.ctrader.com/open-api/sending-receiving-protobuf

Processes a received ProtoMessage by iterating over observers, getting the message from MessageFactory, and forwarding it to observers. Handles exceptions by creating an ObserverException.

```csharp
private void OnNext(ProtoMessage protoMessage)
{
    foreach (KeyValuePair<int, IObserver<IMessage>> observer2 in _observers)
    {
        observer2.Deconstruct(out var _, out var value);
        IObserver<IMessage> observer = value;
        try
        {
            IMessage message = MessageFactory.GetMessage(protoMessage);
            if (protoMessage.HasClientMsgId || message == null)
            {
                observer.OnNext(protoMessage);
            }

            if (message != null)
            {
                observer.OnNext(message);
            }
        }
        catch (Exception innerException)
        {
            ObserverException exception = new ObserverException(innerException, observer);
            OnError(exception);
        }
    }
}

```

--------------------------------

### Connect WebSocket and subscribe to messages in C#

Source: https://help.ctrader.com/open-api/sending-receiving-protobuf?q=

Establishes a WebSocket connection to the cTrader backend, configures the client with reconnection disabled, and subscribes to message and disconnection events. Parses incoming binary messages into ProtoMessage and passes them to OnNext.

```csharp
private async Task ConnectWebSocket()
{
    DefaultInterpolatedStringHandler defaultInterpolatedStringHandler = new DefaultInterpolatedStringHandler(7, 2);
    defaultInterpolatedStringHandler.AppendLiteral("wss://");
    defaultInterpolatedStringHandler.AppendFormatted(Host);
    defaultInterpolatedStringHandler.AppendLiteral(":");
    defaultInterpolatedStringHandler.AppendFormatted(Port);
    Uri url = new Uri(defaultInterpolatedStringHandler.ToStringAndClear());
    _websocketClient = new WebsocketClient(url, () => new ClientWebSocket())
    {
        IsTextMessageConversionEnabled = false,
        ReconnectTimeout = null,
        IsReconnectionEnabled = false,
        ErrorReconnectTimeout = null
    };
    _webSocketMessageReceivedDisposable = _websocketClient.MessageReceived.Select((ResponseMessage msg) => ProtoMessage.Parser.ParseFrom(msg.Binary)).Subscribe(new Action<ProtoMessage>(OnNext));
    _webSocketDisconnectionHappenedDisposable = _websocketClient.DisconnectionHappened.Subscribe(new Action<DisconnectionInfo>(OnWebSocketDisconnectionHappened));
    await _websocketClient.StartOrFail();
}
```

--------------------------------

### Connect via TCP using Python Client

Source: https://help.ctrader.com/open-api/connection

Initializes the Python Open API client, which automatically attempts to establish a TCP connection when it is created.

```python
client = Client("live1.p.ctrader.com", 5035, TcpProtocol)
```

--------------------------------

### Parse and forward received data in Python

Source: https://help.ctrader.com/open-api/sending-receiving-protobuf?q=

Handles incoming raw data by parsing it into a ProtoMessage, checking for a heartbeat event, and forwarding the message to the factory. Returns the original data.

```python
def stringReceived(self, data):
    msg = ProtoMessage()
    msg.ParseFromString(data)

    if msg.payloadType == ProtoHeartbeatEvent().payloadType:
        self.heartbeat()
    self.factory.received(msg)
    return data
```

--------------------------------

### C# classes for P&L messages

Source: https://help.ctrader.com/open-api/profit-loss-calculation

Example C# classes for serializing and deserializing P&L messages when using Protobuf. Includes PositionUnrealizedPnL, GetPositionUnrealizedPnLReq, and GetPositionUnrealizedPnLRes with payload types 2187 and 2188.

```C#
public abstract class OpenAPIModelMessageBase { }

public class PositionUnrealizedPnL : OpenAPIModelMessageBase
{
    public PositionUnrealizedPnL() { }
    public PositionUnrealizedPnL(int positionId, int grossUnrealizedPnL, int netUnrealizedPnL) 
    {
        this.PositionId = positionId;
        this.GrossUnrealizedPnL = grossUnrealizedPnL;
        this.NetUnrealizedPnL = netUnrealizedPnL;
    }

    public int PositionId { get; set; }
    public int GrossUnrealizedPnL { get; set; }
    public int NetUnrealizedPnL { get; set; }
}

public class GetPositionUnrealizedPnLReq : OpenAPIMessageBase
{
    public GetPositionUnrealizedPnLReq() { }
    public GetPositionUnrealizedPnLReq(int ctidTraderAccountId)
    {
        this.Payload = new GetPositionUnrealizedPnLReqPayload(ctidTraderAccountId);
        this.ClientMsgId = Guid.NewGuid().ToString();
    }

    public override int PayloadType => 2187;
    public GetPositionUnrealizedPnLReqPayload? Payload { get; set; }
}

public class GetPositionUnrealizedPnLReqPayload : OpenAPIMessagePayloadBase
{
    public GetPositionUnrealizedPnLReqPayload() { }
    public GetPositionUnrealizedPnLReqPayload(int ctidTraderAccountId)
    {
        this.CtidTraderAccountId = ctidTraderAccountId;
    }

    public int CtidTraderAccountId { get; set; } = 0;

}

public class GetPositionUnrealizedPnLRes : OpenAPIMessageBase 
{
    public GetPositionUnrealizedPnLRes() { }
    public GetPositionUnrealizedPnLRes(int ctidTraderAccountId, int moneyDigits, List<PositionUnrealizedPnL> positionUnrealizedPnL)
    {
        this.Payload = new GetPositionUnrealizedPnLResPayload(ctidTraderAccountId, moneyDigits, positionUnrealizedPnL);
        this.ClientMsgId = Guid.NewGuid().ToString();
    }

    public override int PayloadType => 2188;
    public GetPositionUnrealizedPnLResPayload? Payload { get; set; }

}

public class GetPositionUnrealizedPnLResPayload : OpenAPIMessagePayloadBase
{
    public GetPositionUnrealizedPnLResPayload() { }
    public GetPositionUnrealizedPnLResPayload(int ctidTraderAccountId, int moneyDigits, List<PositionUnrealizedPnL> positionUnrealizedPnL)
    {
        this.CtidTraderAccountId = ctidTraderAccountId;
        this.MoneyDigits = moneyDigits;
        this.PositionUnrealizedPnL = positionUnrealizedPnL;
    }

    public int CtidTraderAccountId { get; set; } = 0;
    public int MoneyDigits { get; set; } = 0;
    public List<PositionUnrealizedPnL> PositionUnrealizedPnL { get; set; } = new List<PositionUnrealizedPnL>();
}
```
Tokens:
Raw