CryptoCurrency eXchange WebSockets

A JavaScript library for connecting to realtime public APIs on all cryptocurrency exchanges.

Blocktap.io, a free data analytics platform, uses CCXWS to provide real time data.

CCXWS provides a standardized eventing interface for connection to public APIs. Currently CCXWS support ticker, trade and orderbook events.

The CCXWS socket client performs automatic reconnection when there are disconnections. It also has silent reconnection logic to assist when no data has been seen by the client but the socket remains open.

CCXWS uses similar market structures to those generated by the CCXT library. This allows interoperability between the RESTful interfaces provided by CCXT and the realtime interfaces provided by CCXWS.

Getting Started

Install ccxws

npm install ccxws

Create a new client for an exchange. Subscribe to the events that you want to listen to by supplying a market.

const ccxws = require("ccxws");
const binance = new ccxws.Binance();

// market could be from CCXT or genearted by the user
const market = {
  id: "ADABTC", // remote_id used by the exchange
  base: "ADA", // standardized base symbol for Cardano
  quote: "BTC", // standardized quote symbol for Bitcoin
};

// handle trade events
binance.on("trade", trade => console.log(trade));

// handle level2 orderbook snapshots
binance.on("l2snapshot", snapshot => console.log(snapshot));

// subscribe to trades
binance.subscribeTrades(market);

// subscribe to level2 orderbook snapshots
binance.subscribeLevel2Snapshots(market);

Exchanges

Exchange	Class	Ticker	Trades	OB-L2 Snapshot	OB-L2 Updates	OB-L3 Snapshot	OB-L3 Updates
Bibox	bibox	Support	Support	Support		-	-
Binance	binance	Support	Support	Support	Support**	-	-
Bitfinex	bitfinex	Support	Support	-	Support*	-	Support*
bitFlyer	bitflyer	Support	Support	-	Support**	-	-
BitMEX	bitmex		Support	-	Support*	-	-
Bitstamp	bitstamp	-	Support	Support	Support**	-	Support
Bittrex	bittrex	Support	Support	-	Support*	-	-
Cex.io	cex	Support	Support	-	Support*	-	-
Coinex	coinex	Support	Support	-	Support*	-	-
Coinbase Pro	coinbasepro	Support	Support	-	Support*	-	Support
Ethfinex	ethfinex	Support	Support	-	Support*	-	Support*
Gate.io	gateio	Support	Support	-	Support*	-	-
Gemini	gemini	-	Support	-	Support*	-	-
HitBTC	hitbtc	Support	Support	-	Support*	-	-
Huobi	huobi	Support	Support	Support	-	-	-
Kraken	kraken	Support	Support	-	Support*	-	-
OKEx	okex	Support	Support	Support	Support*	-	-
Poloniex	poloniex	Support	Support	-	Support*	-	-
Upbit	upbit	Support	Support	Support	-	-	-
ZB	zb	Support	Support	Support	-	-	-

Notes:

Support*: Broadcasts a snapshot event at startup
Support**: Broadcasts a snapshot by using the REST API

Definitions

Trades - A maker/taker match has been made. Broadcast as an aggregated event.

Orderbook level 2 - has aggregated price points for bids/asks that include the price and total volume at that point. Some exchange may include the number of orders making up the volume at that price point.

Orderbook level 3 - this is the most granual order book information. It has raw order information for bids/asks that can be used to build aggregated volume information for the price points.

API

`Market`

Markets are used as input to many of the client functions. Markets can be generated and stored by you the developer or loaded from the CCXT library.

The following properties are used by CCXWS.

id: string - the identifier used by the remote exchange
base: string - the normalized base symbol for the market
quote: string - the normalized quote symbol for the market

`Client`

A websocket client that connects to a specific exchange. There is an implementation of this class for each exchange that governs the specific rules for managing the realtime connections to the exchange. You must instantiate the specific exchanges client to conncet to the exchange.

const binance = new ccxws.Binance();
const gdax = new ccxws.GDAX();

Properties

`reconnectIntervalMs: int` - default 90000

Property that controls silent socket drop checking. This will enable a check at the reconnection interval that looks for ANY broadcast message from the server. If there has not been a message since the last check a reconnection (close, connect) operation is performed. This property must be set before the first subscription (and subsequent connection).

Events

Subscribe to events by addding an event handler to the client .on(<event>) method of the client. Multiple event handlers can be added for the same event.

Once an event handler is attached you can start the stream using the subscribe<X> methods.

binance.on("trades", trade => console.log(trade));
binance.on("l2snapshot", snapshot => console.log(snapshot));

`ticker: Ticker`

Fired when a ticker update is received. Returns an instance of Ticker.

`trade: Trade`

Fired when a trade is received. Returns an instance of Trade.

`l2snapshot: Level2Snapshot`

Fired when a orderbook level 2 snapshot is received. Returns an instance of Level2Snapshot.

The level of detail will depend on the specific exchange and may include 5/10/20/50/100/1000 bids and asks.

This event is also fired when subscribing to the l2update event on many exchanges.

`l2update: Level2Update`

Fired when a orderbook level 2 update is recieved. Returns an instance of Level2Update.

Subscribing to this event may trigger an initial l2snapshot event for many exchanges.

`l3snapshot: Level3Snapshot`

Fired when a orderbook level 3 snapshot is received. Returns an instance of Level3Snapshot.

`l3update: Level3Update` - orderbook level 3 Update

Fired when a level 3 update is recieved. Returns an instance of Level3Update.

Connection Events

`connected`

Fires when a socket has connected. This event will fire when for reconnections.

`closed`

Fires when the client has closed its connection(s). This event is not fired during disconnections, it is fired when the close method is called and the connection(s) are successfully closed.

`disconnected`

Fires when a socket has been disconnected. Automatic reconnection should will be performed and the next event will be reconnected followed by a connected event when the reconnection is successful.

`reconnected`

Fires when a socket has initiated the reconnection process. This is fired at the start of thee reconnection process and is more aptly named reconnecting.

Methods

`subscribeTicker(market): void`

Subscribes to a ticker feed for a market. This method will cause the client to emit ticker events that have a payload of the Ticker object.

`unsubscribeTicker(market): void`

Unsubscribes from a ticker feed for a market.

`subscribeTrades(market): void`

Subscribes to a trade feed for a market. This method will cause the client to emit trade events that have a payload of the Trade object.