blinktrade v1.0.0-rc.0

BlinkTradeJS SDK

BlinkTradeJS WebSocket and REST Official JavasScript client for node.js and browser.

Getting Started

BlinkTrade provides a simple and robust WebSocket API to integrate our platform, we strongly recommend you to use it over the RESTful API.

Install

$ yarn add blinktrade

using npm.

$ npm install blinktrade

Documentation

You can also check our Full API Documentation.

Examples

More examples can be found in the examples directory.

Usage

All SDK supports either promises and callbacks, if a callback is provided as the last argument, it will be called as callback(error, result), otherwise it will just return the original promise, we also provide event emitters that you can use to get realtime updates through our WebSocket API, you can check the Event Emitters section.

NOTE We impose cross origin policy (cors), even though our SDK can work on the browser, it won’t work due our origin policy, so and we recommend you use on server side instead. Only the public rest is available on the browser, and other environments only works on testnet and you won’t be able use to use production environment on the browser, this might change in the future.

Public REST API

The most simple way to get the ticker, orderbook and trades, is through our public RESTful API, which doesn't require authentication.

Ticker

const BlinkTradeRest = require("blinktrade").BlinkTradeRest;
const blinktrade = new BlinkTradeRest({ currency: "BRL" });

blinktrade.ticker().then((ticker) => {
  console.log(ticker)
})

Response

  {
    "high": 1900,
    "vol": 4.87859418,
    "buy": 1891.89,
    "last": 1891.89,
    "low": 1891.89,
    "pair": "BTCBRL",
    "sell": 1910,
    "vol_brl": 9250.19572651
  }

OrderBook

const BlinkTradeRest = require("blinktrade").BlinkTradeRest;
const blinktrade = new BlinkTradeRest({ currency: "BRL" });

blinktrade.orderbook().then((orderbook) => {
  console.log(orderbook)
})

Response

{
  "pair": "BTCBRL",
  "bids": [
    [ 1891.89, 0.16314699, 90800027 ],
    [ 1880, 0.20712, 90800027 ]
  ],
  "asks": [
    [ 1910, 3.28046533, 90800027 ],
    [ 1919.99, 1.95046354, 90800027 ]
  ]
}

Last Trades

const BlinkTradeRest = require("blinktrade").BlinkTradeRest;
const blinktrade = new BlinkTradeRest({ currency: "BRL" });

blinktrade.trades().then((trades) => {
  console.log(trades)
})

Response

 [{
    "tid": 16093,
    "date": 1472278473,
    "price": 1891.89,
    "amount": 0.1,
    "side": "sell"
  }, {
    "tid": 16094,
    "date": 1472278477,
    "price": 1891.89,
    "amount": 0.1,
    "side": "sell"
  }, {
    "tid": 16095,
    "date": 1472278668,
    "price": 1891.89,
    "amount": 0.1,
    "side": "sell"
 }]

Trade REST / WebSocket

On our RESTful API, we provide a trade endpoint that you're allowed to send and cancel orders, request deposits and withdrawals. You need to create an API Key through our platform and set their respective permission that gives you access to it.

The Trade endpoint is internaly a bridge to our WebSocket API, so you can access it both on REST and WebSocket API. Be aware that our RESTful trade endpoint can be changed at any time, we strongly recommend using the WebSocket API over the RESTful API.

NOTE that when generate the API Key and the API Secret, it will be only shown once, you should save it securely. The API Password is only used in the WebSocket API.

const BlinkTradeRest = require("blinktrade").BlinkTradeRest;
const blinktrade = new BlinkTradeRest({
  prod: false,
  key: "YOUR_API_KEY_GENERATED_IN_API_MODULE",
  secret: "YOUR_SECRET_KEY_GENERATED_IN_API_MODULE",
  currency: "BRL",
});

blinktrade.sendOrder({
  side: "BUY",
  price: parseInt(1800 * 1e8).toFixed(0),
  amount: parseInt(0.5 * 1e8).toFixed(0),
  symbol: "BTCBRL",
}).then((order) => {
    console.log(order)
})

