OpenAPI Python

https://github.com/spotware/openapipy
Admin
A Python package for asynchronously interacting with the cTrader Open API using Twisted and...
Tokens:9,672
Snippets:32
Trust Score:8.7
License:MIT
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install Klein Web Framework

Source: https://github.com/spotware/openapipy/blob/main/samples/KleinWebAppSample/README.md

Installs the Klein web framework, a dependency for running the sample application. This command should be executed in your terminal.

```bash
pip install klein
```

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

### Start Spotware Client Service and Run Reactor

Source: https://github.com/spotware/openapipy/blob/main/samples/jupyter/main.ipynb

Initiates the client service and starts the Twisted reactor event loop. This is the final step to run the asynchronous client operations.

```python
# Starting the client service
client.startService()
# Run Twisted reactor, we imported it earlier
reactor.run()
```

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

### Install ctrader-open-api

Source: https://github.com/spotware/openapipy/blob/main/samples/jupyter/main.ipynb

Installs the necessary Python package 'ctrader-open-api' using pip. This is the first step to begin using the library.

```python
!pip install ctrader-open-api
```

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

### Initialize Auth Class

Source: https://github.com/spotware/openapipy/blob/main/docs/authentication.md

Instantiates the Auth class with your application's unique identifier, secret, and the redirect URI.

```python
from ctrader_open_api import Auth

auth = Auth("Your App ID", "Your App Secret", "Your App redirect URI")
```

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

### Install ctrader-open-api Package

Source: https://github.com/spotware/openapipy/blob/main/README.md

Installs the necessary Python package for interacting with the cTrader Open API using pip.

```bash
pip install ctrader-open-api
```

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

### Spotware Client Callback Setup and Authentication

Source: https://github.com/spotware/openapipy/blob/main/samples/jupyter/main.ipynb

Defines and sets up callback functions for client connection, disconnection, message reception, and authentication responses. It handles application authentication requests and processes incoming messages, filtering out specific event types.

```python
def applicationAuthResponseCallback(result):
    print("\nApplication authenticated")
    request = ProtoOAAccountAuthReq()
    request.ctidTraderAccountId = credentials["AccountId"]
    request.accessToken = credentials["AccessToken"]
    deferred = client.send(request)
    deferred.addCallbacks(accountAuthResponseCallback, onError)

def onError(client, failure): # Call back for errors
    print("\nMessage Error: ", failure)

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

def onMessageReceived(client, message): # Callback for receiving all messages
    if message.payloadType in [ProtoHeartbeatEvent().payloadType, ProtoOAAccountAuthRes().payloadType, ProtoOAApplicationAuthRes().payloadType, ProtoOASymbolsListRes().payloadType, ProtoOAGetTrendbarsRes().payloadType]:
        return
    print("\nMessage received: \n", Protobuf.extract(message))
    
def connected(client): # Callback for client connection
    print("\nConnected")
    request = ProtoOAApplicationAuthReq()
    request.clientId = credentials["ClientId"]
    request.clientSecret = credentials["Secret"]
    deferred = client.send(request)
    deferred.addCallbacks(applicationAuthResponseCallback, onError)
    
# Setting optional client callbacks
client.setConnectedCallback(connected)
client.setDisconnectedCallback(disconnected)
client.setMessageReceivedCallback(onMessageReceived)
```

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

### Get Access Token

Source: https://github.com/spotware/openapipy/blob/main/docs/authentication.md

Exchanges an authorization code, received after user authentication and redirection, for an access token and refresh token.

```python
# This method uses EndPoints.TOKEN_URI as a base URI to get token
# you can change it by passing another URI via optional baseUri parameter
token = auth.getToken("auth_code")
```

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

### Get Authentication URI

Source: https://github.com/spotware/openapipy/blob/main/docs/authentication.md

Retrieves the URL for the cTrader Open API authentication web page. Users are redirected here to grant your application access.

```python
authUri = auth.getAuthUri()
```

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

### Auth Class refreshToken Method Details

Source: https://github.com/spotware/openapipy/blob/main/docs/authentication.md

