2. General Provisions

2.1. Key Rules

The API calls covered in this document follow these rules.

• By using Spotware's API, you automatically agree to the company's terms of service.

• All requests must be made to secure endpoints using the https protocol instead of http.

• API calls 3.1-3.11 are made by the broker's CRM to cTrader backend. API calls 4.1.-4.4. are made by cTrader backend to the broker's CRM.

• The content types accepted by the API calls defined in Section 3 differ according to the below table.

Endpoint Starting With	Accepted Content Types
/ctid/ or /oauth2/	Text/JSON only
/webserv/	Text/JSON and text/XML

• The endpoints in Section 3 are relative to the following URLs. The unique value of https://HOST:PORT is provided by Spotware Systems to each individual broker.

Endpoint Starting With	Relative To
/ctid/ or /oauth2/	https://HOST:PORT/cid
/webserv/	https://HOST:PORT/v2

• All API calls received by your client area/CRM (see their list here) must be available at endpoints relative to one consistent URL. Avoid establishing some endpoints at broker.com while hosting others at my.broker.com. To avoid confusion, these endpoints are referenced as https://brokerCrmUrl.com/. Additional information about this URL is provided in this tutorial.

• Several fields related to finances (balance, bonus, nonWithdrawableBonus, equity, usedMargin, and freeMargin) list their respective values in 10^moneyDigits, where moneyDigits is a separate JSON key taking integer values. An equity of 234512 with a moneyDigits value of 2 would equal 2345.12 currency units.

• If the number of requests per hour exceeds a certain threshold, all new PUT/POST/DELETE requests will be rejected. There are no rate limits for GET requests.

2.2. Authentication Provisions

The broker's backend is authenticated under the same manager's credentials used to login into the cTrader Admin backend application. For the API calls made by the broker's backend office to the cTrader backend, append an authentication token to each request by placing ?token={token} at the end of each request URL. Additional details about the manager authentication token can be found here.

The SSO (OAuth) REST API also requires the cTrader backend to be authenticated when making requests to your client area. As specified in API call 4.1., the cTrader backend exchanges a pre-generated password to acquire a long-term authentication token that must be valid for at least one week. This token is added to each request made by the cTrader back office by appending ?crmApiToken={crmApiToken} to each request URL.

2.3. Broker-Specific Parameters Provided by Spotware

The API calls defined in Section 3 take several request body keys and/or query parameters the values of which are provided by Spotware Systems on a per-broker basis. These keys are summarised in the following table.

Parameter	Data Type	Description
brokerCrmName	string	A unique name designating a broker's CRM system. If several brokers share the same CRM system, they will also have the same brokerCrmName value.
brokerName	string	A unique name denoting a specific broker (including White Labels).

2.4. Firebase Integration

Spotware's API also supports Firebase integration. You can use this functionality when both conditions below are true.

• The user accesses an SSO (OAuth) screen using cTrader Mobile.
• Sending Firebase analytics is enabled. To enable this option, contact Spotware's Service Assurance team.

To send events to Firebase, the API supports the eventName query parameter.

Parameter	Data Type	Description
eventName	string	The name of the event to be sent to Firebase.

You can add this parameter to the URLs that host various SSO (OAuth) screens. When a user is transferred from one URL to another during an SSO (OAuth) flow (e.g., when completing the first stage of the account registration process and being sent to the second stage) and eventName is specified in the screen URL, the event is sent to Firebase under the specified name.

As a result, you can attain detailed statistics about how and when users are redirected as part of broker SSO (OAuth) flows. This functionality facilitates tracking users' progression along the onboarding funnel.

info

You can use eventName to track how many traders who have opened an account with your brokerage choose to start passing your KYC checks as well as how many traders are lost at each distinct stage of your KYC process (if these stages have custom screens shown on different URLs).

2.5. SSO (OAuth) Screens and InApp Controls Examples

The SSO (OAuth) flows require you to create and host various screens inside your client area. Below, we provide examples of how these screens may look like depending on their type. We also provide an example of an InApp control (a ribbon).

Login/Signup Screens

Web Example One

Mobile Example One

Web Example Two

Mobile Example Two

Web Example Three

Mobile Example Three

Deposit/Withdrawal Screens

Web Example One

Mobile Example One

Web Example Two

Mobile Example Two

Web Example Three

Mobile Example Three

InApp Controls (Ribbons)

Web Example One

Mobile Example One

Web Example Two

Mobile Example Two

Web Example Three

Mobile Example Three

2.6. Requirements for Brokers' CRM Systems

2.6.1. API Interaction

The deployment of SSO (OAuth) flows is only possible if the following mandatory requirements are met.

• Dedicated login/signup, account creation, and InApp action screens pages are prepared by the broker.
• The screens accept the required URL parameters. In addition, the custom login/signup screen attributes users based on the specified partnerId (when relevant).
• The broker's client area creates a new user when sending an API call to the cTrader backend.
• The broker's CRM system generates valid OT tokens.
• The broker's CRM redirects users to a success URL while retrieving the relevant OT token.
• The broker has deployed a REST API allowing the cTrader backend to exchange the OT token for a long-term access token.
• The broker's client area contains a link to cTrader Web; upon clicking on it, cTrader Web is opened on a separate page.
• The broker's CRM needs to store information about the user's preferred language. In case a user first registers in the broker's client area, this is needed to send a welcome email in the correct language.

2.6.2. Infrastructure Connectivity

Brokers must use a direct connection, with costs covered by them, to enhance the quality and stability of their connection to Spotware services. Two cross connection options are available:

Direct connection between our data centre and your infrastructure

Our data centres are available in these locations:

• UK. Equinix LD4 and Equinix LD7. Cross-connections with this data centre are suitable for brokers with infrastructure in the UK.
• US. Equinix NY2 and Equinix NY6. Cross-connections with this data centre are suitable for brokers with infrastructure in the US.

Technical requirements

• Cable type: 1G/10G Fiber
• Routing: Private AS, Private network with a subnet mask of up to /28 (in rare cases up to /24), BGP.

We strongly recommend that brokers establish two cross-connections to ensure redundancy and avoid disruptions during our maintenance and maintenance of the data centres.

Connection via AWS

Our data centres are AWS partners. Therefore, clients with infrastructure on AWS can connect to our data centres using the Direct Connect service. This connection option is more convenient because you do not have to set up direct connections between your infrastructure and ours.

To set up the connection via AWS, you will need to provide your AWS ID, AWS zone, number of connections via Direct Connect and the speed of each connection (minimum speed is 50 Mbps). You are responsible for covering all costs and managing AWS-side configurations.

Technical requirements for routing: Private AS, Private network with a subnet mask of up to /28 (in rare cases up to /24), BGP.

We strongly recommend that brokers establish two cross-connections to ensure redundancy and avoid disruptions during our maintenance, data centre maintenance or AWS maintenance.

2.6.3. UX

Meeting the following optional requirements should give you additional options for enhancing your broker SSO (OAuth) UX.

• Users are correctly redirected to a success page along with a related OT token.
• The screens accept optional parameters and modify the page contents accordingly.
• The broker's client area contains cTrader Web as an embeddable iframe.