224 lines
7.1 KiB
Markdown
224 lines
7.1 KiB
Markdown
# Websocket API
|
|
## Class: WebsocketClient
|
|
|
|
The `WebsocketClient` inherits from `EventEmitter`. After establishing a
|
|
connection, the client sends heartbeats in regular intervalls, and reconnects
|
|
to the server once connection has been lost.
|
|
|
|
### new WebsocketClient([options][, logger])
|
|
- `options` {Object} Configuration options
|
|
- `key` {String} Bybit API Key. Only needed if private topics are subscribed
|
|
- `secret` {String} Bybit private Key. Only needed if private topics are
|
|
subscribed
|
|
- `livenet` {Bool} Weather to connect to livenet (`true`). Default `false`.
|
|
- `pingInterval` {Integer} Interval in ms for heartbeat ping. Default: `10000`,
|
|
- `pongTimeout` {Integer} Timeout in ms waiting for heartbeat pong response
|
|
from server. Default: `1000`,
|
|
- `reconnectTimeout` {Integer} Timeout in ms the client waits before trying
|
|
to reconnect after a lost connection. Default: 500
|
|
- `logger` {Object} Optional custom logger
|
|
|
|
Custom logger must contain the following methods:
|
|
```js
|
|
const logger = {
|
|
silly: function(message, data) {},
|
|
debug: function(message, data) {},
|
|
notice: function(message, data) {},
|
|
info: function(message, data) {},
|
|
warning: function(message, data) {},
|
|
error: function(message, data) {},
|
|
}
|
|
```
|
|
|
|
### ws.subscribe(topics)
|
|
- `topics` {String|Array} Single topic as string or multiple topics as array of strings.
|
|
Subscribe to one or multiple topics. See [available topics](#available-topics)
|
|
|
|
### ws.unsubscribe(topics)
|
|
- `topics` {String|Array} Single topic as string or multiple topics as array of strings.
|
|
Unsubscribe from one or multiple topics.
|
|
|
|
### ws.close()
|
|
Close the connection to the server.
|
|
|
|
### Event: 'open'
|
|
Emmited when the connection has been opened for the first time.
|
|
|
|
### Event: 'reconnected'
|
|
Emmited when the client has been opened after a reconnect.
|
|
|
|
### Event: 'update'
|
|
- `message` {Object}
|
|
- `topic` {String} the topic for which the update occured
|
|
- `data` {Array|Object} updated data (see docs for each [topic](#available-topics)).
|
|
- `type` {String} Some topics might have different update types (see docs for each [topic](#available-topics)).
|
|
|
|
Emmited whenever an update to a subscribed topic occurs.
|
|
|
|
### Event: 'response'
|
|
- `response` {Object}
|
|
- `success` {Bool}
|
|
- `ret_msg` {String} empty if operation was successfull, otherwise error message.
|
|
- `conn_id` {String} connection id
|
|
- `request` {Object} Original request, to which the response belongs
|
|
- `op` {String} operation
|
|
- `args` {Array} Request Arguments
|
|
|
|
Emited when the server responds to an operation sent by the client (usually after subscribing to a topic).
|
|
|
|
### Event: 'close'
|
|
Emitted when the connection has been finally closed, after a call to `ws.close()`
|
|
|
|
### Event: 'reconnect'
|
|
Emitted when the connection has been closed, but the client will try to reconnect.
|
|
|
|
### Event: 'error'
|
|
- `error` {Error}
|
|
|
|
Emitted when an error occurs.
|
|
|
|
## Available Topics
|
|
Generaly all [public](https://bybit-exchange.github.io/docs/inverse/#t-publictopics) and [private](https://bybit-exchange.github.io/docs/inverse/#t-privatetopics)
|
|
topics are available.
|
|
|
|
### Private topics
|
|
#### Positions of your account
|
|
All positions of your account.
|
|
Topic: `position`
|
|
|
|
[See bybit documentation](https://bybit-exchange.github.io/docs/inverse/#t-websocketposition)
|
|
|
|
#### Execution message
|
|
Execution message, whenever an order has been (partially) filled.
|
|
Topic: `execution`
|
|
|
|
[See bybit documentation](https://bybit-exchange.github.io/docs/inverse/#t-websocketexecution)
|
|
|
|
#### Update for your orders
|
|
Updates for your active orders
|
|
Topic: `order`
|
|
|
|
[See bybit documentation](https://bybit-exchange.github.io/docs/inverse/#t-websocketorder)
|
|
|
|
#### Update for your conditional orders
|
|
Updates for your active conditional orders
|
|
Topic: `stop_order`
|
|
|
|
[See bybit documentation](https://bybit-exchange.github.io/docs/inverse/#t-websocketstoporder)
|
|
|
|
### Public topics
|
|
#### Candlestick chart
|
|
Candlestick OHLC "candles" for selected symbol and interval.
|
|
Example topic: `klineV2.BTCUSD.1m`
|
|
|
|
[See bybit documentation](https://bybit-exchange.github.io/docs/inverse/#t-websocketklinev2)
|
|
|
|
#### Real-time trading information
|
|
All trades as they occur.
|
|
Topic: `trade`
|
|
|
|
[See bybit documentation](https://bybit-exchange.github.io/docs/inverse/#t-websockettrade)
|
|
|
|
#### Daily insurance fund update
|
|
Topic: `insurance`
|
|
|
|
[See bybit documentation](https://bybit-exchange.github.io/docs/inverse/#t-websocketinsurance)
|
|
|
|
#### OrderBook of 25 depth per side
|
|
OrderBook for selected symbol
|
|
Example topic: `orderBookL2_25.BTCUSD`
|
|
|
|
[See bybit documentation](https://bybit-exchange.github.io/docs/inverse/#t-websocketorderbook25)
|
|
|
|
#### OrderBook of 200 depth per side
|
|
OrderBook for selected symbol
|
|
Example topic: `orderBook_200.100ms.BTCUS`
|
|
|
|
[See bybit documentation](https://bybit-exchange.github.io/docs/inverse/#t-websocketorderbook200)
|
|
|
|
#### Latest information for symbol
|
|
Latest information for selected symbol
|
|
Example topic: `instrument_info.100ms.BTCUSD`
|
|
|
|
[See bybit documentation](https://bybit-exchange.github.io/docs/inverse/#t-websocketinstrumentinfo)
|
|
|
|
## Examples
|
|
### Klines
|
|
```javascript
|
|
const {WebsocketClient} = require('bybit-api');
|
|
|
|
const API_KEY = 'xxx';
|
|
const PRIVATE_KEY = 'yyy';
|
|
|
|
const ws = new WebsocketClient({key: API_KEY, secret: PRIVATE_KEY});
|
|
|
|
ws.subscribe(['position', 'execution', 'trade']);
|
|
ws.subscribe('kline.BTCUSD.1m');
|
|
|
|
ws.on('open', function() {
|
|
console.log('connection open');
|
|
});
|
|
|
|
ws.on('update', function(message) {
|
|
console.log('update', message);
|
|
});
|
|
|
|
ws.on('response', function(response) {
|
|
console.log('response', response);
|
|
});
|
|
|
|
ws.on('close', function() {
|
|
console.log('connection closed');
|
|
});
|
|
|
|
ws.on('error', function(err) {
|
|
console.error('ERR', err);
|
|
});
|
|
```
|
|
|
|
### OrderBook Events
|
|
```javascript
|
|
const { WebsocketClient, DefaultLogger } = require('bybit-api');
|
|
const { OrderBooksStore, OrderBookLevel } = require('orderbooks');
|
|
|
|
const OrderBooks = new OrderBooksStore({ traceLog: true, checkTimestamps: false });
|
|
|
|
// connect to a websocket and relay orderbook events to handlers
|
|
DefaultLogger.silly = () => {};
|
|
const ws = new WebsocketClient({ livenet: true });
|
|
ws.on('update', message => {
|
|
if (message.topic.toLowerCase().startsWith('orderbook')) {
|
|
return handleOrderbookUpdate(message);
|
|
}
|
|
});
|
|
ws.subscribe('orderBookL2_25.BTCUSD');
|
|
|
|
// parse orderbook messages, detect snapshot vs delta, and format properties using OrderBookLevel
|
|
const handleOrderbookUpdate = message => {
|
|
const { topic, type, data, timestamp_e6 } = message;
|
|
const [ topicKey, symbol ] = topic.split('.');
|
|
|
|
if (type == 'snapshot') {
|
|
return OrderBooks.handleSnapshot(symbol, data.map(mapBybitBookSlice), timestamp_e6 / 1000, message).print();
|
|
}
|
|
|
|
if (type == 'delta') {
|
|
const deleteLevels = data.delete.map(mapBybitBookSlice);
|
|
const updateLevels = data.update.map(mapBybitBookSlice);
|
|
const insertLevels = data.insert.map(mapBybitBookSlice);
|
|
return OrderBooks.handleDelta(
|
|
symbol,
|
|
deleteLevels,
|
|
updateLevels,
|
|
insertLevels,
|
|
timestamp_e6 / 1000
|
|
).print();
|
|
}
|
|
}
|
|
|
|
// Low level map of exchange properties to expected local properties
|
|
const mapBybitBookSlice = level => {
|
|
return OrderBookLevel(level.symbol, +level.price, level.side, level.size);
|
|
};
|
|
```
|