Explains the refreshToken method, which allows for obtaining a new access token using a refresh token. It details the input and the structure of the returned token object.

```APIDOC
Auth.refreshToken(refresh_token: str, baseUri: str = None)
  - Description: Obtains a new access token using a valid refresh token.
  - Parameters:
    - refresh_token: The refresh token previously received.
    - baseUri (str, optional): The base URI for the token refresh endpoint. Defaults to EndPoints.TOKEN_URI.
  - Returns: A JSON object containing new token details, similar to the getToken method's return structure (accessToken, refreshToken, expiresIn, tokenType, errorCode, description).
```

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

### Auth Class getAuthUri Method Details

Source: https://github.com/spotware/openapipy/blob/main/docs/authentication.md

Provides details on the getAuthUri method, including its optional parameters for customizing the authentication scope and base URI.

```APIDOC
Auth.getAuthUri()
  - Description: Generates the URL for the cTrader Open API authentication page.
  - Parameters:
    - scope (str, optional): Defines the level of access requested. Defaults to 'trading' (full access). Use 'accounts' for read-only access to trading account data.
    - baseUri (str, optional): The base URI for the authentication endpoint. Defaults to EndPoints.AUTH_URI ('https://connect.spotware.com/apps/auth').
  - Returns: A string representing the full authentication URI.
```

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

### Python cTrader Open API Client Usage

Source: https://github.com/spotware/openapipy/blob/main/README.md

Demonstrates the basic setup and usage of the OpenApiPy client to connect to cTrader, send authentication requests, and handle incoming messages asynchronously using Twisted.

```python
from ctrader_open_api import Client, Protobuf, TcpProtocol, Auth, EndPoints
from ctrader_open_api.messages.OpenApiCommonMessages_pb2 import *
from ctrader_open_api.messages.OpenApiMessages_pb2 import *
from ctrader_open_api.messages.OpenApiModelMessages_pb2 import *
from twisted.internet import reactor

hostType = input("Host (Live/Demo): ")
host = EndPoints.PROTOBUF_LIVE_HOST if hostType.lower() == "live" else EndPoints.PROTOBUF_DEMO_HOST
client = Client(host, EndPoints.PROTOBUF_PORT, TcpProtocol)

def onError(failure):
    print("Message Error: ", failure)

def connected(client):
    print("\nConnected")
    request = ProtoOAApplicationAuthReq()
    request.clientId = "Your application Client ID"
    request.clientSecret = "Your application Client secret"
    deferred = client.send(request)
    deferred.addErrback(onError)

def disconnected(client, reason):
    print("\nDisconnected: ", reason)

def onMessageReceived(client, message):
    print("Message received: \n", Protobuf.extract(message))

client.setConnectedCallback(connected)
client.setDisconnectedCallback(disconnected)
client.setMessageReceivedCallback(onMessageReceived)

client.startService()
reactor.run()
```

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

### Auth Class getToken Method Details

Source: https://github.com/spotware/openapipy/blob/main/docs/authentication.md

Details the getToken method, which is used to obtain OAuth tokens by providing an authorization code. It outlines the structure of the returned token object.

```APIDOC
Auth.getToken(authorization_code: str, baseUri: str = None)
  - Description: Requests an access token and refresh token from the API using the provided authorization code.
  - Parameters:
    - authorization_code: The code received from the redirect URI after user authentication.
    - baseUri (str, optional): The base URI for the token endpoint. Defaults to EndPoints.TOKEN_URI.
  - Returns: A JSON object containing token details:
    - accessToken (str): The token used for authenticating API requests.
    - refreshToken (str): The token used to obtain new access tokens after expiry.
    - expiresIn (int): The token's validity period in seconds.
    - tokenType (str): The type of token (e.g., 'bearer').
    - errorCode (str, optional): An error code if the request failed.
    - description (str, optional): A description of the error if the request failed.
```

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

### Refresh Access Token

Source: https://github.com/spotware/openapipy/blob/main/docs/authentication.md

Renews an expired access token using a previously obtained refresh token, ensuring continued API access.