Response

{
    "OrderID": 1459028830811,
    "ExecID": 740972,
    "ExecType": "0",
    "OrdStatus": "0",
    "CumQty": 0,
    "Symbol": "BTCUSD",
    "OrderQty": 5000000,
    "LastShares": 0,
    "LastPx": 0,
    "Price": 180000000000,
    "TimeInForce": "1",
    "LeavesQty": 50000000,
    "MsgType": "8",
    "ExecSide": "1",
    "OrdType": "2",
    "CxlQty": 0,
    "Side": "1",
    "ClOrdID": 3251968,
    "AvgPx": 0
}

Usage WebSocket

Authenticating

Make sure that you're connected to send messages through WebSocket, most of the message also require that you're authenticated.

const BlinkTradeWS = require("blinktrade").BlinkTradeWS;
const blinktrade = new BlinkTradeWS({ prod: true });

blinktrade.connect().then(() => {
  // Connected
  return blinktrade.login({ username: "<API_KEY>", password: "<API_SECRET>" });
}).then((logged) => {});

Requesting Balance

Will request your balance for each broker.

blinktrade.balance().then((balance) => {
  console.log(balance);
});

You can pass a callback to receive balance updates.

blinktrade.balance(null, (err, balance) => {
  console.log(balance);
});

EXAMPLE RESPONSE

{
    "5": {
        "BTC_locked": 0,
        "USD": 177911657052760,
        "BTC": 1468038442214,
        "USD_locked": 96750050000
    },
    "MsgType": "U3",
    "ClientID": 90800003,
    "BalanceReqID": 5019624
}

Subscribe to OrderBook

blinktrade.subscribeMarketData(["BTCBRL"]).then((orderbook) => {
  console.log(orderbook)
})

EXAMPLE RESPONSE

{
  "MDReqID": 9894272,
  "Symbol": "BTCUSD",
  "MsgType": "W",
  "MarketDepth": 0,
  "MDFullGrp": {
    "BTCUSD": {
      "bids": [{
        "MDEntryPositionNo": 1,
        "MDEntrySize": 50000000,
        "MDEntryPx": 1150600000000,
        "MDEntryID": 1459030492064,
        "MDEntryTime": "05:50:13",
        "MDEntryDate": "2018-02-03",
        "UserID": 90800000,
        "OrderID": 1459000000000,
        "MDEntryType": "0",
      }],
      "asks": [{
        "MDEntryPositionNo": 1,
        "MDEntrySize": 50000000,
        "MDEntryPx": 1150700000000,
        "MDEntryID": 1459030492064,
        "MDEntryTime": "05:50:13",
        "MDEntryDate": "2018-02-03",
        "UserID": 90800000,
        "OrderID": 1459000000000,
        "MDEntryType": "1",
      }]
    }
  }
}

To unsubscribe from orderbook, you should pass the MDReqID on unSubscribeOrderbook().

blinktrade.subscribeMarketData(["BTCBRL"]).then((orderbook) => {
  blinktrade.unSubscribeOrderbook(orderbook.MDReqID);
});

Note that there's no return when unsubscribe from orderbook.

Syncronize orderbook

The syncOrderbook function automatically handles the event system to keep the order book syncronized for you, you can access the order book at anywhere in your application with blinktrade.orderbook

blinktrade.syncOrderbook(["BTCBRL"]).then(() => {
  console.log(blinktrade.orderbook);
})

The blinktrade.orderbook is a object like this

{
  "BTCUSD": {
    "bids": [{
      "MDEntryPositionNo": 1,
      "MDEntrySize": 50000000,
      "MDEntryPx": 1150600000000,
      "MDEntryID": 1459030492064,
      "MDEntryTime": "05:50:13",
      "MDEntryDate": "2018-02-03",
      "UserID": 90800000,
      "OrderID": 1459000000000,
      "MDEntryType": "0",
    }],
    "asks": [{
      "MDEntryPositionNo": 1,
      "MDEntrySize": 50000000,
      "MDEntryPx": 1150700000000,
      "MDEntryID": 1459030492064,
      "MDEntryTime": "05:50:13",
      "MDEntryDate": "2018-02-03",
      "UserID": 90800000,
      "OrderID": 1459000000000,
      "MDEntryType": "1",
    }]
  }
}

