Create account replica

About

Creates a trading account replica in a region different from trading account region and starts a cloud API server for it. It can take some time for the API server and trading terminal to start and connect to broker. You can use the connectionStatus replica field to monitor the current status of the replica.

POST /users/current/accounts/:accountId/replicas

For more information see swagger documentation

Headers

Name	Type	Required	Description
auth-token	string	Yes	Authorization token. See Authentication and authorization
transaction-id	string	Yes	Transaction id is used to identify a unique transaction. For the new request please generate a random 32-character transaction id. If your request has returned 202 status code, please reuse the same transaction id value to poll the result of the request you've sent earlier.

Path parameters

Name	Type	Required	Description
accountId	string	Yes	Primary account id
account	TradingAccount	Yes	Trading account data

Body

Name	Type	Required	Description
magic	number	Yes	Magic value the trades should be performed using. When manualTrades field is set to true, magic value must be 0
region	string	Yes	Region id to deploy account replica at. One of returned by the /users/current/regions endpoint
quoteStreamingIntervalInSeconds	number		Quote streaming interval in seconds. Set to 0 in order to receive quotes on each tick. Default value is 2.5 seconds. Intervals less than 2.5 seconds are supported only for G2
tags	Array		User-defined account replica tags
metadata	object		Extra information which can be stored together with your account replica. Total length of this field after serializing it to JSON is limited to 1024 characters
reliability	string		Used to increase the reliability of the account replica. Allowed values are regular and high. High is a recommended value for production environment. Default is high
resourceSlots	number		Number of resource slots to allocate to account replica. Allocating extra resource slots results in better account performance under load which is useful for some applications. E.g. if you have many accounts copying the same strategy via CooyFactory API, then you can increase resourceSlots to get a lower trade copying latency. Please note that allocating extra resource slots is a paid option. Default is 1
copyFactoryResourceSlots	number		Number of CopyFactory 2 resource slots to allocate to account replica. Allocating extra resource slots results in lower trade copying latency. Please note that allocating extra resource slots is a paid option. Please also note that CopyFactory 2 uses redundant infrastructure so that each CopyFactory resource slot is billed as 2 standard resource slots. You will be billed for CopyFactory 2 resource slots only if you have added your account to CopyFactory 2 by specifying copyFactoryRoles field. Default is 1

Response

201 - New trading account replica created successfully. Schema:

Name	Type	Required	Description
id	string	Yes	Created trading account replica id
state	string	Yes	State of the account replica created. Possible values are 'UNDEPLOYED', 'DEPLOYED', 'DRAFT'

202 - Request accepted. Reponse schema: AcceptedError
400 - Validation failed. Response schema: Error
401 - Authorization failed. Response schema: Error
403 - Method or resource access permissions are missing. Response schema: Error
404 - Primary account not found. Response schema: Error

Examples

Example request:

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'auth-token: token' --header 'transaction-id: transactionId' -d '{
    "magic": 123456,
    "region": "london"
}' 'https://mt-provisioning-api-v1.agiliumtrade.agiliumtrade.ai/users/current/accounts/861ceafd-a58e-2fb9-a9bb-c9dd449f3bb4/replicas'

If the account replica has been created successfully, you will receive a response with account replica id:

{
  "id": "1eda642a-a9a3-457c-99af-3bc5e8d5c4c9",
  "state": "DEPLOYED"
}

Broker settings detection or connection validation might take some time. If so you will receive response with request processing stage and amount of seconds after which another attempt can be made:

{
  "message": "Automatic broker settings detection is in progress, please retry in 60 seconds",
}

Response headers:

{
  "Retry-After": "Thu, 04 May 2023 13:42:20 GMT"
}

The retry-after header indicates when it is recommended to repeat the request for its successful completion. If process has been successfully completed, your next request will return the standard response:

{
  "id": "1eda642a-a9a3-457c-99af-3bc5e8d5c4c9",
  "state": "DEPLOYED"
}

Errors

Several types of errors are possible during the request:

Server file not found
Authentication error
Forbidden error
Settings detection error
Resource slots error

Server file not found

This error is returned if the server file for the specified server name has not been found. In case of this error it is recommended to check the server name or recreate the primary account using a provisioning profile. Error also includes existing server names that are similar to provided one.

Example:

{
  "id": 3,
  "error": "ValidationError",
  "message": ".dat file for server ICMarkets-Demo not found, please check the server name or use a provisioning profile instead. Suggested server names: 
  ICMarketsSC-Demo, ICMarketsSC-MT5.",
  "details": {
    "code": "E_SRV_NOT_FOUND",
    "serversByBrokers": {
      "Raw Trading Ltd": [
        "ICMarketsSC-Demo",
        "ICMarketsSC-MT5"
      ]
    }
  }
}

Authentication error

This error is returned if the server has failed to connect to the broker using your credentials. This error indicates that your primary account is no longer valid and needs to be recreated.

Example:

{
  "id": 3,
  "error": "ValidationError",
  "message": "We failed to authenticate to your broker using credentials provided. This means that there is an \"Invalid account\" or \"Account disabled\" error on the trading terminal. Please check that your trading account platform version, login, password and server name are correct.",
  "details": "E_AUTH"
}

Settings detection error

This error is return if the server has failed to detect the broker settings. In case of this error it is recommended to retry the request later or recreate the primary account using a provisioning profile.

Example:

{
  "id": 3,
  "error": "ValidationError",
  "message": "We were not able to retrieve server settings using credentials provided. Please try again later or configure the provisioning profile manually.",
  "details": "E_SERVER_TIMEZONE"
}

Resource slots error

Depending on your broker and trading account some trading accounts might require extra resource slots to be executed successfully in the cloud. If your trading account requires extra resource slots then you will receive a E_RESOURCE_SLOTS error in response. You will then need to re-submit your request with updated resource slots value in order for your trading account to be added to MetaApi cloud.

Example:

{
  "id": 3,
  "error": "ValidationError",
  "message": "Account resource slots should be equal or above estimated",
  "details": {
    "code": "E_RESOURCE_SLOTS",
    "recommendedResourceSlots": 2
  }
}