```python
# This method uses EndPoints.TOKEN_URI as a base URI to refresh token
# you can change it by passing another URI via optional baseUri parameter
newToken = auth.refreshToken("refresh_Token")
```

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

### Create Spotware API Client Instance

Source: https://github.com/spotware/openapipy/blob/main/docs/client.md

Demonstrates how to instantiate the `Client` class from the `ctrader_open_api` library, specifying the API endpoint and protocol. This client handles connection complexities.

```Python
from ctrader_open_api import Client, Protobuf, TcpProtocol, Auth, EndPoints

client = Client(EndPoints.PROTOBUF_DEMO_HOST, EndPoints.PROTOBUF_PORT, TcpProtocol)
```

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

### Prepare Proto Message for API Request

Source: https://github.com/spotware/openapipy/blob/main/docs/client.md

Shows how to import necessary protobuf message types and create a `ProtoOAApplicationAuthReq` message, populating its fields like `clientId` and `clientSecret`.

```Python
# Import all message types
from ctrader_open_api.messages.OpenApiCommonMessages_pb2 import *
from ctrader_open_api.messages.OpenApiMessages_pb2 import *
from ctrader_open_api.messages.OpenApiModelMessages_pb2 import *

# ProtoOAApplicationAuthReq message
applicationAuthReq = ProtoOAApplicationAuthReq()
applicationAuthReq.clientId = "Your App Client ID"
applicationAuthReq.clientSecret = "Your App Client secret"
```

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

### Send Proto Message and Handle Response

Source: https://github.com/spotware/openapipy/blob/main/docs/client.md

Illustrates sending a prepared proto message using the client's `send` method, which returns a Twisted deferred. Callbacks are added to handle successful responses or errors.

```Python
deferred = client.send(applicationAuthReq)

def onProtoOAApplicationAuthRes(result):
	print(result)

def onError(failure):
	print(failure)

deferred.addCallbacks(onProtoOAApplicationAuthRes, onError)
```

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

### Connect and Authenticate with cTrader Open API

Source: https://github.com/spotware/openapipy/blob/main/docs/index.md

Demonstrates how to establish an asynchronous connection to the cTrader Open API, handle connection events, and send an application authentication request. It utilizes the `ctrader_open_api` library and Twisted for network operations.

```python
from ctrader_open_api import Client, Protobuf, TcpProtocol, Auth, EndPoints
from ctrader_open_api.messages.OpenApiCommonMessages_pb2 import *
from ctrader_open_api.messages.OpenApiMessages_pb2 import *
from ctrader_open_api.messages.OpenApiModelMessages_pb2 import *
from twisted.internet import reactor

hostType = input("Host (Live/Demo): ")
host = EndPoints.PROTOBUF_LIVE_HOST if hostType.lower() == "live" else EndPoints.PROTOमपुर_DEMO_HOST
client = Client(host, EndPoints.PROTOBUF_PORT, TcpProtocol)

def onError(failure): # Call back for errors
    print("Message Error: ", failure)

def connected(client):
    print("\nConnected")
    # Now we send a ProtoOAApplicationAuthReq
    request = ProtoOAApplicationAuthReq()
    request.clientId = "Your application Client ID"
    request.clientSecret = "Your application Client secret"
    # Client send method returns a Twisted deferred
    deferred = client.send(request)
    # You can use the returned Twisted deferred to attach callbacks
    # for getting message response or error backs for getting error if something went wrong
    # deferred.addCallbacks(onProtoOAApplicationAuthRes, onError)
    deferred.addErrback(onError)

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

def onMessageReceived(client, message): # Callback for receiving all messages
    print("Message received: \n", Protobuf.extract(message))

# Setting optional client callbacks
client.setConnectedCallback(connected)
client.setDisconnectedCallback(disconnected)
client.setMessageReceivedCallback(onMessageReceived)

# Starting the client service
client.startService()

# Run Twisted reactor
reactor.run()
```

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

### Client Connection Callbacks

Source: https://github.com/spotware/openapipy/blob/main/docs/client.md

