GitHub - airicyu/okx-v5-ws: A Non-Official OKX V5 WebSocket SDK for Node.js

Introduction

This repository hosts a non-official JavaScript SDK for interacting with the OKX V5 WebSocket API. Designed for Node.js, it simplifies WebSocket communication with OKX's trading platform, offering managed methods for common operations like login, subscription, and trading.

Installation

To install the SDK, run:

npm i okx-v5-ws

Quick Start: Hello World Example

Subscribe to a channel topic and log incoming messages using this sample code:

import { OkxV5Ws } from 'okx-v5-ws';

const run = async () => {
  try {
    const okxV5Ws = new OkxV5Ws({
      serverBaseUrl: OkxV5Ws.DEMO_PUBLIC_ENDPOINT,
      options: {
        logLoginMessage: false,
        logSubscriptionMessage: false,
        logChannelTopicMessage: false,
        logTradeMessage: false,
      }
    });
    await okxV5Ws.connect();
    await okxV5Ws.subscribeChannel({
      channel: 'tickers',
      instId: 'BTC-USDT',
    });
    okxV5Ws.addChannelMessageHandler(
      { channel: 'tickers', instId: 'BTC-USDT' },
      (message) => {
        console.log(`Message received: ${JSON.stringify(message)}`);
      }
    );
  } catch (e) {
    console.error(e);
  }
};
run();

Expected Output:

WebSocket Client Connected
subscribe channel {"channel":"tickers","instId":"BTC-USDT"}
send: {"op":"subscribe","args":[{"channel":"tickers","instId":"BTC-USDT"}]}
add ChannelMessageHandler for {"channel":"tickers","instId":"BTC-USDT"}
message handler: {"arg":{"channel":"tickers","instId":"BTC-USDT"},"data":[{"instType":"SPOT","instId":"BTC-USDT","last":"16911","lastSz":"27.6688588","askPx":"16912.3","askSz":"0.0001","bidPx":"16910.5","bidSz":"43.30579595","open24h":"16641.8","high24h":"17121.3","low24h":"16035.8","sodUtc0":"16621.7","sodUtc8":"16592.1","volCcy24h":"22694273441.21289897","vol24h":"1359475.31206937","ts":"1668524928148"}]}
...

Private Endpoint Usage

For private endpoints, include profileConfig with API credentials:

const okxV5Ws = new OkxV5Ws({
  serverBaseUrl: OkxV5Ws.DEMO_PRIVATE_ENDPOINT,
  profileConfig: {
    apiKey: 'YOUR_API_KEY',
    secretKey: 'YOUR_SECRET_KEY',
    passPhrase: 'YOUR_PASSPHRASE',
  },
  // ... other options
});

👉 Learn more about OKX API authentication

Advanced: Free Control Mode

Bypass managed features and handle messages directly:

const okxV5Ws = new OkxV5Ws({
  serverBaseUrl: OkxV5Ws.DEMO_PUBLIC_ENDPOINT,
  // ... other configs
});

okxV5Ws.event.on('message', (message) => {
  console.log(`Received: ${message}`);
});

await okxV5Ws.send({
  op: 'subscribe',
  args: [{ channel: 'status' }],
});

API Reference

OkxV5Ws Class

Constructor

constructor({
  serverBaseUrl: string,
  profileConfig?: {
    apiKey: string;
    secretKey: string;
    passPhrase: string;
  },
  options?: {
    autoLogin?: boolean;
    logLoginMessage?: boolean;
    logSubscriptionMessage?: boolean;
    logChannelTopicMessage?: boolean;
    logTradeMessage?: boolean;
  }
});

Key Methods

• send(payload: object): Send raw messages to the server.
• subscribeChannel(topic: SubscriptionTopic): Subscribe to a channel.
• addChannelMessageHandler(topic, handler): Attach a callback for channel messages.

Limitations

1. Single-Process Operations: Login/subscribe/unsubscribe requests are processed sequentially.
2. No Multi-Account Support: Only single-account login is supported currently.

FAQ

How do I handle reconnections?

The SDK auto-reconnects by default. Use the reconnecting event to track reconnection attempts.

Can I use this SDK for high-frequency trading?

While functional, the SDK lacks advanced optimization for ultra-low-latency scenarios. Consider custom implementations for such use cases.

Where can I report issues?

👉 Visit the GitHub repository to open an issue or contribute.

Conclusion

This SDK provides a streamlined way to interact with OKX's WebSocket API, balancing ease of use with flexibility. For more complex needs, leverage the "Free Control" mode to customize message handling.

For updates and contributions, check the GitHub repository.