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.
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: "BTCUSDT", // remote_id used by the exchange
base: "BTC", // standardized base symbol for Bitcoin
quote: "USDT", // standardized quote symbol for Tether
};
// 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);
Exchange | API | Class | Ticker | Trades | Candles | OB-L2 Snapshot |
OB-L2 Updates |
OB-L3 Snapshot |
OB-L3 Updates |
---|---|---|---|---|---|---|---|---|---|
Bibox | 1 | bibox | âś“ | âś“ | WIP | âś“ | - | - | |
Binance | 1 | binance | âś“ | âś“ | âś“ | âś“ | âś“** | - | - |
Binance Jersey | 1 | binanceje | âś“ | âś“ | âś“ | âś“ | âś“** | - | - |
Binance US | 1 | binanceus | âś“ | âś“ | âś“ | âś“ | âś“** | - | - |
Bitfinex | 1.1 | bitfinex | âś“ | âś“ | - | - | âś“* | - | âś“* |
bitFlyer | 1 | bitflyer | âś“ | âś“ | - | - | âś“** | - | - |
BitMEX | 1 | bitmex | âś“ | âś“ | WIP | - | âś“* | - | - |
Bitstamp | 2 | bitstamp | - | âś“ | - | âś“ | âś“** | - | âś“ |
Bittrex | 1 | bittrex | âś“ | âś“ | - | - | âś“* | - | - |
Cex.io | 1 | cex | âś“ | âś“ | WIP | - | âś“* | - | - |
Coinbase Pro | 1 | coinbasepro | âś“ | âś“ | - | - | âś“* | - | âś“ |
Coinex | 1 | coinex | âś“ | âś“ | WIP | - | âś“* | - | - |
Ethfinex | 1 | ethfinex | âś“ | âś“ | - | - | âś“* | - | âś“* |
FTX | 1 | ftx | âś“ | âś“ | - | - | âś“* | - | - |
Gate.io | 3 | gateio | âś“ | âś“ | WIP | - | âś“* | - | - |
Gemini | 1 | gemini | - | âś“ | - | - | âś“* | - | - |
HitBTC | 2 | hitbtc2 | âś“ | âś“ | WIP | - | âś“* | - | - |
Huobi | 1 | huobipro | âś“ | âś“ | WIP | âś“ | - | - | - |
KuCoin | 2 | kucoin | âś“ | âś“ | - | - | âś“** | - | |
Kraken | 0 | kraken | âś“ | âś“ | âś“ | - | âś“* | - | - |
Liquid | 2 | liquid | âś“ | âś“ | - | - | âś“ | - | - |
OKEx | 3 | okex3 | âś“ | âś“ | WIP | âś“ | âś“* | - | - |
Poloniex | 2 | poloniex | âś“ | âś“ | - | - | âś“* | - | - |
Upbit | 1 | upbit | âś“ | âś“ | - | âś“ | - | - | - |
ZB | 1 | zb | âś“ | âś“ | WIP | âś“ | - | - | - |
Notes:
- âś“* broadcasts a snapshot event at startup
- âś“** broadcasts a snapshot by using the REST API
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.
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.
These properties are required by CCXWS.
id: string
- the identifier used by the remote exchangebase: string
- the normalized base symbol for the marketquote: string
- the normalized quote symbol for the market
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();
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).
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.
All events emit the market used to subscribe to the event as a second property of the event handler.
binance.on("error", err => console.error(err));
binance.on("trades", (trade, market) => console.log(trade, market));
binance.on("l2snapshot", (snapshot, market) => console.log(snapshot, market));
You must subscribe to the error
event to prevent the process exiting. More information in the Node.js Events Documentation
If an EventEmitter does not have at least one listener registered for the 'error' event, and an 'error' event is emitted, the error is thrown, a stack trace is printed, and the Node.js process exits.
Fired when a ticker update is received. Returns an instance of Ticker
and the Market
used to subscribe to the event.
Fired when a trade is received. Returns an instance of Trade
and the Market
used to subscribe to the event.
Fired when a candle is received. Returns an instance of Candle
and the Market
used to subscribe to the event.
Fired when a orderbook level 2 snapshot is received. Returns an instance of Level2Snapshot
and the Market
used to subscribe to the event.
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.
Fired when a orderbook level 2 update is recieved. Returns an instance of Level2Update
and the Market
used to subscribe to the event.
Subscribing to this event may trigger an initial l2snapshot
event for many exchanges.
Fired when a orderbook level 3 snapshot is received. Returns an instance of Level3Snapshot
and the Market
used to subscribe to the event.
Fired when a level 3 update is recieved. Returns an instance of Level3Update
and the Market
used to subscribe to the event.
Clients emit events as their state changes.
+-------+
| |
| start |
| |
+---+---+
|
|
|
| subscribe
|
|
|
+------v-------+ initiate
| | reconnect
| connecting <------------------------+
| | |
+------+-------+ |
| |
| +-------+-------+
| | |
| socket | disconnected |
| open | |
| +-------^-------+
| |
+------v-------+ |
| | |
| connected +------------------------+
| | socket
+------+-------+ closed
|
|
|
| close
| requested
|
|
|
+------v-------+ +--------------+
| | | |
| closing +------------------> closed |
| | socket | |
+--------------+ closed +--------------+
Fires prior to a socket initiating the connection. This event also fires when a reconnection starts.
Fires when a socket has connected. This event will also fire for reconnection completed.
Fires when a socket prematurely disconnects. Automatic reconnection will be triggered. The expected
flow is disconnected -> connecting -> connected
.
Fires when the client is preparing to close its connection(s). This event is not fired during reconnections.
Fires when the client has closed its connection(s). This event is not fired during reconnections, it is fired when the close
method is called and the connection(s) are successfully closed.
Fires when a socket has initiated the reconnection process due to inactivity. This is fired at the start of the reconnection process reconnecting -> closing -> closed -> connecting -> connected
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.
Unsubscribes from a ticker feed for a market.
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.
Unsubscribes from a trade feed for a market.
*For some exchanges, calling unsubscribe may cause a temporary disruption in all feeds.
Subscribes to a candle feed for a market. This method will cause the client to emit candle
events that have a payload of the Candle
object. Set the
candlePeriod
property of the client to control which candle is returned by the feed.
Unsubscribes from a candle feed for a market.
*For some exchanges, calling unsubscribe may cause a temporary disruption in all feeds.
Subscribes to the orderbook level 2 snapshot feed for a market. This method will cause the client to emit l2snapshot
events that have a payload of the Level2Snaphot
object.
This method is a no-op for exchanges that do not support level 2 snapshot subscriptions.
Unbusbscribes from the orderbook level 2 snapshot for a market.
*For some exchanges, calling unsubscribe may cause a temporary disruption in all feeds.
Subscribes to the orderbook level 2 update feed for a market. This method will cause the client to emit l2update
events that have a payload of the Level2Update
object.
This method is a no-op for exchanges that do not support level 2 snapshot subscriptions.
Unbusbscribes from the orderbook level 2 updates for a market.
*For some exchanges, calling unsubscribe may cause a temporary disruption in all feeds.
Subscribes to the orderbook level 3 snapshot feed for a market. This method will cause the client to emit l3snapshot
events that have a payload of the Level3Snaphot
object.
This method is a no-op for exchanges that do not support level 2 snapshot subscriptions.
Unbusbscribes from the orderbook level 3 snapshot for a market.
*For some exchanges, calling unsubscribe may cause a temporary disruption in all feeds.
Subscribes to the orderbook level 3 update feed for a market. This method will cause the client to emit l3update
events that have a payload of the Level3Update
object.
This method is a no-op for exchanges that do not support level 3 snapshot subscriptions.
Unbusbscribes from the orderbook level 3 updates for a market.
*For some exchanges, calling unsubscribe may cause a temporary disruption in all feeds.
The ticker class is the result of a ticker
event.
exchange: string
- the name of the exchangebase: string
- the normalized base symbol for the marketquote: string
- the normalized quote symbol for the markettimestamp: int
- the unix timestamp in millisecondslast: string
- the last price of a match that caused a tickopen: string
- the price 24 hours agolow: string
- the highest price in the last 24 hourshigh: string
- the lowest price in the last 24 hoursvolume: string
- the base volume traded in the last 24 hoursquoteVolume: string
- the quote volume traded in the last 24 hourschange: string
- the price change (last - open)changePercent: string
- the price change in percent (last - open) / open * 100bid: string
- the best bid pricebidVolume: string
- the volume at the best bid priceask: string
- the best ask priceaskVolume: string
- the volume at the best ask price
The trade class is the result of a trade
event emitted from a client.
exchange: string
- the name of the exchangebase: string
- the normalized base symbol for the marketquote: string
- the normalized quote symbol for the markettradeId: string
- the unique trade identifer from the exchanges feedunix: int
- the unix timestamp in milliseconds for when the trade executedside: string
- whether the buyerbuy
or sellersell
was the maker for the matchprice: string
- the price at which the match executedamount: string
- the amount executed in the matchbuyOrderId: string
- the order id of the buy sidesellOrderId: string
- the order id of the sell side
The candle class is the result of a candle
event emitted from a client.
timestampMs: int
- the unix timestamp in milliseconds for the candleopen: string
- the open price for the periodhigh: string
- the high price for the periodlow: string
- the low price for the periodclose: string
- the close price for the periodvolume: string
- the volume exchanged during the period
Represents a price point in a level 2 orderbook
price: string
- pricesize: string
- aggregated volume for all orders at this price pointcount: int
- optional number of orders aggregated into the price point
The level 2 snapshot class is the result of a l2snapshot
or l2update
event emitted from the client.
exchange: string
- the name of the exchangebase: string
- the normalized base symbol for the marketquote: string
- the normalized quote symbol for the markettimestampMs: int
- optional timestamp in milliseconds for the snapshotsequenceId: int
- optional sequence identifier for the snapshotasks: [Level2Point]
- the ask (seller side) price pointsbids: [Level2Point]
- the bid (buyer side) price points
The level 2 update class is a result of a l2update
event emitted from the client. It consists of a collection of bids/asks even exchanges broadcast single events at a time.
exchange: string
- the name of the exchangebase: string
- the normalized base symbol for the marketquote: string
- the normalized quote symbol for the markettimestampMs: int
- optional timestamp in milliseconds for the snapshotsequenceId: int
- optional sequence identifier for the snapshotasks: [Level2Point]
- the ask (seller side) price pointsbids: [Level2Point]
- the bid (buyer side) price points
Represents a price point in a level 3 orderbook
orderId: string
- identifier for the orderprice: string
- pricesize: string
- volume of the ordermeta: object
- optional exchange specific metadata with additional information about the update.
The level 3 snapshot class is the result of a l3snapshot
or l3update
event emitted from the client.
exchange: string
- the name of the exchangebase: string
- the normalized base symbol for the marketquote: string
- the normalized quote symbol for the markettimestampMs: int
- optional timestamp in milliseconds for the snapshotsequenceId: int
- optional sequence identifier for the snapshotasks: [Level3Point]
- the ask (seller side) price pointsbids: [Level3Point]
- the bid (buyer side) price points
The level 3 update class is a result of a l3update
event emitted from the client. It consists of a collection of bids/asks even exchanges broadcast single events at a time.
Additional metadata is often provided in the meta
property that has more detailed information that is often required to propertly manage a level 3 orderbook.
exchange: string
- the name of the exchangebase: string
- the normalized base symbol for the marketquote: string
- the normalized quote symbol for the markettimestampMs: int
- optional timestamp in milliseconds for the snapshotsequenceId: int
- optional sequence identifier for the snapshotasks: [Level3Point]
- the ask (seller side) price pointsbids: [Level3Point]
- the bid (buyer side) price points