¶ 2. Domain Model and Logic
This page defines the key terms and entities forming the core cTrader infrastructure.
¶ 2.1. Defining Server Structure
cTrader servers are comprised of the following elements.
Plant. This term denotes a logical aggregation of several environments into a single ‘pack’. In the vast majority of cases, a plant combines all environments managed by a single broker. This aggregation is useful to quickly and clearly identify a specific trading server (as shown below by our naming convention) and to facilitate billing.
Environment. This term defines an actual server which is itself an instance of the backend solution provided by Spotware to a broker. Our generic setup allows two environments (namely demo or live) to exist on one plant. Brokers can request the creation of additional environments (e.g., live2) with any naming. A single broker may have an unlimited number of environments. However, the deployment of each new environment is billed separately and constitutes an additional charge. Please contact sales@spotware.com to get more information on adding new environments.
Broker (White Label). This designation applies to an entity that can be used to segregate trading accounts registered on one plant. This entity, therefore, may refer to different White Labels (WLs) and/or jurisdictions. By default, each plant contains one broker (which is denoted as brokerName in this API) with the name of this broker also used as the plant name. Note that a plant may support a potentially infinite number of broker/WL entities.
Given the terms defined above, our naming convention for a trading server is {environment}.{plant}. For example, a server could be designated as demo.superbroker.
The following examples graphically summarize the relationship between plants, environments, and brokers.
¶ 2.2 Defining cTrader ID (cTID)
As part of our continuous improvements to the creation/authorization UX, we have introduced a solution that allows all cTrader users to have a single set of credentials for any environment in the cTrader ecosystem. This per-user set of credentials forms an entity that we have designated as cTrader ID or simply cTID.
Think of cTID as a unique identifier of a certain user-person within the cTrader ecosystem. To create a new cTID, the user must provide a valid email address.
After a user registers their email, our system finishes creating the new cTID by automatically assigning the user with a unique nickname (that is a part of the specified email). This nickname can be later changed by the user. The cTID, subsequently, allows the user to authorize in any cTrader application (of any cTrader-affiliated broker) by entering the related set of credentials.
Authorization via cTID is possible either via the user’s email or their custom (or automatically generated) nickname, and the correct password. To account for this, all cTrader applications denote possible logins as the user’s email or the cTrader ID. The custom nickname is not mentioned as not all users may choose to set it after creating a new cTID. Nevertheless, cTID is an entity that may contain a unique email and a unique nickname, leading to the possibility of using either to login inside cTrader applications.
To reiterate, cTID allows for using a single set of credentials to log into cTrader applications and access accounts that may be registered under any number of different brokerages. For reasons of security, brokers cannot change or set cTID passwords as this would lead to brokers gaining access to sensitive data from plants that they may not own. Users receive automatic emails from Spotware about cTID creation and the link to set their passwords.
In this API, cTID entities are denoted as ‘users’.
¶ 2.3. Account (Trader) and Linkage to cTID
As an entity, cTID is only used for user authorization. In our ecosystem, the responsibility to perform trading operations is delegated to accounts that constitute entirely different entities compared to cTID. In this API, accounts are referred to as ‘traders’.
To elaborate, an account is an entity that always belongs to a specific cTID and has the power to engage in trading activities.
In contrast to cTIDs, accounts are always registered on a specific plant and a specific environment. As cTIDs cannot trade, they must be linked to at least one account on any server.
Note that each cTID can have an unlimited number of linked accounts registered on different servers. Nonetheless, cTrader applications are designed so that only linked accounts from a specific broker are shown to a cTID when using a branded cTrader application. The only exception to this rule is Spotware cTrader as it functions as a cross-broker application.
While an account still has a password as an attribute, it is only used in two cases.
- Brokers must use it to link an account to a related cTID.
- Developers must use it when working with our FIX API solution.
The diagram below illustrates a case in which both user1 and user2 have registered several demo and live accounts on different plants. With the exception of the cross-broker application, user1 will only see two accounts registered with brokerOne when accessing cTrader applications branded and released for brokerOne. In contrast, when accessing the same applications, user2 will see three accounts registered with brokerOne.
Users constitute higher-order entities compared to accounts. When you want to create a new user-trader pair, the order in which you create individual entities does not matter from the practical point of view. However, creating a new user first is a more transparent and reliable process and we recommend you follow it in your integration.
¶ 2.4. Summary
As an entity, the cTID is used to authorize end users in the trading application(s) of their choice.
Accounts, in turn, can perform trading operations on a per-plant per-environment basis. A cTID may have any number of linked trading accounts.
As a result, to fully register a new user, a broker must perform the following actions:
- Create a new cTID (API call 5.1.).
- Create a new account (API call 4.1.).
- Link the new account to the cTID (API call 5.2).
Note that, in contrast to other trading platforms, cTrader accounts for two different authorization flows that end users may choose to participate in.
- Login using a cTID. The current API spec covers this model.
- Login using credentials from a broker’s client area/portal/CRM. Detailed specifications for this model can be found in our documentation for the broker SSO (OAuth) solution.