Subscribe to ticker

You can subscribe on one or more market symbols.

blinktrade.subscribeTicker(["BLINK:BTCBRL"]).then((ticker) => {
  console.log(ticker);
});

To unsubscribe from ticker, you do the same as unSubscribeOrderbook, but passing SecurityStatusReqID to unSubscribeTicker().

blinktrade.subscribeTicker(["BLINK:BTCBRL"]).then((ticker) => {
  blinktrade.unSubscribeTicker(ticker.SecurityStatusReqID);
});

Send and cancelling orders

Floats are Evil!

Converting Floats to Integers can be dangerous. Different programming languages can get weird rounding errors and imprecisions, so all API returns prices and bitcoin values as Integers and in "satoshis" format. We also expect Integers as input, make sure that you're formatting the values properly to avoid precision issues.

e.g.:

// Wrong
0.57 * 1e8 => 56999999.99999999

// Correct
parseInt((0.57 * 1e8).toFixed(0)) => 57000000

blinktrade.sendOrder({
  side: "BUY",
  price: parseInt((550 * 1e8).toFixed(0)),
  amount: parseInt((0.05 * 1e8).toFixed(0)),
  symbol: "BTCUSD",
}).then((order) => {
  // Sent
});

Advanced Orders (MARKET, LIMIT, STOP)

Market

Market orders automatically execute your order at the current price.

blinktrade.sendOrder({
  side: 'BUY',
  type: 'MARKET',
  symbol: 'BTCBRL',
  amount: parseInt(0.01 * 1e8),
})

NOTE Market orders will execute indenpendently of the price of the other side, so be careful on low liquidity scenarios.

Limit

Limit order allows you specified your own price.

blinktrade.sendOrder({
  side: 'SELL',
  type: 'LIMIT',
  symbol: 'BTCBRL',
  price: parseInt(16000 * 1e8),
  amount: parseInt(0.01 * 1e8),
})

Post Only

Post Only ensures that your order will be added to the order book and not match with a existing order.

blinktrade.sendOrder({
  side: 'BUY',
  type: 'LIMIT',
  symbol: 'BTCBRL',
  price: parseInt(16000 * 1e8),
  amount: parseInt(0.01 * 1e8),
  postOnly: true,
})

Stop

Stop order allow you place an order only when the price reaches the stop price, your order won't be visible on the book until it triggered.

blinktrade.sendOrder({
  side: 'SELL',
  type: 'STOP',
  symbol: 'BTCBRL',
  stopPrice: parseInt(16000 * 1e8), // Price bellow the best bid
  amount: parseInt(0.01 * 1e8),
})

NOTE STOP order will act as a MARKET order, if you want yo specify a limit price use STOP_LIMIT instead.

Stop Limit

Stop Limit order allow you specified a limit price toghether with the stop price.

blinktrade.sendOrder({
  side: 'SELL',
  type: 'STOP_LIMIT',
  symbol: 'BTCBRL',
  price: parseInt(15900 * 1e8), // Limit price
  stopPrice: parseInt(16000 * 1e8), // Price bellow the best bid
  amount: parseInt(0.01 * 1e8),
})

Response

The response is the same as the Execution Report, if you're using it with rest transport, it will response as an array together with the balance response.

{
    "OrderID": 1459028830811,
    "ExecID": 740972,
    "ExecType": "0",
    "OrdStatus": "0",
    "CumQty": 0,
    "Symbol": "BTCUSD",
    "OrderQty": 5000000,
    "LastShares": 0,
    "LastPx": 0,
    "Price": 55000000000,
    "TimeInForce": "1",
    "LeavesQty": 5000000,
    "MsgType": "8",
    "ExecSide": "1",
    "OrdType": "2",
    "CxlQty": 0,
    "Side": "1",
    "ClOrdID": 3251968,
    "AvgPx": 0
}

