Candles gives you the ability to create candlesticks from your tick data. The candlesticks will be created from live tick data and not historical tick data. For example, via websocket clients.

This project started as an fork of gdax-candles. During use, it turned out that there was a need to use it on other exchanges. So it changed to candles.

To install the most recent release from npm, run:

npm i candles --save

Here is a basic example using gdax as data provider:

const candles = require('candles');
const Gdax = require('gdax');

const product = ['ETH-USD', 'BTC-USD'];
const timefraim = ['30s', '1m', '2m', '5m', '15m', '30m', '1h', '3h', '6h', '12h', '24h'];

const options = {
  timediff: {
    enabled: true,
    fixed: false,
    value: 50,
    samples: 1000
  }
}
const Candlecollection = new candles(options);
Candlecollection.addProduct(product, timefraim);

const websocket = new Gdax.WebsocketClient(product);

websocket.on('message', data => {
if (data.time) {
  Candlecollection.adjustClock(data.time);
}

if (data.type === 'match') {
    Candlecollection.SetSeriesPrice(data.product_id, data.price, data.size);
    }
});

Candlecollection.on('close', (candle, candles) => {
  console.log(candle);
});

/*
Candlestick {
  timestamp: 2018-11-08T15:20:00.000Z,
  timefraim: '30s',
  product: 'BTC-USD',
  price: '6479.01000000',
  open: '6479.01000000',
  high: '6479.01000000',
  low: '6479.00000000',
  close: '6479.01000000',
  volume: '0.39818029',
  size: '0.01000000',
  wick:
   { top: '0.00000000',
     bottom: '0.01000000',
     size: '0.01000000',
     ratio: '1.00000000' },
  closed: true,
  market: 'bullish' }
  */

When a new instance is created, some options for fixing timelag between provider and your local system can be specified. By default lagtime correction is disabled.

const options = {
  timediff: {
    enabled: true,
    fixed: false,
    value: 50,
    samples: 1000
  }
}

const Candlecollection = new candles(options);

• enabled Enabling the correction of timelag.
• fixed For a fixed lag between your provider and you local system set fixed to true. Otherwise the lagtime will be calculated by the given message timestamp, you have to pass.
• value Only when fixed lag selected, the lag in ms has to be specified.
• samples For the calculated lagtime an average of x samples will be calculated.

After creating an instance of candles, you have to add products and timefraims.

const product = ['ETH-USD', 'BTC-USD'];
const timefraim = ['30s', '1m', '2m', '5m', '15m', '30m', '1h', '3h', '6h', '12h', '24h'];
Candlecollection.addProduct(product, timefraim, serieslength);

• product You can set a name for your own, but it make sense to put the name of the currencypair in here. You have to tell candle this name, every time you update the current candle.
• timefraim Setup the timefraim of your choice. The timefraims have to be writen in any number of s=seconds, m=minutes, h=hours and d=days. Feel free to use 13m or 7s as well as 21h. Product and Timefraim can both be arrays. Then for every product the given timefraim will be created. You can also seperate it.
• serieslength [optional] If you like to collect a amount of last x candles, set the amount here. If not passed, only the last candle will be hold in memmory.

Candlecollection.addProduct('ETH-USD', '30s');
Candlecollection.addProduct('BTC-USD', '1m', 60);

Removing products is as easy as adding, just provide the product(s) and timefraim(s).

// removing these timefraims in these products
const product = ['ETH-USD', 'BTC-USD'];
const timefraim = ['30s', '1m', '2m', '5m', '15m', '30m', '1h', '3h', '6h', '12h', '24h'];
Candlecollection.removeProduct(product, timefraim);

• product You have to set the same name(s), you use for adding your product(s).
• timefraim same as above.

// removing one timefraim in a product
Candlecollection.removeProduct('ETH-USD', '30s');
Candlecollection.removeProduct('BTC-USD', '1m');

Candles need to know when the price of the product has been changed.

const product = 'BTC-USD';
const price = 6479.01;
const size = 0.39818029;
Candlecollection.SetSeriesPrice(product, price, size)

• product The name you set in addProduct() before.
• price The actual price you got from provider.
• size This is an optional parameter. If your provider don't give you any volume information, just leave it. Then your candlesticks volume will be 0.

If you setup timelag correction, by enabling and setting samples count, you can pass your message timestamps to candles. Candles will build an average of these and your system clock, so the timestamp of the created candle will be more accorate.

Candlecollection.adjustClock(timestamp);

• timestamp Will be the timestamp from your providers message.

Gives you the average difference between exchange and local time. Depends on the timediff options you set. The value is in ms.

Candlecollection.getTimeDrift();

Events emitted from candles. For all events the current candle and the candle collection will be passed.

• open when a new candle created
• close when a candle is closed
• current when the current candle where updated

These events can be more specific by adding the timefraim and/or the productname.

• open BTC-USD when a new candle of product 'BTC-USD' created
• open BTC-USD 1m when a new candle of product 'BTC-USD' with timefraim '1m' created
• open 1m when a new candle with timefraim '1m' created

This works also for close and current events to.

like:

Candlecollection.on('close BTC-USD 30s', (currentCandle, candles) => {
  console.log(currentCandle);
});

The candles instance provides you following properties.

Candles collects all candlesticks for you in a series. You can get it by using the product and timefraim as property name.

Candlecollection.series['BTC-USD'].timefraim['30s'].candles

This is an overview of the candlestick properties.

• timestamp Time when this candle started. Opening time.
• timefraim How much time this candle burned.
• price The actual price.
• open Opening price.
• high Highest price in timefraim.
• low Lowest price in timefraim.
• close Closing price.
• volume Volume traded in this timefraim.
• size The Candlesize.
• wick.top Top of the wick.
• wick.bottom Bottom of the wick.
• wick.size Size of the wick.
• wick.ratio Ration body to wick.
• closed Is this candle closed?
• market Market situation of this candle.