Details how to set up optional callbacks for the client to monitor connection status. These include `setConnectedCallback`, `setDisconnectedCallback`, and `setMessageReceivedCallback`.

```APIDOC
Client Methods:

setConnectedCallback(callback)
  - Sets a callback function to be executed when the client successfully connects.
  - Parameters:
    - callback: A function that accepts the client instance as an argument.

setDisconnectedCallback(callback)
  - Sets a callback function to be executed when the client disconnects.
  - Parameters:
    - callback: A function that accepts the client instance and a reason for disconnection.

setMessageReceivedCallback(callback)
  - Sets a callback function to be executed for every message received by the client.
  - Parameters:
    - callback: A function that accepts the client instance and the received message.
```

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

### Initialize API Client

Source: https://github.com/spotware/openapipy/blob/main/samples/jupyter/main.ipynb

Initializes the cTrader Open API client. It selects the appropriate host endpoint (live or demo) based on the 'HostType' specified in the credentials file and uses TCP protocol.

```python
host = EndPoints.PROTOBUF_LIVE_HOST if credentials["HostType"].lower() == "live" else EndPoints.PROTOBUF_DEMO_HOST
client = Client(host, EndPoints.PROTOBUF_PORT, TcpProtocol)
```

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

### Theme Switcher and Giscus Integration

Source: https://github.com/spotware/openapipy/blob/main/overrides/main.html

This script listens for changes in the documentation's color scheme. When a theme change is detected, it updates the Giscus comment section to match the new theme, ensuring a consistent user experience.

```javascript
var palette = __md_get("__palette")
if (palette && typeof palette.color === "object") {
  if (palette.color.scheme === "slate") {
    var giscus = document.querySelector("script[src*=giscus]")
    giscus.setAttribute("data-theme", "dark")
  }
}
/* Register event handlers after documented loaded */
document.addEventListener("DOMContentLoaded", function () {
  var ref = document.querySelector("[data-md-component=palette]")
  ref.addEventListener("change", function () {
    var palette = __md_get("__palette")
    if (palette && typeof palette.color === "object") {
      var theme = palette.color.scheme === "slate" ? "dark_dimmed" : "light"
      /* Instruct Giscus to change theme */
      var frame = document.querySelector(".giscus-frame")
      frame.contentWindow.postMessage(
        {
          giscus: {
            setConfig: {
              theme: theme
            }
          }
        },
        "https://giscus.app"
      )
    }
  })
})
```

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

### Initialize Data Storage

Source: https://github.com/spotware/openapipy/blob/main/samples/jupyter/main.ipynb

Declares an empty list to store the fetched daily bars data. This list will be populated by the callback function after data retrieval.

```python
dailyBars = []
```

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

### Load Credentials

Source: https://github.com/spotware/openapipy/blob/main/samples/jupyter/main.ipynb

Loads API application credentials and access tokens from a local 'credentials-dev.json' file. Ensure this file is populated with valid credentials before execution.

```python
credentialsFile = open("credentials-dev.json")
credentials = json.load(credentialsFile)
```

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

### cTrader Open API Client and Message Handling

Source: https://github.com/spotware/openapipy/blob/main/README.md

Details the core components and methods for interacting with the cTrader Open API using the OpenApiPy library. This includes client initialization, connection management, sending Protobuf messages, and handling responses via Twisted Deferreds.

