OKX JavaScript SDK

JavaScript SDK Usage

Use framework-neutral JavaScript request and event flows across Node.js-compatible runtimes.

In JavaScript, use the package directly from readable examples. TypeScript remains useful for larger integrations, but the same client patterns work in plain JavaScript.

What This SDK Covers

• Complete OKX REST API integrations for exchange-specific workflows.
• Robust OKX WebSocket support for market and account stream handling.
• JavaScript-friendly usage patterns for production integration work.
• Adaptable JavaScript examples & guides under /examples for implementation reference.
• Framework-neutral JavaScript snippets that stay approachable in all JavaScript runtimes.

Install Package

npm install okx-api
# or
pnpm install okx-api
yarn add okx-api

Quickstart REST API Walkthrough

Quickstart REST API Example

/* eslint-disable @typescript-eslint/no-unused-vars */
import { OrderRequest, RestClient } from 'okx-api';

// read from environmental variables
const API_KEY = process.env.API_KEY_COM;
const API_SECRET = process.env.API_SECRET_COM;
const API_PASS = process.env.API_PASS_COM;

// If running from CLI in unix, you can pass env vars as such:
// API_KEY_COM='lkm12n3-2ba3-1mxf-fn13-lkm12n3a' API_SECRET_COM='035B2B9637E1BDFFEE2646BFBDDB8CE4' API_PASSPHRASE_COM='ComplexPa$!23$5^' ts-node examples/rest-private-trade.ts
// note the single quotes, preventing special characters such as $ from being incorrectly parsed by the shell

if (!API_KEY || !API_SECRET || !API_PASS) {
  throw new Error(
    'Missing api credentials. Use environmental variables or hard code in the script',
  );
}

console.log(new Date(), 'Using credentials: ', {
  API_KEY,
  API_SECRET,
  API_PASS,
});

const client = new RestClient({
  apiKey: API_KEY,
  // apiKey: 'apiKeyHere',
  apiSecret: API_SECRET,
  // apiSecret: 'apiSecretHere',
  apiPass: API_PASS,
  // apiPass: 'apiPassHere',
});

// const wsClient = new WebsocketClient({
//   apiKey: API_KEY,
//   apiSecret: API_SECRET,
//   apiPass: API_PASS,
// });

function logWSEvent(type: string, data: any) {
  console.log(new Date(), `WS ${type} event: `, data);
}

// simple sleep function
function promiseSleep(milliseconds: number) {
  return new Promise((resolve) => setTimeout(resolve, milliseconds));
}

// WARNING: for sensitive math you should be using a library such as decimal.js!
function roundDown(value: any, decimals: number) {
  return Number(
    Math.floor(parseFloat(value + 'e' + decimals)) + 'e-' + decimals,
  );
}

/** This is a simple script wrapped in a immediately invoked function expression, designed to check for any available BTC balance and immediately buy with 50% of the available USDT */
(async () => {
  try {
    // // Add event listeners to log websocket events on account
    // wsClient.on('update', (data) => logWSEvent('update', data));
    // wsClient.on('open', (data) => logWSEvent('open', data));
    // wsClient.on('response', (data) => logWSEvent('response', data));
    // wsClient.on('reconnect', (data) => logWSEvent('reconnect', data));
    // wsClient.on('reconnected', (data) => logWSEvent('reconnected', data));
    // wsClient.on('authenticated', (data) => logWSEvent('authenticated', data));
    // wsClient.on('exception', (data) => logWSEvent('exception', data));

    // // Subscribe to private account topics
    // wsClient.subscribeTopic('SPBL', 'account');
    // wsClient.subscribeTopic('SPBL', 'orders');

    // wait briefly for ws to be ready (could also use the response or authenticated events, to make sure topics are subscribed to before starting)
    await promiseSleep(2.5 * 1000);

    const allBalances = await client.getBalance();
    // const balances = allBalances.filter((bal) => Number(bal.available) != 0);
    const usdtBalanceResult = allBalances[0].details.find(
      (bal) => bal.ccy === 'USDT',
    );
    console.log('BTC balance result: ', usdtBalanceResult);

    const usdtBalance = Number(usdtBalanceResult?.availBal);
    // console.log('balance: ', JSON.stringify(balances, null, 2));

    if (!usdtBalanceResult || !usdtBalance) {
      console.error('No USDT to trade');
      return;
    }

    console.log(`USDT available: ${usdtBalance}`);

    const symbol = 'BTC-USDT';
    const quantity = 0.002;

    const order: OrderRequest = {
      instId: symbol,
      ordType: 'market',
      side: 'buy',
      sz: String(usdtBalance * 0.5),
      tdMode: 'cash',
      tgtCcy: 'base_ccy',
    };

    const buyResult = await client.submitOrder(order);

    console.log('result: ', buyResult);
    return;
    // example to find minimum allowed size for a symbol and place an order with it
    /*  const symbol = 'BTC-USDT-SWAP';

    const symbolsResult = await client.getInstruments({
      instType: 'SWAP',
    });
    const btcRules = symbolsResult.find((rule) => rule.instId === symbol);
    console.log('btc trading rules: ', btcRules);
    if (!btcRules) {
      return console.log('no rules found for trading ' + symbol);
    }

    const minSize = Number(btcRules.minSz);

    const order = {
      instId: symbol,
      tdMode: 'cross',
      ordType: 'market',
      side: 'sell',
      sz: String(minSize),
    } as const;

    console.log('submitting order: ', order);

    const sellResult = await client.submitOrder(order);

    console.log('sell result: ', sellResult); */
  } catch (e) {
    console.error('request failed: ', e);
  }
})();

