Minimalistic wrapper around IG's API

• Installation
• Usage
• Instance API
  • constructor
  • login
  • logout
  • request
  • get
  • post
  • put
  • delete
• Static API
  • IG.transformResponse
  • IG.transformError
  • IG.uniqueId
• Options
• Errors
• Promises
• Testing

Install

yarn add ig-api

Usage

import IG from 'ig-api'

const ig = new IG(apiKey, isDemo)

// Using promises
ig.login(username, password)
  // Response data is automatically
  // passed to the resolve callback
  .then((summary) => {
    console.log('summary:', summary)
    // Once logged in, use the shorthand
    // get(), post(), put() and delete()
    // methods to interact with IG's API
    ig.get('positions')
      .then((positions) => {
        console.log('positions:', positions)
      })
  })
  // Errors are automatically transformed
  // into a more user friendly format with
  // the response status and IG error code
  .catch(console.error)

// Using async await
try {
  await ig.login(username, password)
  const positions = await ig.get('positions')
  console.log('positions:', positions)
} catch (error) {
  console.error(error)
}

Instance API

// ES6 Module
import IG from 'ig-api'

// Common JS
const IG = require('ig-api')

The IG class is a minimalistic wrapper around axios—a Promise based HTTP client that works in browsers and node. IG class instances take care of setting the request URL, headers and authentication tokens when logging into an account.

Responses and errors are automatically transformed into a more user friendly format, though this can be customised or disabled if desired. See options for more information.

constructor(apiKey, isDemo, options)

parameter | type | required | description ----------|---------|----------|------------ apiKey | string | true | Application API key isDemo | boolean | false | Is the API key associated with a demo account? Defaults to false options | object | false | See options for more information

login(username, password, encryptPassword, options)

parameter | type | required | description ----------------|---------|----------|------------ username | string | true | Account user name password | string | true | Account password encryptPassword | boolean | false | Encrypt password before posting to API. Defaults to false options | object | false | See options for more information

logout(options)

parameter | type | required | description ----------|---------|----------|------------ options | object | false | See options for more information

request(method, path, version, config, options)

parameter | type | required | description ----------|---------|----------|------------ method | string | true | Request method to use ('get', 'post', 'put' or 'delete') path | string | true | Endpoint path eg. 'history/transactions' version | number | false | Endpoint version (1, 2 or 3). Defaults to 1 config | object | false | Request config to pass to axios. See documentation options | object | false | See options for more information

get(path, version, params, options)

Shorthand to request, passing 'get' as the method and params as the key value to config.

// Get detailed account activity since 25th December 2016
ig.get('history/activity', 3, {
  from: '2016-12-25',
  detailed: true
})
// ...is the same as
ig.request('get', 'history/activity', 3, {
  params: {
    from: '2016-12-25',
    detailed: true
  }
})

post(path, version, data, options)

Shorthand to request, passing 'post' as the method and data as the key value to config.

// Create a new watchlist
ig.post('watchlist', 1, {
  name: 'Forex Majors',
  epics: [
    'CS.D.AUDUSD.TODAY.IP', // AUD/USD
    'CS.D.EURGBP.TODAY.IP', // EUR/GBP
    'CS.D.EURUSD.TODAY.IP', // EUR/USD
  ]
})
// ...is the same as
ig.request('post', 'watchlist', 1, {
  data: {
    name: 'Forex Majors',
    epics: [
      'CS.D.AUDUSD.TODAY.IP', // AUD/USD
      'CS.D.EURGBP.TODAY.IP', // EUR/GBP
      'CS.D.EURUSD.TODAY.IP', // EUR/USD
    ]
  }
})

put(path, version, data, options)

Shorthand to request, passing 'put' as the method and data as the key value to config.

// Switch active account
ig.put('session', 1, {
  accountId: 'XXXXX'
})
// ...is the same as
ig.request('put', 'session', 1, {
  data: {
    accountId: 'XXXXX'
  }
})

delete(path, version, data, options)

Shorthand to request, passing 'delete' as the method and data as the key value to config.

// Close a position
ig.delete('positions/otc', 1, {
  epic: 'UA.D.AAPL.DAILY.IP', // AAPL DFB
  orderType: 'MARKET',
  direction: 'SELL',
  expiry: 'DFB',
  size: 0.5
})
// ...is the same as
ig.request('delete', 'positions/otc', 1, {
  data: {
    epic: 'UA.D.AAPL.DAILY.IP', // AAPL DFB
    orderType: 'MARKET',
    direction: 'SELL',
    expiry: 'DFB',
    size: 0.5
  }
})

Static API

IG.transformResponse(response)

parameter | type | required | description ----------|---------|----------|------------ response | object | true | Response object

Simply returns response.data.

