00 usage guide

Upload: grof-pongracz-istvan

Post on 07-Apr-2018

227 views

Category:

Documents


0 download

TRANSCRIPT

  • 8/4/2019 00 Usage Guide

    1/21

    Web Service API v1.0 BETADeveloper's Guide

    Sections

    1. Overview

    What this document is about.

    Who this document is targeted towards2. Usage Requirements

    Technical Requirements

    Web Service API Requirements3. Generic JSON Object Formats, Request Methods, and Response Codes, etc.

    4. QS4 (Quote Streamer 4) Services

    Quote Fetching5. WR4 (Web Registration 4) Services ~Deprecated

    Account Creation ~Deprecated

    6. GDB (Global Database) Services

    Account Fetching

    Broker Fetching

    Group Fetching

    7. MT4 (Meta-Trader 4) Services

    Account Creation

    Account Modification

    Account Fetching

    Group Fetching

  • 8/4/2019 00 Usage Guide

    2/21

    Section 1Overview

    What this document is aboutThis document is about the Web Services API. The Web Services API is a RESTful

    programmable interface designed with the intention for to have a universal way to service theirclients. The Web Service is intended only for use by clients of .

    Who this document is targeted towards

    This document is targeted towards clients; more specifically, developer employees of saidclients. Developers can utilize this web service to interact with services via a programmable

    interface. The majority of examples supplied with this document are written in PHP;

    however, the web service is designed to be used with any language that can send and receiveHTTP requests and responses.

  • 8/4/2019 00 Usage Guide

    3/21

    Section 2Usage RequirementsTechnical Requirements

    The technical requirements are defined as what technology is required to use the web service.

    Must be implemented with a language that can send and receive HTTP requests andresponses. For example, PHP's client URL (cURL) library plug-in.

    It is recommended that the web service be implemented with a language that

    supports JSON parsing. For example, PHP's JSON library plug-in. It is recommended that the developer implementing this web service have a basic

    understanding of RESTful services, and W3C protocol standards.

    Web Services API Requirements

    The web services API requirements are defined as any other miscellaneous parameters that areobligated to be given in the request sent to the web service. Failure to provide these parameters

    correctly will result in a failure to process and/or verify the client's request.

    The URL for each service is required for each request.

    A web service API key must be specified. Keys are granted by exclusively and are

    verified and validated by the web service. Failure to provide a valid key will result in

    failure to oblige the client's request. If multiple requests are attempted using an invalid

    key or no key, reserves the right to ban the client's IP from the web service entirely. For most requests, a GDB identifier will have to be specified. This is require for data

    mapping. Failure to provide this parameter will most often result in authentication

    failure, or failure to validate request.

  • 8/4/2019 00 Usage Guide

    4/21

    Section 3Generic JSON Object Formats, Request Methods, and Response Codes, etc.This section will give a generic format of JSON object templates implemented by the web service. Note

    that these are only examples.

    Request{

    "key":"123abc",

    "gdb":3,...

    }

    "key":"123abc"tells the web service that the client's access key is 123abc.

    "gdb":3 is the GDB identifier.

    ... is the input for the request being performed. For most requests, additional input

    will need to be given for the request to be fulfilled.

    Request MethodsEvery request sent to the service must have a method specified in the envelope header. The webservice request methods adhere to W3C standards. As of v1.0 (BETA) there are only four

    supported request methods: GET, POST, PUT, DELETE. For for information regarding requestmethods and header parameters, please refer to the W3C manual(http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9).

    Response (Success){

    ...

    }

    The response will have... ... is the output of the request. If not output is expected, no output will be returned.

    Response (Failure){

    "error":"Example error."

    }

    Upon failure, the response may output certain useful data, and the errors array will be populated

    with useful information as to what went wrong and how it can be fixed. Please see above forerror object information.

    In the response, the error will be the only field in the JSON object.

    "error":"Example error."is a brief explanation of what went wrong, and possiblyhow it can be fixed. The ideal way to handle errors, however, will be to handle the

    response code appropriatley.

    Response CodesEvery response from the service will have a code that will identify the status of the query. These

    response codes adhere to the W3C standard. To review a full list of these codes, and how theyshould be interpreted and handled, please refer to W3C manual

    (http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10).

    http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9
  • 8/4/2019 00 Usage Guide

    5/21

    Section 4QS4 (Quote Streamer 4) ServicesQuote Fetching

    The web service allows client's to stream live quotes in real-time.

    RequestAn example JSON object that would modify an MT4 account might look like the following.{

    "key":"abc123", "gdb":3,

    "mt4":"mt4host.example.com",

    "qs4":abc

    }

    The default required parameters are...

    "key":"123abc"tells the web service that the client's access key is 123abc.

    "gdb":3 tells the web service that the data mapping identifier to use is 3.

    "mt4":"mt4host.example.com"is the MT4 host that you would like to fetch the

    quotes from. This host is generally the public DNS of the MT4 server.

    "qs4":abcspecifies which quotes to stream. This is generally the symbol suffix that

    will designate to your brokerage and can be obtained from .The are no optional parameters.

    Request MethodThe request method to use for this type of request is GET.

    Response (Success){

    "EURUSD":

    {

    },

    ...

    }

    "ask":1.01234,

    "bid":1.01233,

    "status":true,

    "year":2011,

    "month":1,

    "day":1,

    "hour":0,

    "minute":0,

    "second":0

    The response will have...

    "EURUSD":{...}is the symbol that the quote is for. It is an object that will contain

    information regarding the quote, such as prices, status, and time-stamp data. "ask":1.01234is the quoted ask price for the symbol.

    "bid":1.01233 is the quoted bid price for the symbol.

    "status":true is a boolean representation of the current status of the quote (true = up,

  • 8/4/2019 00 Usage Guide

    6/21

    false = down).

    "year":2011 is the year that the quote was last updated (in real-time).

    "month":1 is the month that the quote was last updated (in real-time).

    "day":1 is the day that the quote was last updated (in real-time).

    "hour":0 is the hour that the quote was last updated (in real-time).

    "minute":0 is the minute that the quote was last updated (in real-time).

    "second":0 is the second that quote was last updated (in real-time). ... means that the response will contain a quote object for each symbol fetched.

    Response (Failure){

    "error":"Example error."

    }

    Upon failure, the response will contain an error field with useful information on what wentwrong. Please see above for error handling.

    In the response, the errors array will be populated with error message, like this one above.

    "error":"Example error."is a brief explanation of what went wrong, and possiblyhow it can be fixed.

    Response CodeA successful execution of the query will respond with code 200 (OK). For all other response

    codes, please refer to W3C manual (http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10).

    http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10
  • 8/4/2019 00 Usage Guide

    7/21

    Section 5WR4 (Web Registration 4) Services ~DeprecatedAccount Creation ~ Deprecated

    This section describes how to utilize the web service to create an MT4 account. The account

    will be created via MT4's Web Registration plug-in.

    Note: This functionality is deprecated and should not be utilized. Instead, the MT4 servicesshould be used for account creation.

    URL

    RequestAn example JSON object that would create an MT4 account might look like the following.{

    "key":"abc123", "gdb":3,

    "mt4":"mt4host.example.com",

    "name":"Dr. Example Sample Sr.",

    "email":"[email protected]",

    "phone":"555-555-5555",

    "address":"1 Example Road",

    "city":"Exampleville",

    "state":"Examplefornia",

    "zip_code":"01234",

    "country":"United State of Examples",

    "password":"Example123",

    "enabled":false,

    "group":"exampleGroup",

    "trading_enabled":true,

    "reports_enabled":false,

    "leverage":100,

    "balance":0

    }

    The default required parameters are... "key":"123abc"tells the web service that the client's access key is 123abc.

    "gdb":3 tells the web service that the data mapping identifier to use is 3.

    "mt4":"mt4host.example.com"is the MT4 host that you would like to create the new

    account in. This host is generally the public DNS of the MT4 server.

    "group":"exampleGroup"specifies which MT4 group to create this account in. Thisvalue must be a non-empty string that is the valid name of the MT4 group. This value is

    case-sensitive.

    The optional parameters are...

    "name":"Dr. Example Sample Sr." is the name of the person who will be trading

    under this account. As of v1.0 there is no restriction on what the value of this parameter

    is; however, it will be forced to type string. If not specified, this value will default to anempty string.

    "email":"[email protected]"is the account holder's email address. As of v1.0there is no restriction on what the value of this parameter is; however, it will be forced

    to type string. If not given in the request input, this value will default to an empty

    string.

    "phone":"555-555-5555"is the account holder's phone number. As of v1.0 there is norestriction on what the value of this parameter is; however, it will be forced to type

    mailto:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]
  • 8/4/2019 00 Usage Guide

    8/21

    string. If not specified in the request input, this value defaults to an empty string.

    "address":"1 Example Road"is the account holder's address field. As of v1.0 there isno restriction on what the value of this parameter is; however, it will be forced to type

    string. If not specified in the request input, this value defaults to an empty string.

    "city":"Exampleville"is the account holder's city or town. As of v1.0 there is norestriction on what the value of this parameter is; however, it will be forced to type

    string. If not specified, this value defaults to an empty string. "state":"Examplefornia"is the account holder's state or province. As of v1.0 there

    is no restriction on what the value of this parameter is; however, it will be forced to typestring. If not specified, this value defaults to an empty string.

    "zip_code":"01234"is the account holder's zip or postal code. As of v1.0 there is no

    restriction on what the value of this parameter is; however, it will be forced to typestring. If not specified, this value will default to an empty string.

    "country":"United State of Examples"is the account holder's country. As of v1.0

    there is no restriction on what the value of this parameter is; however, it will be forcedto type string. If not specified, this value will default to an empty string.

    "password":"Example123"is the password that will allow the account holder to login

    to their MT4 account via MetaQuotes products. If specified in the request input, this

    value must be a non-empty string, 8 to 20 characters long, and must include acombination of upper-case, lower-case, and numeric characters. If not specified in the

    request input, this value will be a string of 8 to 20 characters, consisting of a

    combination of upper-case, lower-case, and numeric characters.

    "enabled":falseis a flag that will be used to decide if the account will be enabled for

    activity, including logging in via MetaQuotes software, as well as all other activity. As

    of v1.0 there is no restriction on what the value of this parameter is; however, it will beforced to type boolean (true or false). If not specified in the request input, this value

    will default to true.

    "trading_enabled":false is a flag that will be used to decide if the account will be

    enabled for trading activity. As of v1.0 there is no restriction on what the value of this

    parameter is; however, it will be forced to type boolean (true or false). If not specifiedin the request input, this value will default to true.

    "reports_enabled":false is a flag that will be used to decide if the account will beenabled for receiving reports. As of v1.0 there is no restriction on what the value of this

    parameter is; however, it will be forced to type boolean (true or false). If not specified

    in the request input, this value will default to false.

    leverage:100 is the leverage on the account. As of v1.0 there is no restriction on what

    the value of this parameter is; however, it will be forced to type int. If not specified in

    the request input, this value will default to 0.

    balance:0 is the balance on the account. As of v1.0 there is no restriction on what the

    value of this parameter is; however, it will be forced to a numeric type. If not specifiedin the request input, this value will default to 0.

    Request Method

    The request method to use for this type of request is PUT.

    Response (Success){

    "login":123456789,

    "password":"Example123"

  • 8/4/2019 00 Usage Guide

    9/21

    }

    The response will have...

    "login":123456789is the new account's login number. This login number is generated

    automatically by the MT4 server. The client nor the web service has control over what

    this number will be.

    "password":"Example123"is the new account's password. If the client specifies apassword in the request input, that same password will be returned to the client via the

    response output.

    Response (Failure){

    "error":"Example error."

    }

    Upon failure, the response will contain an error field with useful information on what went

    wrong. Please see above for error handling.

    In the response, the errors array will be populated with error message, like this one above. "error":"Example error."is a brief explanation of what went wrong, and possibly

    how it can be fixed.

    Response Code

    A successful execution of the query will respond with code 201 (CREATED). For all otherresponse codes, please refer to W3C manual

    (http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10 ).

    http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10
  • 8/4/2019 00 Usage Guide

    10/21

    Section 6GDB (Global Database) ServicesAccount Fetching

    The web service allows client's access to their accounts.

    URL

    RequestAn example JSON object that would modify an MT4 account might look like the following.{

    "key":"abc123", "gdb":3,

    "mt4":"mt4host.example.com",

    "login":123456789

    }

    The default required parameters are... "key":"123abc"tells the web service that the client's access key is 123abc.

    "gdb":3 tells the web service that the data mapping identifier to use is 3.

    "mt4":"mt4host.example.com"is the MT4 host that you would like to fetch the

    account from. This host is generally the public DNS of the MT4 server. "login":123456789specifies which MT4 account to fetch. This value must be a validMT4 account login number and must represent an account that belongs to the client.

    The are no optional parameters.

    Request MethodThe request method to use for this type of request is GET.

    Response (Success){

    "login":123456789,

    "name":"Dr. Example Sample Sr.",

    "email":"[email protected]"

    ,

    "phone":"555-555-5555",

    "address":"1 Example Road",

    "city":"Exampleville",

    "state":"Examplefornia",

    "zip_code":"01234",

    "country":"United State of Examples",

    "enabled":false,

    "leverage":100,

    "balance":1

    }

    The response will have...

    "login":123456789is the account's login number. "name":"Dr. Example Sample Sr."is the account holder's name.

    "email":"[email protected]"is the account holder's email address.

    "phone":"555-555-5555" is the account holder's phone number.

    "address":"1 Example Road" is the account holder's postal address.

    "city":"Exampleville" is the account holder's city.

    "state":"Examplefornia" is the account holder's state.

    mailto:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]
  • 8/4/2019 00 Usage Guide

    11/21

    "zip_code":"01234" is the account holder's zip code.

    "country":"United State of Examples" is the account holder's country.

    "enabled":false is the account's enabled status.

    "leverage":100 is the account's leverage.

    "balance":1 is the account's balance.

    Response (Failure){

    "error":"Example error."

    }

    Upon failure, the response will contain an error field with useful information on what wentwrong. Please see above for error handling.

    In the response, the errors array will be populated with error message, like this one above.

    "error":"Example error."is a brief explanation of what went wrong, and possibly

    how it can be fixed.

    Response CodeA successful execution of the query will respond with code 200 (OK). For all other response

    codes, please refer to W3C manual (http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10).

    Broker FetchingThe web service allows client's access to their broker information.

    URL

    Request

    An example JSON object that would modify an MT4 account might look like the following.{

    "key":"abc123",

    "gdb":3

    }

    The default required parameters are...

    "key":"123abc"tells the web service that the client's access key is 123abc.

    "gdb":3 tells the web service that the data mapping identifier to use is 3.

    The are no optional parameters.

    Request MethodThe request method to use for this type of request is GET.

    Response (Success){

    "name":"My Brokerage",

    "description":"This is my brokerage.",

    "prefix":XXX

    }

    http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10
  • 8/4/2019 00 Usage Guide

    12/21

    The response will have...

    "name":"myGroup1"is the group name.

    "currency":"USD" is the group default base currency.

    "deposit":0 is the group default deposit amount.

    "leverage":100 is the group default leverage value.

    "enabled":false is the group's enabled status.

    "signature":"This is my group." is the group company signature.

    Response (Failure){

    "error":"Example error."

    }

    Upon failure, the response will contain an error field with useful information on what went

    wrong. Please see above for error handling.

    In the response, the errors array will be populated with error message, like this one above.

    "error":"Example error."is a brief explanation of what went wrong, and possibly

    how it can be fixed.

    Response CodeA successful execution of the query will respond with code 200 (OK). For all other response

    codes, please refer to W3C manual (http://www.w3.org/Protocols/rfc2616/rfc2616-

    sec10.html#sec10).

    Group FetchingThe web service allows client's access to their MT4 groups.

    URL

    RequestAn example JSON object that would modify an MT4 account might look like the following.{

    "key":"abc123", "gdb":3,

    "mt4":"mt4host.example.com",

    "name":"myGroup1"

    }

    The default required parameters are...

    "key":"123abc"tells the web service that the client's access key is 123abc.

    "gdb":3 tells the web service that the data mapping identifier to use is 3.

    "mt4":"mt4host.example.com"is the MT4 host that you would like to modify thenew account on. This host is generally the public DNS of the MT4 server.

    "name":"myGroup1"specifies which MT4 group to fetch. This value must be a valid

    MT4 group name and must represent a group that belongs to the client.

    The are no optional parameters.

    Request Method

    http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10
  • 8/4/2019 00 Usage Guide

    13/21

    The request method to use for this type of request is GET.

    Response (Success){

    "name":"myGroup1",

    "currency":"USD"

    }

    The response will have...

    "name":"myGroup1"is the group name.

    "currency":"USD" is the group default base currency.

    Response (Failure){

    "error":"Example error."

    }

    Upon failure, the response will contain an error field with useful information on what went

    wrong. Please see above for error handling.

    In the response, the errors array will be populated with error message, like this one above.

    "error":"Example error."is a brief explanation of what went wrong, and possiblyhow it can be fixed.

    Response CodeA successful execution of the query will respond with code 200 (OK). For all other response

    codes, please refer to W3C manual (http://www.w3.org/Protocols/rfc2616/rfc2616-

    sec10.html#sec10).

    http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10
  • 8/4/2019 00 Usage Guide

    14/21

    Section 7MT4 (Meta-Trader 4) ServicesAccount Creation

    This section describes how to utilize the web service to create an MT4 account. One thing to

    note is that, in addition to the required request parameters outlined above, in order to

    successfully implement the MT4 account creation functionality, the request will also have tworequired input parameters: MT4 host, account leverage, and the MT4 group name.

    URL

    Request

    An example JSON object that would create an MT4 account might look like the following.{

    "key":"abc123", "gdb":3,

    "mt4":"mt4host.example.com",

    "name":"Dr. Example Sample Sr.",

    "email":"[email protected]",

    "phone":"555-555-5555",

    "address":"1 Example Road",

    "city":"Exampleville",

    "state":"Examplefornia",

    "zip_code":"01234",

    "country":"United State of Examples",

    "password":"Example123",

    "enabled":false,

    "group":"exampleGroup",

    "leverage":100,

    "balance":0

    }

    The default required parameters are... "key":"123abc"tells the web service that the client's access key is 123abc.

    "gdb":3 tells the web service that the data mapping identifier to use is 3. "mt4":"mt4host.example.com"is the MT4 host that you would like to create the new

    account in. This host is generally the public DNS of the MT4 server.

    "group":"exampleGroup"specifies which MT4 group to create this account in. Thisvalue must be a non-empty string that is the valid name of the MT4 group. This value is

    case-sensitive.

    The optional parameters are...

    "name":"Dr. Example Sample Sr." is the name of the person who will be trading

    under this account. As of v1.0 there is no restriction on what the value of this parameter

    is; however, it will be forced to type string. If not specified, this value will default to anempty string.

    "email":"[email protected]"is the account holder's email address. As of v1.0there is no restriction on what the value of this parameter is; however, it will be forced

    to type string. If not given in the request input, this value will default to an emptystring.

    "phone":"555-555-5555"is the account holder's phone number. As of v1.0 there is norestriction on what the value of this parameter is; however, it will be forced to type

    string. If not specified in the request input, this value defaults to an empty string.

    "address":"1 Example Road"is the account holder's address field. As of v1.0 there is

    mailto:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]
  • 8/4/2019 00 Usage Guide

    15/21

    no restriction on what the value of this parameter is; however, it will be forced to type

    string. If not specified in the request input, this value defaults to an empty string.

    "city":"Exampleville"is the account holder's city or town. As of v1.0 there is no

    restriction on what the value of this parameter is; however, it will be forced to type

    string. If not specified, this value defaults to an empty string.

    "state":"Examplefornia"is the account holder's state or province. As of v1.0 there

    is no restriction on what the value of this parameter is; however, it will be forced to typestring. If not specified, this value defaults to an empty string.

    "zip_code":"01234"is the account holder's zip or postal code. As of v1.0 there is norestriction on what the value of this parameter is; however, it will be forced to type

    string. If not specified, this value will default to an empty string.

    "country":"United State of Examples"is the account holder's country. As of v1.0there is no restriction on what the value of this parameter is; however, it will be forced

    to type string. If not specified, this value will default to an empty string.

    "password":"Example123"is the password that will allow the account holder to loginto their MT4 account via MetaQuotes products. If specified in the request input, this

    value must be a non-empty string, 8 to 20 characters long, and must include a

    combination of upper-case, lower-case, and numeric characters. If not specified in the

    request input, this value will be a string of 8 to 20 characters, consisting of acombination of upper-case, lower-case, and numeric characters.

    "enabled":falseis a flag that will be used to decide if the account will be enabled for

    activity, including logging in via MetaQuotes software, as well as all other activity. Asof v1.0 there is no restriction on what the value of this parameter is; however, it will be

    forced to type boolean (true or false). If not specified in the request input, this value

    will default to true.

    leverage:100 is the leverage on the account. As of v1.0 there is no restriction on what

    the value of this parameter is; however, it will be forced to type int. If not specified inthe request input, this value will default to 0.

    balance:0 is the balance on the account. As of v1.0 there is no restriction on what thevalue of this parameter is; however, it will be forced to a numeric type. If not specified

    in the request input, this value will default to 0.

    Request MethodThe request method to use for this type of request is PUT.

    Response (Success){

    "login":123456789,

    "password":"Example123"

    }

    The response will have...

    "login":123456789is the new account's login number. This login number is generated

    automatically by the MT4 server. The client nor the web service has control over whatthis number will be.

    "password":"Example123"is the new account's password. If the client specifies a

    password in the request input, that same password will be returned to the client via the

    response output.

  • 8/4/2019 00 Usage Guide

    16/21

    Response (Failure){

    "error":"Example error."

    }

    Upon failure, the response will contain an error field with useful information on what went

    wrong. Please see above for error handling.

    In the response, the errors array will be populated with error message, like this one above.

    "error":"Example error."is a brief explanation of what went wrong, and possiblyhow it can be fixed.

    Response CodeA successful execution of the query will respond with code 201 (CREATED). For all other

    response codes, please refer to W3C manual (http://www.w3.org/Protocols/rfc2616/rfc2616-

    sec10.html#sec10).

    Account Modification

    Account modification includes the manipulating of client's account information, includingname, email address, phone number, postal information, password, and account deposits.

    URL

    RequestAn example JSON object that would modify an MT4 account might look like the following.{

    "key":"abc123", "gdb":3,

    "mt4":"mt4host.example.com",

    "login":123456789,

    "name":"Dr. Example Sample Sr.",

    "email":"[email protected]"

    ,

    "phone":"555-555-5555",

    "address":"1 Example Road",

    "city":"Exampleville",

    "state":"Examplefornia",

    "zip_code":"01234",

    "country":"United State of Examples",

    "password":"Example123",

    "enabled":false,

    "leverage":100,

    "deposit":1

    }

    The default required parameters are... "key":"123abc"tells the web service that the client's access key is 123abc.

    "gdb":3 tells the web service that the data mapping identifier to use is 3.

    "mt4":"mt4host.example.com"is the MT4 host that you would like to modify thenew account on. This host is generally the public DNS of the MT4 server.

    "login":123456789specifies which MT4 account to modify. This value must be a

    valid MT4 account login number and must represent an account that belongs to the

    http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10mailto:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10
  • 8/4/2019 00 Usage Guide

    17/21

    client.

    The optional parameters are...

    "name":"Dr. Example Sample Sr." is the new name of the person who will be

    trading under this account. As of v1.0 there is no restriction on what the value of this

    parameter is; however, it will be forced to type string. If not specified, this parameterwill not be modified.

    "email":"[email protected]"is the account holder's new email address. As ofv1.0 there is no restriction on what the value of this parameter is; however, it will be

    forced to type string. If not given in the request input, this parameter will not bemodified.

    "phone":"555-555-5555" is the account holder's new phone number. As of v1.0 there

    is no restriction on what the value of this parameter is; however, it will be forced to typestring. If not specified in the request input, this parameter will not be modified.

    "address":"1 Example Road"is the account holder's new postal address. As of v1.0

    there is no restriction on what the value of this parameter is; however, it will be forcedto type string. If not specified in the request input, this parameter will not be modified.

    "city":"Exampleville"is the account holder's new city or town. As of v1.0 there is

    no restriction on what the value of this parameter is; however, it will be forced to type

    string. If not specified, this parameter will not be modified.

    "state":"Examplefornia" is the account holder's new state or province. As of v1.0

    there is no restriction on what the value of this parameter is; however, it will be forced

    to type string. If not specified, this parameter will not be modified.

    "zip_code":"01234"is the account holder's new zip or postal code. As of v1.0 there is

    no restriction on what the value of this parameter is; however, it will be forced to type

    string. If not specified, this parameter will not be modified.

    "country":"United State of Examples"is the new account holder's country. As of

    v1.0 there is no restriction on what the value of this parameter is; however, it will be

    forced to type string. If not specified, this parameter will not be modified.

    "password":"Example123"is the new password that will allow the account holder to

    login to their MT4 account via MetaQuotes products. If specified in the request input,

    this value must be a non-empty string, 8 to 20 characters long, and must include acombination of upper-case, lower-case, and numeric characters. If not specified in the

    request input, this parameter will not be modified.

    "enabled":false is a flag that will be used to decide if the account will be enabled foractivity, including logging in via MetaQuotes software, as well as all other activity. As

    of v1.0 there is no restriction on what the value of this parameter is; however, it will be

    forced to type boolean (true or false). If not specified in the request input, thisparameter will not be modified.

    "leverage":100 is the new leverage value on the account. As of v1.0 there is no

    restriction on what the value of this parameter is; however, it will be forced to type int.

    If not specified in the request input, this parameter will not be modified.

    "deposit":1 is the amount of currency to deposit into the account. As of v1.0 there is no

    restriction on what the value of this parameter is; however, it will be forced to a numerictype. If not specified in the request input, no deposit will be made.

    Request Method

    The request method to use for this type of request is POST.

    mailto:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]
  • 8/4/2019 00 Usage Guide

    18/21

    Response (Success){

    "login":123456789,

    "name":"Dr. Example Sample Sr.",

    "email":"[email protected]",

    "phone":"555-555-5555",

    "address":"1 Example Road",

    "city":"Exampleville",

    "state":"Examplefornia",

    "zip_code":"01234",

    "country":"United State of Examples",

    "enabled":false,

    "leverage":100,

    "balance":1

    }

    The response will have...

    "login":123456789is the account's login number.

    "name":"Dr. Example Sample Sr."is the account's new name, or the old name if thevalue was not modified.

    "email":"[email protected]"is the account's new email, or the old email if the valuewas not modified.

    "phone":"555-555-5555" is the account's new phone number, or the old value if the

    value was not modified.

    "address":"1 Example Road" is the account's new address, or the old address if the valuewas not modified.

    "city":"Exampleville" is the account's new city, or the old city if the value was not

    modified.

    "state":"Examplefornia" is the account's new state, or the old state if the value was not

    modified.

    "zip_code":"01234" is the account's new zip_code, or the old zip_code if the value wasnot modified.

    "country":"United State of Examples" is the account's new country, or the old country ifthe value was not modified.

    "enabled":false is the account's new enabled flag, or the old enabled flag value if thevalue was not modified.

    "leverage":100 is the account's new leverage, or the old leverage if the value was not

    modified.

    "balance":1 is the account's new balance, or the old balance if no deposit was given.

    Response (Failure)

    {"error":"Example error."

    }

    Upon failure, the response will contain an error field with useful information on what wentwrong. Please see above for error handling.

    In the response, the errors array will be populated with error message, like this one above.

    "error":"Example error."is a brief explanation of what went wrong, and possibly

    how it can be fixed.

    mailto:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]
  • 8/4/2019 00 Usage Guide

    19/21

    Response CodeA successful execution of the query will respond with code 200 (OK). For all other response

    codes, please refer to W3C manual (http://www.w3.org/Protocols/rfc2616/rfc2616-

    sec10.html#sec10).

    Account FetchingThe web service allows client's access to their accounts.

    URL

    RequestAn example JSON object that would modify an MT4 account might look like the following.{

    "key":"abc123", "gdb":3,

    "mt4":"mt4host.example.com",

    "login":123456789

    }

    The default required parameters are...

    "key":"123abc"tells the web service that the client's access key is 123abc.

    "gdb":3 tells the web service that the data mapping identifier to use is 3.

    "mt4":"mt4host.example.com"is the MT4 host that you would like to fetch theaccount from. This host is generally the public DNS of the MT4 server.

    "login":123456789specifies which MT4 account to fetch. This value must be a valid

    MT4 account login number and must represent an account that belongs to the client.The are no optional parameters.

    Request Method

    The request method to use for this type of request is GET.

    Response (Success){

    "login":123456789,

    "name":"Dr. Example Sample Sr.",

    "email":"[email protected]",

    "phone":"555-555-5555",

    "address":"1 Example Road",

    "city":"Exampleville",

    "state":"Examplefornia",

    "zip_code":"01234",

    "country":"United State of Examples",

    "enab

    led

    ":false,

    "leverage":100,

    "balance":1

    }

    The response will have...

    "login":123456789is the account's login number.

    "name":"Dr. Example Sample Sr."is the account holder's name.

    http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10mailto:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10
  • 8/4/2019 00 Usage Guide

    20/21

    "email":"[email protected]"is the account holder's email address.

    "phone":"555-555-5555" is the account holder's phone number.

    "address":"1 Example Road" is the account holder's postal address.

    "city":"Exampleville" is the account holder's city.

    "state":"Examplefornia" is the account holder's state.

    "zip_code":"01234" is the account holder's zip code.

    "country":"United State of Examples" is the account holder's country. "enabled":false is the account's enabled status.

    "leverage":100 is the account's leverage.

    "balance":1 is the account's balance.

    Response (Failure){

    "error":"Example error."

    }

    Upon failure, the response will contain an error field with useful information on what went

    wrong. Please see above for error handling.

    In the response, the errors array will be populated with error message, like this one above.

    "error":"Example error."is a brief explanation of what went wrong, and possiblyhow it can be fixed.

    Response Code

    A successful execution of the query will respond with code 200 (OK). For all other responsecodes, please refer to W3C manual (http://www.w3.org/Protocols/rfc2616/rfc2616-

    sec10.html#sec10).

    Group FetchingThe web service allows client's access to their MT4 groups.

    URL

    Request

    An example JSON object that would modify an MT4 account might look like the following.{

    "key":"abc123", "gdb":3,

    "mt4":"mt4host.example.com",

    "name":"myGroup1"

    }

    The default required parameters are...

    "key":"123abc"tells the web service that the client's access key is 123abc.

    "gdb":3 tells the web service that the data mapping identifier to use is 3.

    "mt4":"mt4host.example.com"is the MT4 host that you would like to modify thenew account on. This host is generally the public DNS of the MT4 server.

    "name":"myGroup1"specifies which MT4 group to fetch. This value must be a valid

    MT4 group name and must represent a group that belongs to the client.

    mailto:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]:[email protected]://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10mailto:[email protected]
  • 8/4/2019 00 Usage Guide

    21/21

    The are no optional parameters.

    Request MethodThe request method to use for this type of request is GET.

    Response (Success){

    "name":"myGroup1",

    "currency":"USD",

    "deposit":0,

    "leverage":100,

    "enabled":true,

    "signature":"This is my group."

    }

    The response will have... "name":"myGroup1"is the group name.

    "currency":"USD" is the group default base currency.

    "deposit":0 is the group default deposit amount.

    "leverage":100 is the group default leverage value.

    "enabled":false is the group's enabled status.

    "signature":"This is my group." is the group company signature.

    Response (Failure){

    "error":"Example error."

    }

    Upon failure, the response will contain an error field with useful information on what wentwrong. Please see above for error handling.

    In the response, the errors array will be populated with error message, like this one above.

    "error":"Example error."is a brief explanation of what went wrong, and possibly

    how it can be fixed.

    Response Code

    A successful execution of the query will respond with code 200 (OK). For all other responsecodes, please refer to W3C manual (http://www.w3.org/Protocols/rfc2616/rfc2616-

    sec10.html#sec10).

    http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10