woo-api

WARNING: This package is still early beta, following the designs of my other connectors. If you want to stay informed when this may be ready for testing, please get in touch via telegram.

Node.js connector for the woo APIs and WebSockets, with TypeScript & browser support.

Installation

npm install --save woo-api

Issues & Discussion

• Issues? Check the issues tab.
• Discuss & collaborate with other node devs? Join our Node.js Algo Traders engineering community on telegram.

Related projects

Check out my related projects:

• Try my connectors:
  • binance
  • bybit-api
  • okx-api
  • bitget-api
  • bitmart-api
• Try my misc utilities:
  • orderbooks
• Check out my examples:
  • awesome-crypto-examples

Documentation

Most methods accept JS objects. These can be populated using parameters specified by woo's API documentation.

• woo.org API Documentation.

Structure

This project uses typescript. Resources are stored in 3 key structures:

• src - the whole connector written in typescript
• lib - the javascript version of the project (compiled from typescript). This should not be edited directly, as it will be overwritten with each release.
• dist - the packed bundle of the project for use in browser environments.
• examples - some implementation examples & demonstrations. Contributions are welcome!

Usage

WebSockets

Inverse, linear & spot WebSockets can be used via a shared WebsocketClient. However, make sure to make one instance of WebsocketClient per market type (spot vs inverse vs linear vs linearfutures):

const { WebsocketClient } = require('woo-api');

const API_KEY = 'xxx';
const PRIVATE_KEY = 'yyy';

const wsConfig = {
  key: API_KEY,
  secret: PRIVATE_KEY,

  /*
    The following parameters are optional:
  */

  // defaults to false == testnet. Set to true for livenet.
  // livenet: true

  // NOTE: to listen to multiple markets (spot vs inverse vs linear vs linearfutures) at once, make one WebsocketClient instance per market

  // defaults to inverse:
  // market: 'inverse'
  // market: 'linear'
  // market: 'spot'

  // how long to wait (in ms) before deciding the connection should be terminated & reconnected
  // pongTimeout: 1000,

  // how often to check (in ms) that WS connection is still alive
  // pingInterval: 10000,

  // how long to wait before attempting to reconnect (in ms) after connection is closed
  // reconnectTimeout: 500,

  // config options sent to RestClient (used for time sync). See RestClient docs.
  // restOptions: { },

  // config for axios used for HTTP requests. E.g for proxy support
  // requestOptions: { }

  // override which URL to use for websocket connections
  // wsUrl: 'wss://stream.bytick.com/realtime'
};

const ws = new WebsocketClient(wsConfig);

// subscribe to multiple topics at once
ws.subscribe(['position', 'execution', 'trade']);

// and/or subscribe to individual topics on demand
ws.subscribe('kline.BTCUSD.1m');

// Listen to events coming from websockets. This is the primary data source
ws.on('update', (data) => {
  console.log('update', data);
});

// Optional: Listen to websocket connection open event (automatic after subscribing to one or more topics)
ws.on('open', ({ wsKey, event }) => {
  console.log('connection open for websocket with ID: ' + wsKey);
});

// Optional: Listen to responses to websocket queries (e.g. the response after subscribing to a topic)
ws.on('response', (response) => {
  console.log('response', response);
});

// Optional: Listen to connection close event. Unexpected connection closes are automatically reconnected.
ws.on('close', () => {
  console.log('connection closed');
});

// Optional: Listen to raw error events.
// Note: responses to invalid topics are currently only sent in the "response" event.
ws.on('error', (err) => {
  console.error('ERR', err);
});

See websocket-client.ts for further information.

Note: for linear websockets, pass linear: true in the constructor options when instancing the WebsocketClient. To connect to both linear and inverse websockets, make two instances of the WebsocketClient.

Customise Logging

Pass a custom logger which supports the log methods silly, debug, notice, info, warning and error, or override methods from the default logger as desired.

const { WebsocketClient, DefaultLogger } = require('woo-api');

// Disable all logging on the silly level
DefaultLogger.silly = () => {};

const ws = new WebsocketClient({ key: 'xxx', secret: 'yyy' }, DefaultLogger);

Browser Usage

Build a bundle using webpack:

• npm install
• npm build
• npm pack

The bundle can be found in dist/. Altough usage should be largely consistent, smaller differences will exist. Documentation is still TODO.

Contributions & Thanks

Donations

tiagosiebler

Support my efforts to make algo trading accessible to all - register with my referral links:

• Bybit
• Binance
• OKX
• FTX

Or buy me a coffee using any of these:

• BTC: 1C6GWZL1XW3jrjpPTS863XtZiXL1aTK7Jk
• ETH (ERC20): 0xd773d8e6a50758e1ada699bb6c4f98bb4abf82da

Contributions & Pull Requests

Contributions are encouraged, I will review any incoming pull requests. See the issues tab for todo items.