Quickstart WebSocket Walkthrough

Quickstart WebSocket Example

import { DefaultLogger, WebsocketClient } from 'okx-api';

// Optional: Inject a custom logger.
// This example overrides the default logger to also log "trace" (super verbose) messages, which are disabled by default
const logger = {
  ...DefaultLogger,
  // trace: (...params) => console.log('trace', ...params),
};

// For private events, all 3 of the following are required (per account):
const API_KEY = process.env.API_KEY_COM;
const API_SECRET = process.env.API_SECRET_COM;
const API_PASSPHRASE = process.env.API_PASSPHRASE_COM;

// If running from CLI in unix, you can pass env vars as such:
// API_KEY_COM='lkm12n3-2ba3-1mxf-fn13-lkm12n3a' API_SECRET_COM='035B2B9637E1BDFFEE2646BFBDDB8CE4' API_PASSPHRASE_COM='ComplexPa$!23$5^' ts-node examples/ws-private.ts

// note the single quotes, preventing special characters such as $ from being incorrectly passed

if (!API_KEY) {
  throw new Error('API_KEY is missing');
}

if (!API_SECRET) {
  throw new Error('API_SECRET is missing');
}

if (!API_PASSPHRASE) {
  throw new Error('API_PASSPHRASE is missing');
}

const wsClient = new WebsocketClient(
  {
    // For Global users (www.okx.com), you don't need to set the market.
    // It will use global by default.
    // Not needed: market: 'GLOBAL',

    // For EEA users (my.okx.com), set market to "EEA":
    // market: 'EEA',

    // For US users (app.okx.com), set market to "US":
    // market: 'US',

    accounts: [
      // For private topics, include one or more accounts in an array. Otherwise only public topics will work
      {
        apiKey: API_KEY,
        apiSecret: API_SECRET,
        apiPass: API_PASSPHRASE,
      },
      // {
      //   apiKey: 'yourApiKeyHere',
      //   apiSecret: 'yourApiSecretHere',
      //   apiPass: 'yourApiPassHere',
      // },
      // {
      //   apiKey: 'anotherAccountKey',
      //   apiSecret: 'anotherAccountSecret',
      //   apiPass: 'anotherAccountPass',
      // },
    ],
  },
  logger,
);

// Raw data will arrive on the 'update' event
wsClient.on('update', (data) => {
  // console.log('ws update (raw data received)', JSON.stringify(data, null, 2));
  console.log('ws update (raw data received)', JSON.stringify(data));
});

wsClient.on('open', (data) => {
  console.log('connection opened open:', data.wsKey);
});

// Replies (e.g. authenticating or subscribing to channels) will arrive on the 'response' event
wsClient.on('response', (data) => {
  // console.log('ws response: ', JSON.stringify(data, null, 2));
  console.log('ws response: ', JSON.stringify(data));
});

wsClient.on('reconnect', ({ wsKey }) => {
  console.log('ws automatically reconnecting.... ', wsKey);
});
wsClient.on('reconnected', (data) => {
  console.log('ws has reconnected ', data?.wsKey);
});
wsClient.on('exception', (data) => {
  console.error('ws exception: ', data);
});

// Optional, connect before subscribing:
// wsClient.connectPrivate();

// This is optional though. The wsclient will automatically open and subscribe if the connection doesn't exist yet.