IG.transformError(error)

parameter | type | required | description ----------|---------|----------|------------ error | object | true | Error object

Throws a new Error from error with additional key values. See errors for more detail.

IG.uniqueId(length, chars)

parameter | type | required | description ----------|---------|----------|------------ length | number | false | Length of the unique id. Defaults to 15 chars | string | false | Chars to use. Defaults to [A-Z0-9]

Creates a unique id that matches IG's format of 15 uppercase alphanumeric characters eg. ABCDE12345WVXYZ.

This can be useful when opening a new position and providing a unique dealReference.

Options

The IG constructor and all instance methods take an options argument as the final parameter.

The options object has the following shape:

{
  transformResponse: false || function(response) {
    // Transform and return a custom response
    return response
  },
  transformError: false || function(error) {
    // Transform and throw a custom error
    throw error
  }
}

Both transformResponse and transformError can be specified as functions or disabled by passing false.

By default, the built-in transform functions are used. See IG.transformResponse and IG.transformError.

When setting transformResponse to false, the original response object is returned from the request's resolve method. This is useful if you want to access the response headers or status code for example.

When setting transformError to false, the original error object is thrown from the request's reject method. This is useful if you want to access the error request or response objects and throw your own custom error.

You can also specify your own custom transform functions that map the response and error objects to whatever you so choose.

For example if you wanted to return the response data and status code for all requests on an instance and customise the error:

import IG from 'ig-api'

const ig = new IG(apiKey, isDemo, {
  transformResponse(response) {
    return {
      code: response.status,
      data: response.data
    }
  },
  transformError(error) {
    throw new Error(`Uh oh! ${error.message}`)
  }
})

const customResponse = await ig.login(username, password)
console.log(customResponse) // { code: 200, data: { ... } }

If you want to use the built-in transform functions in your own code, they are available as static properties on the IG class:

import IG from 'ig-api'

const ig = new IG(apiKey, isDemo, {
  transformResponse(response) {
    // Do something with the response...
    return IG.transformResponse(response)
  },
  transformError(error) {
    // Do something with the error...
    IG.transformError(error) // throw is called within IG.transformError
  }
})

Passing an options object to the IG constructor (as shown above) serves as a way for setting the default transform functions for all requests on that instance.

If you want to override these transformation functions on a call-by-call basis, you can do so by passing an options object when calling an instance method:

import IG from 'ig-api'

const ig = new IG(apiKey, isDemo)

// Default configuration
const summary = await ig.login(username, password)
console.log(summary) // response.data object by default

// Disable response transform on single call
const response = await ig.login(username, password, {
  transformResponse: false
})
console.log(response) // original response object

// Customise response transform on single call
const status = await ig.login(username, password, {
  transformResponse: (response) => response.status
})
console.log(status) // 200

Errors

Unless the transformError function is disabled or overridden via options, all request errors are handled by the built-in transform function.

When an error is thrown from a request, a new Error is created that has the following shape:

key | description -----------|------------ type | Either 'request', 'response' or 'internal' message | Error message url | Request url data | Request data params | Request params method | Request method headers | Request headers statusCode | Response status code (type: 'response' only) statusText | Response status text (type: 'response' only) errorCode | Response IG error code (type: 'response' only)

Using type and errorCode can be very useful for handling IG error codes within your application:

ig.login(username, password)
  .catch((error) => {
    if (error.type === 'response') {
      switch (error.errorCode) {
        case 'error.security.invalid-details':
          alert('Incorrect username or password')
          break;
        default:
          console.error(error.errorCode)
          break;
      }
    } else {
      console.error(error.message)
    }
  })

Promises

This library depends on a native ES6 Promise implementation to be supported.

If your environment doesn't support ES6 Promises, you can polyfill.

Testing

To run the tests locally, you will need to create a .env file at the root of the repository that contains the following:

DEMO_API_KEY=yourDemoApiKey
DEMO_USERNAME=yourDemoUsername
DEMO_PASSWORD=yourDemoPassword

Creating API Keys

Since tests mutate your account by creating and deleting watchlists, you must use a demo account and API key.

I will not take any resposibility for running tests using your live account credentials!

To create an API key, login to IG and go to:

My IG > Settings > API keys

Here you will be able to create API keys for both your live and demo accounts.

If you don't have a demo account, you will need to create one.

NOTE: After creating a demo account for the first time, it is important that you login to your account, go to the Dashboard and make one of your demo accounts a default by clicking the radio button next to it. If you don't do this, you will get a "Transformation failure" error when attempting to login using your demo credentials.

Running Tests

Tests are written using jest. To run the tests:

yarn test

To run the tests continuously during development:

yarn test:watch

Author

Matthew Wagerfield

License

MIT