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 Rest-ful API.

Install

$ 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.

Public Rest API

The most simple way to get the ticker, orderbook and trades, is through our public rest-ful api, which doesn't require authentication.

Ticker

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

blinktrade.ticker().then(function(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

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

blinktrade.orderbook().then(function(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

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

blinktrade.trades().then(function(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.

var BlinkTradeRest = require("blinktrade").BlinkTradeRest;
var 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: "1",
  price: parseInt(1800 * 1e8),
  amount: parseInt(0.5 * 1e8),
  symbol: "BTCBRL",
}).then(function(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.

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

blinktrade.connect().then(function() {
  // Connected
  return blinktrade.login({ username: "", password: "" });
}).then(function() {
});

Requesting Balance

Will request your balance for each broker.

blinktrade.balance().then(function(balance) {
  console.log(balance);
});

You can pass a callback to receive balance updates.

blinktrade.balance(function(err, balance) {
  console.log(balance);
});

EXAMPLE RESPONSE

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

Subscribe to OrderBook

blinktrade.subscribeOrderbook(["BTCUSD"]).then(function(orderbook) {
  console.log(orderbook);
});

EXAMPLE RESPONSE

{
  "MDReqID": 9894272,
  "Symbol": "BTCUSD",
  "MsgType": "W",
  "MarketDepth": 0,
  "MDFullGrp": {
    "BTCUSD": {
      "bids": [[ 578, 1.59231429, 90800535 ], [ 577.79, 5.68, 90800535 ]],
      "asks": [[ 578.72, 8.32039144, 90800535 ], [ 579.67, 2, 90800535 ]]
    }
  }
}

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

blinktrade.subscribeOrderbook(["BTCUSD"]).then(function(orderbook) {
  blinktrade.unSubscribeOrderbook(orderbook.MDReqID);
});

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

Subscribe to ticker

You can subscribe on one or more market symbols.

blinktrade.subscribeTicker(["BLINK:BTCUSD"]).then(function(ticker) {
  console.log(ticker);
});

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

blinktrade.subscribeTicker(["BLINK:BTCUSD"]).then(function(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": "1", // Buy
  "price": parseInt((550 * 1e8).toFixed(0)),
  "amount": parseInt((0.05 * 1e8).toFixed(0)),
  "symbol": "BTCUSD",
}).then(function(order) {
  // Sent
});

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 orders, you need to pass the OrderID, you'll also need to pass the ClOrdId as clientId in order to get a response.

blinktrade.cancelOrder({ orderID: order.OrderID, clientId: order.ClOrdID }).then(function(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: 1000, since: "1472347212" }).then(function(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(function(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(function(deposit) {
  console.log(deposit);
});

Response

Both response for bitcoin and fiat deposits is 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, whichs represents the information to your withdraw, it's related to bank accounts, numbers, or a bitcoin address, these informations are dynamically and different by each 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 request a withdraw, you might get a 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 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.

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",   function(usdbrt) {
}).on("BLINK:BTCUSD", function(btcusd) {
}).on("BLINK:BTCBRL", function(btcbrl) {
});

You can easily match all symbols at the same listener.

blinktrade.subscribeTicker(["UOL:USDBRT", "BLINK:BTCUSD", "BLINK:BTCBRL"])
.on("BLINK:*", function(symbol) {
});

Event Market Data

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

blinktrade.subscribeOrderbook(["BTCUSD"])
  .on("OB:NEW_ORDER", function(order) {
}).on("OB:UPDATE_ORDER", function(order) {
}).on("OB:DELETE_ORDER", function(order) {
}).on("OB:DELETE_ORDERS_THRU", function(order) {
}).on("OB:TRADE_NEW", function(order) {
});

You can still return a promise when listen events.

blinktrade.subscribeOrderbook(["BTCUSD"])
.on("OB:NEW_ORDER", function(order) {
  console.log("New order received");
}).then(function(orderbook) {
  console.log("Full orderbook", orderbook);
});

Event Balance

You listen the BALANCE event to receive balance updates

blinktrade.balance().on("BALANCE", function(balance) {
  console.log(balance);
});

Execution Reports

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

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

Withdraw and Deposit Refresh

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

blinktrade.requestDeposit().on('DEPOSIT_REFRESH', function(deposit) {
  console.log(deposit);
});

blinktrade.requestWithdraw().on('WITHDRAW_REFRESH', function(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(function(deposit) {
  console.log(deposit);
});

blinktrade.onWithdrawRefresh(function(withdraw) {
  console.log(withdraw);
});

API

Public Rest API

• Ticker
• Trades
• Orderbook

WebSocket

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

Trade Rest / Websocket

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

Public Rest

Constructor [rest]

new BlinkTradeRest(Object constructor)

Arguments

ticker [rest]

ticker(Function? callback) => Promise / callback

trades [rest]

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

Arguments

orderbook [rest]

orderbook(Function? callback) => Promise / callback

WebSocket

constructor [websocket]

new BlinkTradeWS(Object constructor)

Arguments

connect [websocket]

Connect to our websocket.

connect(Function? callback) => Promise / callback

heartbeat [websocket]

Used as test request to check the latency connection.

heartbeat(Function? callback) => Promise / callback

login [websocket]

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

Arguments

logout [websocket]

logout(Function? callback) => Promise / callback

profile [websocket]

Available only on websocket.

profile(Function? callback) => Promise / callback

subscribeTicker [websocket]

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

Symbols Available:

subscribeOrderbook [websocket]

subscribeOrderbook(Array<string> symbol, Function? callback) => Promise / callback

Events

executionReport [websocket]

executionReport(Function? callback) => Promise / callback

Events

An event emitter to get execution reports.

tradeHistory [websocket]

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

Arguments

Trade Rest / Websocket

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

balance [websocket, rest]

balance(Function? callback) => Promise / callback

Events

balance().on("BALANCE", Function callback) => Promise

sendOrder [websocket, rest]

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

Arguments

cancelOrder [websocket, rest]

cancelOrder(Object order | Number orderId, Function? callback) => Promise / callback

Arguments

myOrders [websocket, rest]

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

Arguments

requestWithdrawList [websocket, rest]

requestWithdrawList(Object pagination, Array<string> statusList, Function? callback) => Promise / callback

requestWithdraw [websocket, rest]

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

Events

FOXBIT

VBTC

confirmWithdraw [websocket, rest]

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

cancelWithdraw [websocket, rest]

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

onWithdrawRefresh [websocket]

onWithdrawRefresh(Function callback) => Promise

requestDepositList [websocket, rest]

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

requestDeposit [websocket, rest]

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

Events

requestDepositMethods [websocket, rest]

requestDepositMethods(Function? callback) => Promise / callback

onDepositRefresh [websocket]

onDepositRefresh(Function callback) => Promise

LICENSE

LICENSE GPLv3