```APIDOC
Client Initialization:
  Client(host: str, port: int, protocol: type)
    - Initializes the API client.
    - Parameters:
      - host: The API server hostname (e.g., EndPoints.PROTOBUF_LIVE_HOST).
      - port: The API server port (e.g., EndPoints.PROTOBUF_PORT).
      - protocol: The communication protocol class (e.g., TcpProtocol).

Connection Callbacks:
  setConnectedCallback(callback: callable)
    - Registers a callback function to be executed upon successful connection.
    - The callback receives the client instance as an argument.
  setDisconnectedCallback(callback: callable)
    - Registers a callback function to be executed upon disconnection.
    - The callback receives the client instance and a reason for disconnection.
  setMessageReceivedCallback(callback: callable)
    - Registers a callback function to process all incoming messages.
    - The callback receives the client instance and the raw message.

Sending Requests:
  client.send(message: ProtobufMessage) -> Deferred
    - Sends a Protobuf message to the cTrader API server.
    - Returns a Twisted Deferred object for asynchronous handling of the response.
    - Example Message Types:
      - ProtoOAApplicationAuthReq: For application authentication.
      - ProtoOALightWeightAccountsReq: Request for light-weight account information.
    - Related Methods:
      - deferred.addCallbacks(callback, errback): Attaches success and error handlers to the Deferred.
      - deferred.addErrback(errback): Attaches an error handler.

Message Extraction:
  Protobuf.extract(message: bytes) -> dict
    - Parses raw Protobuf message bytes into a Python dictionary.
    - Used within the message received callback to interpret data.

API Endpoints:
  Endpoints.PROTOBUF_LIVE_HOST: str
    - Hostname for the live cTrader API server.
  Endpoints.PROTOBUF_DEMO_HOST: str
    - Hostname for the demo cTrader API server.
  Endpoints.PROTOBUF_PORT: int
    - Default port for Protobuf communication.

Twisted Reactor:
  reactor.run()
    - Starts the Twisted event loop, essential for asynchronous operations.
    - Must be called after setting up the client and its callbacks.
```

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

### Import Libraries and Types

Source: https://github.com/spotware/openapipy/blob/main/samples/jupyter/main.ipynb

Imports all required modules and types from the 'ctrader-open-api' library, along with Twisted for asynchronous operations, JSON for configuration, and datetime/calendar for time handling.

```python
from ctrader_open_api import Client, Protobuf, TcpProtocol, Auth, EndPoints
from ctrader_open_api.messages.OpenApiCommonMessages_pb2 import *
from ctrader_open_api.messages.OpenApiMessages_pb2 import *
from ctrader_open_api.messages.OpenApiModelMessages_pb2 import *
from twisted.internet import reactor
import json
import datetime
import calendar
```

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

### Handle Account Authentication Response

Source: https://github.com/spotware/openapipy/blob/main/samples/jupyter/main.ipynb

Callback function for account authentication. Upon successful authentication, it requests the list of available symbols for the trading account.

```python
def accountAuthResponseCallback(result):
    print("\nAccount authenticated")
    request = ProtoOASymbolsListReq()
    request.ctidTraderAccountId = credentials["AccountId"]
    request.includeArchivedSymbols = False
    deferred = client.send(request)
    deferred.addCallbacks(symbolsResponseCallback, onError)
```

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

### Python Scikit-learn Logistic Regression Model Training

Source: https://github.com/spotware/openapipy/blob/main/samples/jupyter/main.ipynb

Trains a Logistic Regression model using prepared data. It splits the data into training and testing sets, fits the model, makes predictions, and prints the accuracy score.

```python
from sklearn.linear_model import LogisticRegression
from sklearn.model_selection import train_test_split
from sklearn.metrics import accuracy_score

model = LogisticRegression()

x = df.loc[:, ["Open", "High", "Low", "Close", "Volume"]]
y = df.Labels

x_train, x_test, y_train, y_test = train_test_split(x, y, train_size=0.7)

model.fit(x_train, y_train)

y_pred= model.predict(x_test)

print("Our Model accuracy score is: ", accuracy_score(y_test, y_pred))
```

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

### Handle Trendbars Response

Source: https://github.com/spotware/openapipy/blob/main/samples/jupyter/main.ipynb

Callback function executed upon receiving trendbar data. It extracts, transforms, stores the data, and stops the Twisted reactor. Includes basic logging.

```python
def trendbarsResponseCallback(result):
    print("\nTrendbars received")
    trendbars = Protobuf.extract(result)
    barsData = list(map(transformTrendbar, trendbars.trendbar))
    global dailyBars
    dailyBars.clear()
    dailyBars.extend(barsData)
    print("\ndailyBars length:", len(dailyBars))
    print("\nStopping reactor...")
    reactor.stop()
```

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