/**
   * # Subscribing to channels
   *
   * Subscribe to channels using the inner "args" part of the subscription request described in the OKX API docs.
   *
   * For example, if the docs state your request should look as such:
   {
     op: "subscribe",
     args: [
       {
         channel: "account"
       }
     ]
   }
   *
   * You should call the wsClient.subscribe function using only the "args".
   *
   * Either of these examples is correct (one channel vs one or more channels in an array):
   wsClient.subscribe({
     channel: 'account'
   });

   wsClient.subscribe([
     {
       channel: "account"
     }
   ])
   */

// Subscribe one event at a time:
wsClient.subscribe({
  channel: 'account',
});

// OR, combine multiple subscription events into one request using an array instead of an object:
wsClient.subscribe([
  {
    channel: 'account',
  },
  {
    channel: 'positions',
    instType: 'ANY',
  },
]);

/**
 * Examples for each private channel listed in the API docs:
 * https://www.okx.com/docs-v5/en/#websocket-api-private-channel
 */

// Account events for all symbols
wsClient.subscribe({
  channel: 'account',
});

// Account events for specific symbol only
wsClient.subscribe({
  channel: 'account',
  ccy: 'BTC',
});

// Withdrawal events for specific symbol only
wsClient.subscribe({
  channel: 'withdrawal-info',
  ccy: 'BTC',
});

// Position events on any instrument type
wsClient.subscribe({
  channel: 'positions',
  instType: 'ANY',
});

// Position events on specific instruments
wsClient.subscribe({
  channel: 'positions',
  instType: 'SWAP',
  instFamily: 'ETH-USD',
  instId: 'ETH-USD-SWAP',
});

// Balance & position channel
wsClient.subscribe({
  channel: 'balance_and_position',
});

// Order channel
wsClient.subscribe({
  channel: 'orders',
  instType: 'ANY',
});

// Order channel with extra args
wsClient.subscribe({
  channel: 'orders',
  instType: 'FUTURES',
  instFamily: 'BTC-USD',
});

// Algo orders channel
wsClient.subscribe({
  channel: 'orders-algo',
  instType: 'ANY',
});

// Advance algo orders channel
wsClient.subscribe({
  channel: 'algo-advance',
  instType: 'ANY',
});

// Position risk warning channel
wsClient.subscribe({
  channel: 'liquidation-warning',
  instType: 'ANY',
});

// Account greeks channel
wsClient.subscribe({
  channel: 'account-greeks',
});

// Spot grid algo orders channel
wsClient.subscribe({
  channel: 'grid-orders-spot',
  instType: 'SPOT',
});

// Contract grid orders channel
wsClient.subscribe({
  channel: 'grid-orders-contract',
  instType: 'ANY',
});

// Moon grid orders channel
wsClient.subscribe({
  channel: 'grid-orders-moon',
  instType: 'ANY',
});

// Moon grid orders channel
wsClient.subscribe({
  channel: 'grid-orders-moon',
  instType: 'ANY',
});

// Grid positions channel
wsClient.subscribe({
  channel: 'grid-positions',
  algoId: '449327675342323712',
});

// Grid sub orders channel
wsClient.subscribe({
  channel: 'grid-sub-orders',
  algoId: '449327675342323712',
});

Quickstart WebSocket API Walkthrough

Quickstart WebSocket API Example

import { DefaultLogger, WebsocketAPIClient } from 'okx-api';

// function attachEventHandlers<TWSClient extends WebsocketClient>(
//   wsClient: TWSClient,
// ): void {
//   wsClient.on('update', (data) => {
//     console.log('raw message received ', JSON.stringify(data));
//   });
//   wsClient.on('open', (data) => {
//     console.log('ws connected', data.wsKey);
//   });
//   wsClient.on('reconnect', ({ wsKey }) => {
//     console.log('ws automatically reconnecting.... ', wsKey);
//   });
//   wsClient.on('reconnected', (data) => {
//     console.log('ws has reconnected ', data?.wsKey);
//   });
//   wsClient.on('authenticated', (data) => {
//     console.log('ws has authenticated ', data?.wsKey);
//   });
// }

