Accounts API

The following part of the guide describes the Accounts API.

Accounts API is based on RESTful API operating via HTTP request/responses. You just generate a simple GET request and get a response in text JSON format.

A list of OAuth RESTful web services is below.

Access token should be passed as a query string using access_token or oauth_token parameter (?access_token=YOUR_ACCESS_TOKEN) for all web-services that requires authorization.

Web services that support cursors (you can identify them by the CursorMessage response) accept following parameters (passed inside query string parameter list):

  • cursor - (optional) start from a specific position in result set. If omitted - starting from most recent entries. You will get cursor from CursorMessage.
  • limit - (optional) return up to limit of entries (default=25, min=25, max=750).
  • fromTimestamp - (optional) lower bound of time period. Inclusive in milliseconds since 1970-01-01 00:00:00 UTC+0.
  • toTimestamp - (optional) upper bound of time period. Also inclusive.

Example:

/connect/tradingaccounts/45654789/deals?limit=100&cursor=123123_987987987/

If query contains at least one of timestamps and cursor then cursor is ignored and server starts returning a new result set. So to get full range of data from 2013-07-01 to 2013-08-01 client needs to send following set of queries:

/connect/tradingaccounts/45654789/deals?limit=40&fromTimestamp=1372654800000&toTimestamp=1375333200000
/connect/tradingaccounts/45654789/deals?limit=20&cursor={value_of_next_from_previous_response}
…
/connect/tradingaccounts/45654789/deals?limit=159&cursor={value_of_next_from_previous_response}
Section Operation URL HTTP
Method
Request Response Res. HTTP Status Code Require Authorization
General JSON schema /connect/schema GET Text document 200 N
Profile Profile details /connect/profile GET MessageJson 200, 400, 404 Y
Trading Accounts Trading accounts /connect/tradingaccounts GET MessageJson<TradingAccountJson[]> 200, 400 Y
Trading Accounts Deals /connect/tradingaccounts/{id}/deals GET {id} - id of trading account to get deals for, ordered by createTimestamp CursorMessageJson<DealJson[]> 200, 400, 404 Y
Trading Accounts Cashflow history /connect/tradingaccounts/{id}/cashflowhistory GET {id} - id of trading account to get history for, ordered by changeTimestamp CursorMessageJson<CashflowJson[]> 200, 400, 404 Y
Trading Accounts Pending orders /connect/tradingaccounts/{id}/pendingorders GET {id} - id of trading account to get orders for, {limit} defaults to 750, ordered by createTimestamp CursorMessageJson<PendingOrderJson[]> 200, 400, 404 Y
Trading Accounts Positions /connect/tradingaccounts/{id}/positions GET {id} - id of trading account to get positions for, {limit} defaults to 750, ordered by entryTimestamp CursorMessageJson<PositionJson[]> 200, 400, 404 Y
Trading Accounts Symbols /connect/tradingaccounts/{id}/symbols GET {id} - id of trading account to get symbols for MessageJson<SymbolJson[]> 200, 400, 404 Y
Trading Accounts Tick data /connect/tradingaccounts/{id}/symbols/{symbolName}/[bid|ask] GET {id} - id of trading account to get tick data for {symbolName} - name of a symbol to get data for.
Additional parameters: date - a date for which tick data set is returned. Date pattern is YYYYMMDD (e.g. /?date=20130716).
from - start time of the requested set within specified day. Time pattern is HHMMSS (e.g. /?from=071346).
to - end time of the requested set within specified day. Time pattern is HHMMSS (e.g. /?to=075332).
Note: max number of returned quotes by a single request is 5000.
Note: Timezone of requested timestamp is UTC+00
MessageJson<TickDataJson[]> 200, 400, 404 Y
Trading Accounts Trendbars /connect/tradingaccounts/{id}/symbols/{symbolName}/trendbars/[h1|m1] GET {id} - id of trading account to get tick data for.
{symbolName} - name of a symbol to get data for.
Additional parameters:
from - start time of the requested set within specified day. Time pattern is YYYYMMDDHHMMSS (e.g. /?from=20130716071346).
to - end time of the requested set within specified day. Time pattern is YYYYMMDDHHMMSS (e.g. /?to=20130716075332).
Note: max number of returned trendbars by a single request is 5000
Note: Timezone of requested timestamp is UTC+00
Note: both to and from should not be in future
MessageJson<TrendbarJson[]> 200, 400, 404 Y
Trading Accounts Demo account creation and linking /connect/tradingaccounts/createdemo POST CreateDemoTradingAccountReqJson MessageJson 200, 400, 404 Y
Trading Accounts Deposit (demo only) /connect/tradingaccounts/{id}/deposit POST DepositWithdrawReqJson in payload and {id} of the trading account to deposit in URL MessageJson 200, 400, 404 Y
Trading Accounts Withdraw (demo only) /connect/tradingaccounts/{id}/withdraw POST DepositWithdrawReqJson in payload and {id} of the trading account to withdraw in URL MessageJson 200, 400, 404 Y

The content type for requests and responses is application/json. All parameters passed in URL should be encoded using application/x-www-form-urlencoded MIME format.

Web Services responses may have the following HTTP status codes:

HTTP Status Code Description
200 (OK) Operation performed successfully
400 (Bad Request) Client side or validation errors (e.g. invalid input, validation error, invalid URL, etc). Response body will contain the error code.
404 (Not Found) Requested entity was not found. Response body will contain the error code.
500 (Internal Server Error) Internal server error. Response body will contain the status code.

In case of error, response body will contain the error details. This is the list of possible errors:

Error Description
UNKNOWN_ERROR Server internal error.
INVALID_REQUEST Client invalid request (request validation failure).
CH_INSUFFICIENT_PERMISSIONS The request requires higher privileges than provided by the access token.
CH_ACCESS_TOKEN_INVALID The access token provided is invalid.
CH_CURSOR_INVALID Invalid cursor.
CH_CTID_NOT_FOUND cTID for the given access token or with the given userId or login(email or nickname) was not found.
CH_CTID_TRADER_ACCOUNT_NOT_FOUND Trading account with the given id was not found.
CH_SYMBOL_NOT_FOUND Symbol with the given id was not found.
CH_DEPOSIT_CURRENCY_INVALID Deposit currency with the given name is invalid.
CH_TRADER_ACCOUNT_NOT_FOUND Linked trader account is not found on trading server. (e.g. it may be deleted by broker)