Streaming API Guide

Our streaming API enables you to stream real-time:

  • Market prices
  • Trade notifications
  • Account status notifications

To get started you will need to first download the Lightstreamer client library for your programming platform.

It is recommended that you read our REST API guide before using our streaming API in order to understand the process of obtaining secure connection tokens.

Concepts

Connect

To connect to an IG streaming server you’ll need to specify the following:

Element Value
Lightstreamer Server Lightstreamer server address returned by the /session API. This may be subject to change so should not be hard-coded
Identifier Active account identifier
Password CST-CST token|XST-X-SECURITY-TOKEN token, tokens obtained on login via the REST /session service
Callback Function Optional function that will receive any Lightstreamer connection notifications

NOTE: The streaming API currently does not accept OAuth tokens so users holding OAuth bearer tokens should call GET /session?fetchSessionTokens=true to obtain CST and X-SECURITY-TOKEN tokens.

Subscribe

To subscribe for price or account updates, a subscription request must be made to Lightstreamer. A subscription request consists of:

  • A list of items (eg IG market identifiers)
  • A list of fields relevant to those items (eg BID, ASK)

Multiple subscriptions can be made, but each subscription may only contain items of one type. By default, up to 40 simultaneous subscriptions per connection may be created. Whilst it’s possible to increase this number by connecting more than once, this is a breach of IG’s terms and conditions and may result in your API permissions being revoked. Please contact us if you need to increase your usage quotas.

A Lightstreamer connection needs an active thread to stream data so it is important for applications to establish connections in separate threads. Creating multiple Lightstreamer connections on the main thread may cause connections to drop intermittently. The Lightstreamer client should also have the ability to reconnect in the event of a connection failure or if instructed by the Lightstreamer server (e.g. due to a LOOP rebind message). A re-connection attempt can fail if the CST and X-SECURITY-TOKEN tokens have expired in which case it will be necessary to re-authenticate to obtain new security tokens.

The full list of available subscription item identifiers and fields can be found here.

Example - Javascript Lightstreamer code

Connect

function connectToLightstreamer(){ // include the Lightstreamer LightstreamerClient module using require.js require(["LightstreamerClient"], function (LightstreamerClient) { // Instantiate Lightstreamer client instance lsClient = new LightstreamerClient(lsEndpoint); // Set up login credentials lsClient.connectionDetails.setUser(activeAccountId); lsClient.connectionDetails.setPassword("CST-" + client_token + "|XST-" + account_token); // Add connection event listener callback functions // Note: the Lightstreamer library will transparently attempt to reconnect a number of times // in the event of communicationss errors lsClient.addListener({ onListenStart: function() { console.log('ListenStart'); }, onStatusChange: function(status) { console.log('Lightstreamer connection status:' + status); } }); // Connect to Lightstreamer lsClient.connect(); }); }

Create a subscription

Each Lightstreamer subscription requires:

  • A Lightstreamer connection
  • A subscription type - only DISTINCT or MERGE are supported*
  • A list of items of the same type (ie price, account or epic). For example, a list of instrument EPICs in the case of a price subscription
  • The desired fields for those items

* DISTINCT indicates that each update should yield a notification and is required for trade notifications. MERGE indicates that updates occurring very close together should only yield one update, and is used for account and price notifications to regulate the update rate)

For example:

function connectToLightstreamer(itemList, fieldList){ // include the Lightstreamer Subscription module using require.js require(["Subscription"], function (Subscription) { var subscription = new Subscription( "MERGE", itemList, // e.g. {"MARKET:IX.D.FTSE.DAILY.IP","MARKET:MT.D.GC.MONTH1.IP"} fieldList // e.g. {"BID", "OFFER"} ); // Set up Lightstreamer event listener subscription.addListener({ onSubscription: function () { console.log('subscribed'); }, onUnsubscription: function () { console.log('unsubscribed'); }, onSubscriptionError: function (code, message) { console.log('subscription failure: ' + code + " message: " + message); }, onItemUpdate: function (updateInfo) { // Lightstreamer published some data var epic = updateInfo.getItemName().split(":")[1]; updateInfo.forEachField(function (fieldName, fieldPos, value) { console.log('Field: ' + fieldName + " Value: " + value); // Alternatively, if the field is JSON, such as in a confirm message: var confirm = JSON.parse(value); console.log('json: ' + confirm.dealId) } }); } }); // Subscribe to Lightstreamer lsClient.subscribe(subscription); }

If a subscription is no longer required, it can be removed at any time by unsubscribing. For example:

lsClient.unsubscribe(subscription); lsClient.closeConnection();