(async () => {
  const logger = {
    ...DefaultLogger,
    trace: (...params: any[]) => console.log('trace', ...params),
  };

  // For private events, all 3 of the following are required (per account):
  const API_KEY = process.env.API_KEY_COM;
  const API_SECRET = process.env.API_SECRET_COM;
  const API_PASSPHRASE = process.env.API_PASSPHRASE_COM;

  // If running from CLI in unix, you can pass env vars as such:
  // API_KEY_COM='lkm12n3-2ba3-1mxf-fn13-lkm12n3a' API_SECRET_COM='035B2B9637E1BDFFEE2646BFBDDB8CE4' API_PASSPHRASE_COM='ComplexPa$!23$5^' ts-node examples/ws-private.ts

  const wsClient = new WebsocketAPIClient(
    {
      // For Global users (www.okx.com), you don't need to set the market.
      // It will use global by default.
      // Not needed: market: 'GLOBAL',

      // For EEA users (my.okx.com), set market to "EEA":
      // market: 'EEA',

      // For US users (app.okx.com), set market to "US":
      // market: 'US',

      accounts: [
        // For private topics, include one or more accounts in an array. Otherwise only public topics will work
        {
          apiKey: API_KEY || '',
          apiSecret: API_SECRET || '',
          apiPass: API_PASSPHRASE || '',
        },
      ],
    },
    logger,
  );

  // Optional, see above "attachEventListeners". Attach basic event handlers, so nothing is left unhandled
  // attachEventHandlers(wsClient.getWSClient());

  // Optional: prepare the WebSocket API connection in advance.
  // This happens automatically but you can do this early before making any API calls, to prevent delays from a cold start.
  // await wsClient.connectWSAPI();

  /**
   * OKX's WebSocket API be used like a REST API, through this SDK's WebsocketAPIClient. The WebsocketAPIClient is a utility class wrapped around WebsocketClient's sendWSAPIRequest() capabilities.
   *
   * Each request sent via the WebsocketAPIClient will automatically:
   * - route via the active WS API connection
   * - return a Promise, which automatically resolves/rejects when a matching response is received
   */

  /**
   * Place Order
   * https://www.okx.com/docs-v5/en/#order-book-trading-trade-ws-place-order
   */
  try {
    const res = await wsClient.submitNewOrder({
      instId: 'BTC-USDT',
      tdMode: 'cash',
      side: 'buy',
      ordType: 'market',
      sz: '100',
    });
    /**
      const res = {
        id: '2',
        op: 'order',
        code: '1',
        msg: '',
        data: [
          {
            tag: '159881cb7207BCDE',
            ts: '1753714603721',
            ordId: '',
            clOrdId: '',
            sCode: '51008',
            sMsg: 'Order failed. Insufficient USDT balance in account.'
          }
        ],
        inTime: '1753714603720755',
        outTime: '1753714603721942',
        wsKey: 'prodPrivate',
        isWSAPIResponse: false
      }

      const res =  {
        id: '2',
        op: 'order',
        code: '1',
        msg: '',
        data: [
          {
            tag: '159881cb7207BCDE',
            ts: '1753714567149',
            ordId: '',
            clOrdId: '',
            sCode: '51010',
            sMsg: "You can't complete this request under your current account mode."
          }
        ],
        inTime: '1753714567149196',
        outTime: '1753714567149913',
        wsKey: 'prodPrivate',
        isWSAPIResponse: false
      }
     */

    console.log(new Date(), 'WS API "submitNewOrder()" result: ', res);
  } catch (e) {
    console.error(new Date(), 'Exception with WS API "submitNewOrder()": ', e);
  }

  /**
   * Submit multiple orders in a batch
   * https://www.okx.com/docs-v5/en/#order-book-trading-trade-ws-place-multiple-orders
   */
  try {
    const res = await wsClient.submitMultipleOrders([
      {
        instId: 'BTC-USDT',
        tdMode: 'cash',
        side: 'buy',
        ordType: 'market',
        sz: '100',
      },
      {
        instId: 'BTC-USDT',
        tdMode: 'cash',
        side: 'buy',
        ordType: 'market',
        sz: '50',
      },
    ]);
    console.log(new Date(), 'WS API "submitMultipleOrders()" result: ', res);
  } catch (e) {
    console.error(
      new Date(),
      'Exception with WS API "submitMultipleOrders()": ',
      e,
    );
  }

  console.log(new Date(), 'Reached end of example.');
})();

Endpoint Function Reference

Source: View endpoint map source

OKX JavaScript FAQ

Direct Example Files

Open the example files below if you want the clearest general-purpose starting point for REST API, WebSocket, and authentication workflows in plain JavaScript.

• OKX REST API example file (OKX/Rest/rest-private-trade.ts)
• OKX WebSocket example file (OKX/Websocket/ws-private.ts)
• OKX WebSocket API example file (OKX/Websocket/WS-API/ws-api-client.ts)

Reference Links

• npm: okx-api
• GitHub: okx-api
• Release feed
• Support and feature requests