### Handle Symbols Response

Source: https://github.com/spotware/openapipy/blob/main/samples/jupyter/main.ipynb

Callback function for symbol list responses. It filters symbols to find the requested one, then requests trendbar data for that symbol and account.

```python
def symbolsResponseCallback(result):
    print("\nSymbols received")
    symbols = Protobuf.extract(result)
    global symbolName
    symbolsFilterResult = list(filter(lambda symbol: symbol.symbolName == symbolName, symbols.symbol))
    if len(symbolsFilterResult) == 0:
        raise Exception(f"There is symbol that matches to your defined symbol name: {symbolName}")
    elif len(symbolsFilterResult) > 1:
        raise Exception(f"More than one symbol matched with your defined symbol name: {symbolName}, match result: {symbolsFilterResult}")
    symbol = symbolsFilterResult[0]
    request = ProtoOAGetTrendbarsReq()
    request.symbolId = symbol.symbolId
    request.ctidTraderAccountId = credentials["AccountId"]
    request.period = ProtoOATrendbarPeriod.D1
    # We set the from/to time stamps to 50 weeks, you can load more data by sending multiple requests
    # Please check the ProtoOAGetTrendbarsReq documentation for more detail
    request.fromTimestamp = int(calendar.timegm((datetime.datetime.utcnow() - datetime.timedelta(weeks=50)).utctimetuple())) * 1000
    request.toTimestamp = int(calendar.timegm(datetime.datetime.utcnow().utctimetuple())) * 1000
    deferred = client.send(request)
    deferred.addCallbacks(trendbarsResponseCallback, onError)
```

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

### Python Pandas DataFrame Transformation

Source: https://github.com/spotware/openapipy/blob/main/samples/jupyter/main.ipynb

Converts raw trading bar data into a Pandas DataFrame, assigning appropriate column names and ensuring all price and volume columns are numeric types for further analysis.

```python
import pandas as pd
import numpy as np

df = pd.DataFrame(np.array(dailyBars),
                   columns=['Time', 'Open', 'High', 'Low', 'Close', 'Volume'])
df["Open"] = pd.to_numeric(df["Open"])
df["High"] = pd.to_numeric(df["High"])
df["Low"] = pd.to_numeric(df["Low"])
df["Close"] = pd.to_numeric(df["Close"])
df["Volume"] = pd.to_numeric(df["Volume"])
```

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

### Define Symbol Name

Source: https://github.com/spotware/openapipy/blob/main/samples/jupyter/main.ipynb

Sets the trading symbol for which to retrieve data. This symbol name must exist within the user's cTrader trading account.

```python
symbolName = "EURUSD"
```

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

### Python Pandas ML Label Creation

Source: https://github.com/spotware/openapipy/blob/main/samples/jupyter/main.ipynb

Creates a 'Labels' column indicating if the closing price was higher than the opening price for each bar. It then shifts these labels to predict the next bar's outcome and removes the last row to maintain data integrity.

```python
df["Labels"] = (df["Close"] > df["Open"])
    .astype(int)
df["Labels"] = df["Labels"].shift(-1)
df.drop(df.tail(1).index,inplace=True)
```

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

### Transform Trendbar Data

Source: https://github.com/spotware/openapipy/blob/main/samples/jupyter/main.ipynb

A utility function to convert raw trendbar data received from the API into a more usable tuple format. It calculates open time, prices, and includes volume.

```python
def transformTrendbar(trendbar):
    openTime = datetime.datetime.fromtimestamp(trendbar.utcTimestampInMinutes * 60, datetime.timezone.utc)
    openPrice = (trendbar.low + trendbar.deltaOpen) / 100000.0
    highPrice = (trendbar.low + trendbar.deltaHigh) / 100000.0
    lowPrice = trendbar.low / 100000.0
    closePrice = (trendbar.low + trendbar.deltaClose) / 100000.0
    return [openTime, openPrice, highPrice, lowPrice, closePrice, trendbar.volume]
```
Tokens:
Raw