REST trading API guide

Overview

REST (Representational State Transfer) is the standard way of accessing resources over the web. It is done through four standard HTTP operations:

  • GET
  • POST (create)
  • PUT (update)
  • DELETE

For example, when you enter http://www.ig.com into the browser address bar, the browser issues a GET HTTP request on the web page resource at that address, and returns a web page as a response. Similarly, in the case of our API, a GET HTTP request to https://api.ig.com/gateway/deal/positions would return a list of open positions on the active account.

The R in REST refers to the representation (or format) of the resource being accessed. In our case, it is the web-standard JSON (JavaScript Object Notation) format.

If you have an IG demo account, we recommend that you run the sample application on the left, logging in using your demo account, and selecting 'Show HTTP' to see the API HTTP requests and responses in action.

HTTP requests

Section Component
ActionHTTP operation GET - retrieve a resource
PUT - replace a resource
POST - create a resource
DELETE - delete a resource
HTTPSThe secure web protocol. It ensures that requests are encrypted between the application and the API
demo-api.ig.com/gateway/dealThe API gateway location. Use api.ig.com instead of demo-api.ig.com for live account access
/positionsThe address of the resource you are accessing, positions in this case
Request Header X-IG-API-KEY: kThe API key k (obtained from My Account on our dealing platform) is how we identify and authorise the calling application
CST / AuthorizationA valid access token identifying the client.
X-SECURITY-TOKEN / IG-ACCOUNT-IDA valid account token or account id identifying the client's current account.
Content-Type: application/json Request format type. This should always be set as indicated to json only
Accept: application/json; charset=UTF-8 Response format type. This should always be set as indicated to json only
Version: v API version v (defaults to 1, if not specified)
Request Body Only required for PUT or POST requestsJSON format

Authentication and authorisation

There are currently two mechanisms for logging into and accessing the API.

  • POST /session v1 and v2 return a CST header with a token identifying a client and an X-SECURITY-TOKEN header with a token identifying the current account. These headers should be passed on subsequent requests to the API. Both tokens are initially valid for 6 hours but get extended up to a maximum of 72 hours while they are in use.

  • POST /session v3 returns OAuth access and refresh tokens which the user can pass in subsequent API requests via the Authorization header, e.g.:

    Authorization : Bearer 5d1ea445-568b-4748-ab47-af9b982bfb74

    The access token only identifies the client so users should also pass an IG-ACCOUNT-ID header to specify the account the request applies to, e.g.:

    IG-ACCOUNT-ID : PZVI2

    The access token is only valid for a limited period of time (e.g. 60 seconds) specified by the login response.
    "oauthToken": { "access_token": "702f6580-25c7-4c04-931d-6000efa824f8", "refresh_token": "a9cec2d7-fd01-4d16-a2dd-7427ef6a471d", "scope": "profile", "token_type": "Bearer", "expires_in": "60" }
    The refresh token can used to acquire a new access token, either before or after the access token has expired but please note that the refresh token does also expiry some time after the access token has expired (e.g. 10 minutes). A call to refresh an access token will also return a new refresh token.The scope for individual clients is always profile which allows full access to the user's account.

FIQL query filters

FIQL (https://tools.ietf.org/html/draft-nottingham-atompub-fiql-00) defines a syntax for expressing filters on entries of a web feed so it can be used to query resources. The activity history is one of the endpoints supporting this syntax and provide a way to query activities, e.g.:

"filter" : "status==ACCEPTED;(channel==PUBLIC_WEB_API,channel==PUBLIC_FIX_API);details.actions.actionType==WORKING_ORDER_DELETED"
This query returns all activity history item representing a cancelled order either via the public Web or FIX API.

HTTP response

Section Component
Response Header
X-REQUEST-IDIdentifies the request
HTTP status code
200request executed fine
401access denied
500server failure
...
Response Body Request results, if any. JSON format. In the event of an error, the body will be of the form:
{ "errorCode" : "the error code" }

Paging

Paging applies to a subset of endpoints returning a list of entries, such as e.g. historical data. A metadata section on the response should provide paging details:

"metadata": { "paging": { "next": "/history/activity?version=3&from=2016-05-27T00:00:00&to=2016-05-27T09:04:49&detailed=true&pageSize=10" } }
In this case "next" will provide a link to retrieve the next page of data.

Errors

Error responses contain a 4xx or 5xx HTTP status and a body with the following format:

{ "errorCode": "the error code" }
User errors caused by e.g. malformed json or invalid requests will be returned as HTTP 4xx errors. The suffix of error codes in validation failures can change depending on the request field that caused the failure, e.g. "invalid.request.forceOpen" indicates that the value on request field "forceOpen" was invalid.