To cancel a order, you need to pass the orderId, you'll also need to pass the clientId in order to get a response, if you didn't provide orderId, all open orders will be cancelled.

blinktrade.cancelOrder({ orderId: order.OrderID, clientId: order.ClOrdID }).then((order) => {
  console.log("Order Cancelled");
})

The response will be the same as the sendOrder with ExecType: "4"

Last Trades

List the latest trades executed on an exchange since a chosen date.

blinktrade.trades({ limit: 100, since: 2270000 }).then((data) => {
  console.log("Trades", data);
})

Requesting Deposits

You can generate either bitcoin or FIAT deposits, if any arguments was passed, it will generate a bitcoin deposit along with the address.

Generate bitcoin address to deposit

blinktrade.requestDeposit().then((deposit) => {
  console.log(deposit)
})

Fiat deposit

To generate a FIAT deposit, you need to pass the depositMethodId which correspond the method of deposit of your broker, you can get these informations calling requestDepositMethods()

blinktrade.requestDeposit({
  value: parseInt(200 * 1e8),
  currency: "BRL",
  depositMethodId: 502,
}).then((deposit) => {
  console.log(deposit)
})

Response

Both responses for bitcoin and fiat deposits are quite similar.

{
    "DepositMethodName": "deposit_btc",
    "UserID": 90800003,
    "ControlNumber": null,
    "State": "UNCONFIRMED",
    "Type": "CRY",
    "PercentFee": 0,
    "Username": "user",
    "CreditProvided": 0,
    "DepositReqID": 7302188,
    "DepositID": "2a6b5e322fd24574a4d9f988681a542f",
    "Reason": null,
    "AccountID": 90800003,
    "Data": {
        "InputAddress": "mjjVMr8WcYQwVGzYc8HpaRyAZc89ngTdKV",
        "Destination": "n19ZAH1WGoUkQhubQw71fH11BenifxpBxf"
    },
    "ClOrdID": "7302188",
    "Status": "0",
    "Created": "2016-09-03 23:08:26",
    "DepositMethodID": null,
    "Value": 0,
    "BrokerID": 5,
    "PaidValue": 0,
    "Currency": "BTC",
    "ReasonID": null,
    "MsgType": "U23",
    "FixedFee": 0
}

NOTE The Data.InputAddress is the address that you have to deposit. DO NOT DEPOSIT on Data.Destination address.

Requesting Withdraws

To request withdraws, you need to pass a "data" information, which represents the information to your withdraw, it's related to bank accounts, numbers, or a bitcoin address. This information is dynamically and different for every broker.

blinktrade.requestWithdraw({
  amount: parseInt(400 * 1e8),
  currency: "BRL",
  method: "bradesco",
  data: {
    AccountBranch: "111",
    AccountNumber: "4444-5",
    AccountType: "corrente",
    CPF_CNPJ: "00000000000"
  }
})

Confirm Withdraws (two-factor)

After requesting a withdraw, you might get an error asking for two factor authentication, you should call confirmWithdraw passing the confirmationToken that was sent to your email, or secondFactor if needed.

blinktrade.confirmWithdraw({
    withdrawId: 523,
    confirmationToken: 'TOKEN'
})

Response

{
    "Username": "user",
    "Status": "1",
    "SecondFactorType": "",
    "Created": "2016-09-03 23:42:06",
    "PaidAmount": 50000000,
    "UserID": 90800003,
    "Reason": null,
    "Currency": "BRL",
    "Amount": 50000000,
    "ReasonID": null,
    "BrokerID": 5,
    "ClOrdID": "3332623",
    "WithdrawID": 523,
    "WithdrawReqID": 3332623,
    "MsgType": "U7",
    "Data": {
        "Instant": "NO",
        "AccountBranch": "111",
        "AccountNumber": "4444-5",
        "AccountType": "corrente", 
        "CPF_CNPJ": "00000000000"
    },
    "Method": "bradesco",
    "FixedFee": 0,
    "PercentFee": 0
}

Event Emitters

