repository·main·Indexed 41 days ago
https://github.com/spotware/openapipyAn asynchronous Python client for the cTrader Open API, built on the Twisted networking framework and Protobuf for non-blocking communication. It provides the ctrader_open_api package, featuring a Client for connection management, an Auth class for OAuth2 flows, and Protobuf utilities for message serialization and deserialization.
The Console Sample operates using a single thread (the Python main execution thread) to handle both user input and the sending/receiving of API messages.
Because the main thread is shared, user input commands have a timeout. If a command is not entered within the specified period, the application will block for a few seconds before resuming command acceptance.
OpenApiPy is an asynchronous Python package built on top of the Twisted networking engine.
Key architectural concepts:
client.send()) return a Twisted deferred. You interact with these using .addCallback() for successful responses or .addErrback() for error handling.Client instance to handle connection lifecycle events and incoming messages.Install the ctrader-open-api package using pip to start interacting with the cTrader Open API.
pip install ctrader-open-apiTo send a message, first instantiate and populate the appropriate Protobuf message type. Use the client.send() method to dispatch the message.
client.send() returns a Twisted deferred. You must attach callbacks to this deferred to handle the asynchronous response:
# 1. Import 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 *
# 2. Create and populate the message
applicationAuthReq = ProtoOAApplicationAuthReq()
applicationAuthReq.clientId = "Your App Client ID"
applicationAuthReq.clientSecret = "Your App Client secret"
# 3. Send the message and handle the deferred
deferred = client.send(applicationAuthReq)
def onProtoOAApplicationAuthRes(result):
print(f"Response received: {result}")
def onError(failure):
print(f"Error occurred: {failure}")
deferred.addCallbacks(onProtoOAApplicationAuthRes, onError)The Console Sample requires the inputimeout Python package to handle timed user inputs within the main execution thread. You must install this package before running the sample.
pip install inputimeoutTo handle authentication workflows, create an instance of the Auth class from the ctrader_open_api package. You must provide your application's credentials and the redirect URI where users will be sent after authentication.
from ctrader_open_api import Auth
auth = Auth("Your App ID", "Your App Secret", "Your App redirect URI")To use the Jupyter Sample, you must prepare a credentials file.
credentials.json file.credentials-dev.json.credentials-dev.json and populate it with your Open API application credentials, access token, and a trading account ID.Use the Client class to interact with the cTrader Open API. Each instance manages a single connection to either a live or demo endpoint and abstracts connection/reconnection complexities using the Twisted ClientService.
To initialize a client, provide the host, port, and protocol (typically TcpProtocol). You can also control the message rate using numberOfMessagesToSendPerSecond to comply with API limitations.
from ctrader_open_api import Client, Protobuf, TcpProtocol, Auth, EndPoints
# Create a client instance for the Demo endpoint
client = Client(EndPoints.PROTOBUF_DEMO_HOST, EndPoints.PROTOBUF_PORT, TcpProtocol)To use the client, you must select a host (Live or Demo), instantiate the Client with a protocol (typically TcpProtocol), set up your event callbacks, and start the Twisted reactor.
Follow these steps:
EndPoints.PROTOBUF_LIVE_HOST or EndPoints.PROTOBUF_DEMO_HOST.client = Client(host, EndPoints.PROTOBUF_PORT, TcpProtocol).setConnectedCallback, setDisconnectedCallback, and setMessageReceivedCallback to handle events.client.startService().reactor.run() to start the asynchronous loop.from ctrader_open_api import Client, Protobuf, TcpProtocol, Auth, EndPoints
from ctrader_open_api.messages.OpenApiMessages_pb2 import *
from twisted.internet import reactor
# 1. Setup connection details
host = EndPoints.PROTOBUF_DEMO_HOST
client = Client(host, EndPoints.PROTOBUF_PORT, TcpProtocol)
# 2. Define event handlers
def connected(client):
print("Connected!")
def onMessageReceived(client, message):
# Use Protobuf.extract to view the message content
print("Message received: \n", Protobuf.extract(message))
# 3. Register callbacks
client.setConnectedCallback(connected)
client.setMessageReceivedCallback(onMessageReceived)
# 4. Start and run
client.startService()
reactor.run()If you already possess a valid access token, you can skip the standard account authentication process by navigating directly to the client area using the token query parameter:
http://localhost:8080/client-area?token=your-access-token
The Klein Web App Sample is a web-based demonstration of the Spotware OpenApiPy Python package using the Twisted Klein web framework. To run the sample, follow these steps:
credentials.json file, rename it to credentials-dev.json, and populate it with your Open API application credentials.pip install kleinmain.py file.http://localhost:8080 in your web browser.pip install kleinOpenApiPy is built on top of Twisted, meaning execution is asynchronous and non-sequential. You interact with the API using a callback-driven pattern:
client.setConnectedCallback(func), client.setDisconnectedCallback(func), and client.setMessageReceivedCallback(func) to handle lifecycle events and incoming messages.client.send(request), it returns a Twisted deferred. You must attach callbacks to this deferred using .addCallbacks(onSuccess, onError) to handle the response or any errors.client.startService() and then reactor.run() to start the asynchronous event loop.Typical Workflow Example:
connected callback triggers $\rightarrow$ send ProtoOAApplicationAuthReq.applicationAuthResponseCallback (on success) $\rightarrow$ send ProtoOAAccountAuthReq.accountAuthResponseCallback (on success) $\rightarrow$ send data requests (like ProtoOAGetTrendbarsReq).