@claasahl/spotware-connect-apideprecated

Protocol Buffers and Data Models for Spotware Open API 2.0

Usage no npm install needed!

<script type="module">
  import claasahlSpotwareConnectApi from 'https://cdn.skypack.dev/@claasahl/spotware-connect-api';
</script>

README

ALPHA VERSION

Currently, the most juicy bits and peaces of this package are:

  • generated data models for spotware messages
  • latest set of protocolbuf files

Upcoming Changes

  • a typescript/javascript client for communicating with spotware open api v2 servers
  • client is likely to be based on TLSSocket and EventEmitter
  • client might be moved into a dedicated package

-----

spotware-connect-api

Protocol Buffers and Data Models for Spotware Open API 2.0

This client is based on TLSSocket and exposes every Spotware message via EventEmitter functions (i.e. on, off, once, emit).

Client and Backbone

The backbone of this client for the Spotware Open API V2 is a NodeJS EventEmitter. Requests, responses and events are funneled through the EventEmitter.

One can listen and react to Spotware messages (i.e. any request being sent, any received response and any received/emitted event) by registering a listener.

import {
  connect,
  fromProtoMessage,
  toProtoMessage,
  writeProtoMessage
} from "@claasahl/spotware-connecti-api";

// establish connection
const client = connect(
  5035,
  "live.ctraderapi.com"
);

// handle (incoming) proto messages
client.on("PROTO_MESSAGE", (message, payloadType) => {
  console.log(payloadType);
  switch (payloadType) {
    case "ERROR_RES": {
      const msg = fromProtoMessage("ERROR_RES", message);
      console.log(msg);
      break;
    }
    case "PROTO_OA_VERSION_REQ": {
      const msg = fromProtoMessage("PROTO_OA_VERSION_REQ", message);
      console.log(msg);
      break;
    }
    case "PROTO_OA_VERSION_RES": {
      const msg = fromProtoMessage("PROTO_OA_VERSION_RES", message);
      console.log(msg);
      break;
    }
  }
});

// write (outgoing) proto messages
setInterval(() => {
  const message = toProtoMessage("HEARTBEAT_EVENT", {});
  writeProtoMessage(client, message);
}, 10000);

writeProtoMessage(client, toProtoMessage("PROTO_OA_VERSION_REQ", {}));

The EventEmitter-interface has been specialized to accept only Spotware messages.

This client treats Spotware messages like so.

Open API v2

Important Links

Technologies

Glossary

cTrader ID

A cTrader ID (cTID) is a set of credentials used for signing in across all cTrader platforms. A cTID is different from a trading account. An account number is a seven digit number used for logging into your account with a broker, a trading account can only be used with the specific broker it belongs to.

Introduction

The Open API 2.0 is the second version of the publicly available protobuf-based API developed by Spotware. Unlike the previous Open API (i.e. version 1.0), which was using a different protocol for each scope (REST and Protocol Buffers), the Open API 2.0 is designed to use solely protocol buffers. Now by using Protocol Buffers you can retrieve accounts information, market data, and trading data. The API is open for everyone with no restrictions (see Terms of Use) and it is supported by all trading accounts of any cTrader supported brokers.

OAuth 2

Scopes

  • Accounts scope: to request for access to the Account Info (trading history, positions, pending orders, etc.)
  • Trading scope: to request for permissions to perform trading actions on behalf of Account owner (send market and pending orders, receive trading events, etc.)

Services

  • auth - can be used to authorize resource (trading account) owners.
  • token - can be used to refresh or obtain tokens.

Grant Types

  • Authorization Code:

    The Authorization Code grant type is used by confidential and public clients to exchange an authorization code for an access token. After the user returns to the client via the redirect URL, the application will get the authorization code from the URL and use it to request an access token. source

  • Refresh Token:

    The Refresh Token grant type is used by clients to exchange a refresh token for an access token when the access token has expired This allows clients to continue to have a valid access token without further interaction with the user.source

Protocol Buffer - ProtoMessages

Message Naming Conventions

Messages are divided into one of four groups.

  • Request messages
  • Response messages
  • Event messages
  • Model messages

https://protogen.marcgravell.com/decode

Servers

  1. live.ctraderapi.com:5035
  2. demo.ctraderapi.com:5035

data

  1. create nessage (e.g. PingReq)
  2. wrap message in ProtoMessage
  3. prepend length of proto message (4 bytes in big endian)

Getting Started

  1. log In with cTID
  2. select application
  3. view development application (see screenshot)
  4. take note of credentials for development application

Protobuf Hosts

Open API v1

Open API v2