diff --git a/docs/authentication.md b/docs/authentication.md deleted file mode 100644 index 4ce83f7..0000000 --- a/docs/authentication.md +++ /dev/null @@ -1,70 +0,0 @@ -### Auth Class - -For authentication you can use the package Auth class, first create an instance of it: - -```python -from ctrader_open_api import Auth - -auth = Auth("Your App ID", "Your App Secret", "Your App redirect URI") -``` - -### Auth URI - -The first step for authentication is sending user to the cTrader Open API authentication web page, there the user will give access to your API application to manage the user trading accounts on behalf of him. - -To get the cTrader Open API authentication web page URL you can use the Auth class getAuthUri method: - -```python -authUri = auth.getAuthUri() -``` -The getAuthUri has two optional parameters: - -* scope: Allows you to set the scope of authentication, the default value is trading which means you will have full access to user trading accounts, if you want to just have access to user trading account data then use accounts - -* baseUri: The base URI for authentication, the default value is EndPoints.AUTH_URI which is https://connect.spotware.com/apps/auth - -### Getting Token - -After user authenticated your Application he will be redirected to your provided redirect URI with an authentication code appended at the end of your redirect URI: - -``` -https://redirect-uri.com/?code={authorization-code-will-be-here} -``` - -You can use this authentication code to get an access token from API, for that you can use the Auth class getToken method: - -```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") -``` - -Pass the received auth code to getToken method and it will give you a token JSON object, the object will have these properties: - -* accessToken: This is the access token that you will use for authentication - -* refreshToken: This is the token that you will use for refreshing the accessToken onces it expired - -* expiresIn: The expiry of token in seconds from the time it generated - -* tokenType: The type of token, standard OAuth token type parameter (bearer) - -* errorCode: This will have the error code if something went wrong - -* description: The error description - -### Refreshing Token - -API access tokens have an expiry time, you can only use it until that time and once it expired you have to refresh it by using the refresh token you received previously. - -To refresh an access token you can use the Auth class refreshToken method: - -```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") -``` - -You have to pass the refresh token to "refreshToken" method, and it will return a new token JSON object which will have all the previously mentioned token properties. - -You can always refresh a token, even before it expires and the refresh token has no expiry, but you can only use it once. diff --git a/docs/client.md b/docs/client.md index 9b2bb37..211b0bb 100644 --- a/docs/client.md +++ b/docs/client.md @@ -2,7 +2,7 @@ You will use an instance of this class to interact with API. -Each instance of this class will have one connection to API, either live or demo endpoint. +Each instance of this class will have one connection to API, either QUOTE or TRADE. The client class is driven from Twisted ClientService class, and it abstracts away all the connection / reconnection complexities from you. @@ -12,79 +12,34 @@ Let's create an isntance of Client class: ```python -from ctrader_open_api import Client, Protobuf, TcpProtocol, Auth, EndPoints +from ctrader_fix import * -client = Client(EndPoints.PROTOBUF_DEMO_HOST, EndPoints.PROTOBUF_PORT, TcpProtocol) +client = Client(config["Host"], config["Port"], ssl = config["SSL"]) ``` It's constructor has several parameters that you can use for controling it behavior: -* host: The API host endpoint, you can use either EndPoints.PROTOBUF_DEMO_HOST or EndPoints.PROTOBUF_LIVE_HOST +* host: The API host endpoint, you can get it from your cTrader FIX settings -* port: The API host port number, you can use EndPoints.PROTOBUF_PORT +* port: The API host port number, you can get it from your cTrader FIX settings -* protocol: The protocol that will be used by client for making connections, use imported TcpProtocol +* ssl: It't bool flag, if Yes client will use SSL for connection otherwise it will use plain TCP connection -* numberOfMessagesToSendPerSecond: This is the number of messages that will be sent to API per second, set it based on API limitations or leave the default value +***The SSL connection is not working for now*** There are three other optional parameters which are from Twisted client service, you can find their detail here: https://twistedmatrix.com/documents/current/api/twisted.application.internet.ClientService.html -### Sending Message +### Callbacks -To send a message you have to first create the proto message, ex: - -```python -# Import all message types -from ctrader_open_api.messages.OpenApiCommonMessages_pb2 import * -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" - -``` - -After you created the message and populated its fields, you can send it by using Client send method: - -```python -deferred = client.send(applicationAuthReq) -``` - -The client send method returns a Twisted deferred, it will be called when the message response arrived, the callback result will be the response proto message. - -If the message send failed, the returned deferred error callback will be called, to handle both cases you can attach two callbacks for getting response or error: - -```python -def onProtoOAApplicationAuthRes(result): - print(result) - -def onError(failure): - print(failure) - -deferred.addCallbacks(onProtoOAApplicationAuthRes, onError) -``` -For more about Twisted deferreds please check their documentation: https://docs.twistedmatrix.com/en/twisted-16.2.0/core/howto/defer-intro.html - -### Canceling Message - -You can cancel a message by calling the returned deferred from Client send method Cancel method. - -If the message is not sent yet, it will be removed from the messages queue and the deferred Errback method will be called with CancelledError. - -If the message is already sent but the response is not received yet, then you will not receive the response and the deferred Errback method will be called with CancelledError. - -If the message is already sent and the reponse is received then canceling it's deferred will not have any effect. - -### Other Callbacks - -The client class has some other optional general purpose callbacks that you can use: +To use your client you have to set it's call backs: * ConnectedCallback(client): This callback will be called when client gets connected, use client setConnectedCallback method to assign a callback for it * DisconnectedCallback(client, reason): This callback will be called when client gets disconnected, use client setDisconnectedCallback method to assign a callback for it * MessageReceivedCallback(client, message): This callback will be called when a message is received, it's called for all message types, use setMessageReceivedCallback to assign a callback for it + +Use the connected call back to send a logon message. + +And after logon use your message received call back to continue your interaction with API. diff --git a/docs/config.md b/docs/config.md new file mode 100644 index 0000000..a9b695b --- /dev/null +++ b/docs/config.md @@ -0,0 +1,50 @@ +### Config + +When you create a request message you have to pass a config, this config should be a dictionary like object with these keys: + +* Host: The FIX host that will be used for client connection +* Port: The port number of host +* SSL: true/false, this can be used by client if SSL connected is required +* Username: Your cTrader trading account number +* Password: Your cTrader trading account password +* BeginString: Message begin string (FIX.4.4) +* SenderCompID: Your cTrader FIX SenderCompID +* SenderSubID: Your cTrader FIX SenderSubID (QUOTE/TRADE) +* TargetCompID: Your cTrader FIX TargetCompID (cServer), +* TargetSubID: Your cTrader FIX TargetSubID (QUOTE), +* HeartBeat: The heartbeat seconds (30) + +You can get the values for most of them from your cTrader FIX settings. + +You can use a JSON file to save your configuration, check our samples. + +### JSON Sample + +```json +{ + "Host": "h51.p.ctrader.com", + "Port": 5201, + "SSL": false, + "Username": "3279204", + "Password": "3279204", + "BeginString": "FIX.4.4", + "SenderCompID": "demo.icmarkets.3279203", + "SenderSubID": "QUOTE", + "TargetCompID": "cServer", + "TargetSubID": "QUOTE", + "HeartBeat": "30" +} +``` + +You can use it like this: + +```python +with open("config.json") as configFile: + config = json.load(configFile) + +# For client +client = Client(config["Host"], config["Port"], ssl = config["SSL"]) + +# For request messages +logonRequest = LogonRequest(config) +``` diff --git a/docs/index.md b/docs/index.md index 7302f78..588c922 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,65 +1,59 @@ ### Introduction -A Python package for interacting with cTrader Open API. +A Python package for interacting with cTrader FIX API. This package is developed and maintained by Spotware. -You can use OpenApiPy on all kinds of Python apps, it uses Twisted to send and receive messages asynchronously. +You can use cTraderFix on all kinds of Python apps, it uses Twisted to send and receive messages asynchronously. -Github Repository: https://github.com/spotware/OpenApiPy +Github Repository: https://github.com/spotware/cTraderFixPy ### Installation -You can install OpenApiPy from pip: +You can install cTraderFix from pip: ``` -pip install ctrader-open-api +pip install ctrader-fix ``` ### Usage ```python -from ctrader_open_api import Client, Protobuf, TcpProtocol, Auth, EndPoints -from ctrader_open_api.messages.OpenApiCommonMessages_pb2 import * -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): # Call back for errors - print("Message Error: ", failure) - -def connected(client): # Callback for client connection - 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 +from inputimeout import inputimeout, TimeoutOccurred +import json +from ctrader_fix import * + +# Callback for receiving all messages +def onMessageReceived(client, responseMessage): + print("Received: ", responseMessage.getMessage().replace("�", "|")) + messageType = responseMessage.getFieldValue(35) + if messageType == "A": + print("We are logged in") + +# Callback for client disconnection +def disconnected(client, reason): + print("Disconnected, reason: ", reason) + +# Callback for client connection +def connected(client): + print("Connected") + logonRequest = LogonRequest(config) + send(logonRequest) + +# you can use two separate config files for QUOTE and TRADE +with open("config-trade.json") as configFile: + config = json.load(configFile) + +client = Client(config["Host"], config["Port"], ssl = config["SSL"]) + +# Setting client callbacks client.setConnectedCallback(connected) client.setDisconnectedCallback(disconnected) client.setMessageReceivedCallback(onMessageReceived) # Starting the client service client.startService() -# Run Twisted reactor reactor.run() ``` diff --git a/docs/receiving-messages.md b/docs/receiving-messages.md new file mode 100644 index 0000000..adf9e59 --- /dev/null +++ b/docs/receiving-messages.md @@ -0,0 +1,23 @@ +### Response Message + +Whenever client receives a FIX message it calls the "MessagedReceived" callback with the message. + +The message parameter of callback is not a plain string, it's an instance of ResponseMessage type. + +ResponseMessage class allows you to easily access each field of a response message. + +### Getting Message Field Values + +To get a field value you can use the response message GetFieldValue method, it takes the FIX field number and returns the value(s). + +The GetFieldValue can return three types of values: + +* String: When there is only one field of your provided field number on the message it returns that field value + +* List: If the field is repetitive like symbol IDs or names, then it returns a list, all of those fields values will be inside that list + +* None: if there was no such field inside the message + +### Getting Raw Message + +If you want to get the raw string of reponse message, you can call the response message getMessage method. diff --git a/docs/sending-messages.md b/docs/sending-messages.md new file mode 100644 index 0000000..7121ceb --- /dev/null +++ b/docs/sending-messages.md @@ -0,0 +1,40 @@ +### Messages + +The package has a class for each of the cTrader FIX API client side messages. + +You have to use those classes to send request messages. + +To set fields of a message you should use message instance attributes and use exact field names that are defined on cTrader FIX Engine, Rules of Engagement document. + +### Examples + +Let's create some messages: + +```python +# All mesages contructors requires the config to be passes a parameter +logonRequests = LogonRequest(config) + +securityListRequest = SecurityListRequest(config) +securityListRequest.SecurityReqID = "A" +securityListRequest.SecurityListRequestType = 0 + +newOrderSingle = NewOrderSingle(config) +newOrderSingle.ClOrdID = "B" +newOrderSingle.Symbol = 1 +newOrderSingle.Side = 1 +newOrderSingle.OrderQty = 1000 +newOrderSingle.OrdType = 1 +newOrderSingle.Designation = "From FIX" +``` + +### Sending + +To send a message you must use the client send method: + +```python +# It returns a Twisted diferred +diferred = client.send(request) +diferred.addCallback(lambda _: print("\nSent: ", request.getMessage(client.getMessageSequenceNumber()).replace("", "|"))) +``` + +You can only call the client send method from OnMessageReceived call back or connected callback. diff --git a/mkdocs.yml b/mkdocs.yml index 8164848..a4dc588 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,14 +1,14 @@ --- # Project Information -site_name: OpenApiPy +site_name: cTraderFixPy site_author: Spotware site_url: https://openapinet.readthedocs.io/en/latest/ -site_description: cTrader Open API Python package documentation +site_description: cTrader FIX API Python package documentation # Repository information -repo_name: spotware/openApiPy -repo_url: https://github.com/spotware/openApiPy -edit_uri: "https://github.com/spotware/openApiPy/tree/master/docs" +repo_name: spotware/cTraderFixPy +repo_url: https://github.com/spotware/cTraderFixPy +edit_uri: "https://github.com/spotware/cTraderFixPy/tree/master/docs" copyright: "Copyright © Spotware Systems Ltd. cTrader, cAlgo, cBroker, cMirror. All rights reserved." @@ -111,9 +111,11 @@ markdown_extensions: # Page tree nav: - Getting Started: index.md - - Authentication: 'authentication.md' + - Config: 'config.md' - Client: 'client.md' - - Samples: "https://github.com/spotware/OpenApiPy/tree/main/samples" + - Sending Messages: 'sending-messages.md' + - Receiving Messages: 'receiving-messages.md' + - Samples: "https://github.com/spotware/cTraderFixPy/tree/main/samples"