Using event emitters is easy and expressive way to keep you updated through our WebSocket API, you can listen to individual events to match your needs, you can listen to new orders, execution reports, tickers and balance changes. Event emitters can also be used as promises to keep it chained, event emitters are implemented with EventEmitter2, which gives you more flexibility to match events with multi-level wildcards and extends events such as .onAny, .once, .many and so on.

Connection Events

You can listem to OPEN, CLOSE, and ERROR events to get WebSocket events and error handling.

blinktrade.connect()
  .on('OPEN',  (e) => {})
  .on('CLOSE', (e, lastMessageSent) => {})
  .on('ERROR', (error, lastMessageSent) => {})
  .then(() => {
    console.log('Connected')
  })

The OPEN event is useful to handle reconnections, since the promise is already resolved.

The ERROR event is where you can do all the error handling, both from WebSocket errors or an error raised by the backend due some invalid message, both CLOSE and ERROR will give you the last message that you sent as the second argument.

You can also listen them by just blinktrade.on('OPEN', (e) => {}) that works just fine.

Event Ticker

To keep ticker update on new events, you can return a event emitter and match with the market.

blinktrade.subscribeTicker(["UOL:USDBRT", "BLINK:BTCUSD", "BLINK:BTCBRL"])
  .on("UOL:USDBRT",   (usdbrt) => {})
  .on("BLINK:BTCUSD", (btcusd) => {})
  .on("BLINK:BTCBRL", (btcbrl) => {})

You can easily match all symbols at the same listener.

blinktrade.subscribeTicker(["UOL:USDBRT", "BLINK:BTCUSD", "BLINK:BTCBRL"])
.on("BLINK:*", (ticker) => {})

Event Market Data

To get realtime updates on order book, you should listen to the following events.

blinktrade.subscribeMarketData(["BTCUSD"])
  .on("OB:NEW_ORDER", (order) => {})
  .on("OB:UPDATE_ORDER", (order) => {})
  .on("OB:DELETE_ORDER", (order) => {})
  .on("OB:DELETE_ORDERS_THRU", (order) => {})
  .on("OB:TRADE_NEW", (order) => {})

You can still return a promise when listen events.

blinktrade.subscribeMarketData(["BTCBRL"])
.on("OB:NEW_ORDER", (order) => {
  console.log("New order received")
}).then((orderbook) => {
  console.log("Full orderbook", orderbook)
})

Event Balance

You listen to the BALANCE event to receive balance updates.

blinktrade.balance().on("BALANCE", (balance) => console.log(balance))

Execution Reports

In order the get when a order is executed, you can listen to the execution report.

blinktrade.executionReport()
  .on("EXECUTION_REPORT:NEW", (data) => {})
  .on("EXECUTION_REPORT:PARTIAL", (data) => {})
  .on("EXECUTION_REPORT:EXECUTION", (data) => {})
  .on("EXECUTION_REPORT:CANCELED", (data) => {})
  .on("EXECUTION_REPORT:REJECTED", (data) => {})

Withdraw and Deposit Refresh

To get deposit and withdraw updates, you can listen to DEPOSIT_REFRESH and WITHDRAW_REFRESH respectively.

blinktrade.requestDeposit().on('DEPOSIT_REFRESH', (deposit) => {
  console.log(deposit)
})

blinktrade.requestWithdraw().on('WITHDRAW_REFRESH', (withdraw) => {
  console.log(withdraw)
})

NOTE that these events will only be called to the current deposit / withdraw created. If you want to listen to any deposit / withdraw updates, you should use onDepositRefresh(callback) and onWithdrawRefresh() instead.

blinktrade.onDepositRefresh((deposit) => {
  console.log(deposit)
})

blinktrade.onWithdrawRefresh((withdraw) => {
  console.log(withdraw)
})

Handling WebSocket Reconnections

A simple connection pool

const blinktrade = new BlinkTradeWS({
  prod: false,
  brokerId: 11,
  reconnect: true,
  reconnectInterval: 3000,
})

blinktrade.connect().on('OPEN', () => {
  console.log('connected');
  blinktrade.login({
    username: '<API_KEY>'
    password: '<API_PASSWORD>'
  }).then(() => {
    // Manually disconnect WebSocket connection
    blinktrade.disconnect()
  })
})

API

Public REST API

• Ticker
• Trades
• Orderbook

WebSocket

• connect
• heartbeat
• login
• logout
• profile
• subscribeTicker
• unSubscribeTicker
• subscribeMarketData
• unSubscribeOrderbook
• executionReport
• tradeHistory

Trade Rest / Websocket

• balance
• sendOrder
• cancelOrder
• myOrders
• requestLedger
• requestWithdrawList
• requestWithdraw
• confirmWithdraw
• cancelWithdraw
• onWithdrawRefresh
• requestDepositList
• requestDeposit
• requestDepositMethods
• onDepositRefresh

Public REST

Constructor rest

new BlinkTradeRest(params: Object)

Arguments

ticker rest

ticker(callback?: Function) => Promise / callback

trades rest

trades(params: Object, callback?: Function) => Promise / callback

Arguments

orderbook rest

orderbook(callback?: Function) => Promise / callback

WebSocket

constructor websocket

new BlinkTradeWS(params?: Object)

Arguments

connect websocket

Connect to our WebSocket.

connect(callback?: Function) => Promise / callback

Connection Events

heartbeat websocket

Used as test request to check the latency connection.

heartbeat(callback?: Function) => Promise / callback

login websocket

login(params: Object, callback?: Function) => Promise / callback

Arguments

logout websocket

logout(callback?: Function) => Promise / callback

profile websocket

Available only on WebSocket.

profile(callback?: Function) => Promise / callback

subscribeTicker websocket

subscribeTicker(Array<string> symbols, Function? callback) => Promise / callback

Symbols Available:

subscribeOrderbook websocket

DEPRECATED Use subscribeMarketData instead

subscribeMarketData websocket

subscribeMarketData(options: Object | Array<string>, callback?: Function) => Promise / callback

Arguments

Events

syncOrderbook websocket

syncOrderbook(options: Object | Array<string>) => Promise

See subscribeMarketData options

executionReport websocket

executionReport(callback?: Function) => Promise / callback

Events

An event emitter to get execution reports.

tradeHistory websocket

tradeHistory(params: Object, callback?: Function) => Promise / callback

Arguments

Trade REST / Websocket

These methods bellow are both availabe under REST and WebSocket API.

balance websocket, rest

balance(clientId?: string, callback?: Function) => Promise / callback

Events

balance().on("BALANCE", (balance) => {}) => Promise

sendOrder websocket, rest

sendOrder(params: Object, callback?: Function) => Promise / callback

Arguments

cancelOrder websocket, rest

cancelOrder(params: { orderId?: number, clientId?: string } | number, callback?: Function) => Promise / callback

Arguments

myOrders websocket, rest

myOrders(params: Object, callback?: Function) => Promise / callback

Arguments

requestLedger websocket, rest

requestLedger(params: Object, callback?: Function) => Promise / callback

Arguments

requestWithdrawList websocket, rest

requestWithdrawList(params: Object, callback?: Function) => Promise / callback

requestWithdraw websocket, rest

requestWithdraw(params: Object, callback?: Function) => Promise / callback

Events

confirmWithdraw websocket, rest

confirmWithdraw(params: Object, callback?: Function) => Promise / callback

cancelWithdraw websocket, rest

cancelWithdraw(withdrawId: number, callback?: Function) => Promise / callback

onWithdrawRefresh websocket

onWithdrawRefresh(callback: Function) => Promise

requestDepositList websocket, rest

requestDepositList(params: Object, callback?: Function) => Promise / callback

requestDeposit websocket, rest

requestDeposit(params: Object, callback?: Function) => Promise / callback

Events

requestDepositMethods websocket, rest

requestDepositMethods(callback?: Function) => Promise / callback

onDepositRefresh websocket

onDepositRefresh(callback: Function) => Promise

LICENSE

LICENSE GPLv3