\n\n[1]: https://www.npmjs.com/package/okx-api\n\n> [!TIP]\n> Upcoming change: As part of the [Siebly.io](https://siebly.io/?ref=ghokx) brand, this SDK is now hosted under our [Siebly.io GitHub organisation](https://github.com/sieblyio). The migration is seamless and requires no user changes.\n\nComplete, updated & performant Node.js SDK for the OKX(OKEX) APIs and WebSockets:\n\n- Complete integration with OKX REST APIs, WebSockets & WebSocket APIs.\n- TypeScript support (with type declarations for most API requests & responses).\n- Over 100 end-to-end tests making real API calls & WebSocket connections, validating any changes before they reach npm.\n- Supports all available OKX regions:\n - OKX Global (www.okx.com), by default.\n - OKX EEA (my.okx.com), by setting `market: 'EEA'`.\n - OKX US (app.okx.com), by setting `market: 'US'`.\n- Actively maintained with a modern, promise-driven interface.\n- Robust WebSocket integration\n - Configurable connection heartbeats (automatically detect failing connections).\n - Automatic reconnect then resubscribe workflows.\n - Automatic authentication and heartbeat handling.\n- Supports WebSocket API in all supported regions & product groups:\n - Use the WebsocketClient's event-driven `sendWSAPIRequest()` method, or;\n - Use the WebsocketAPIClient for a REST-like experience.\n - Use the WebSocket API like a REST API!\n - Automatic routing to business vs private WebSocket endpoints.\n - End to end types.\n - See [examples/ws-api-client.ts](./examples/ws-api-client.ts) for a demonstration.\n- Browser support (via webpack bundle - see \"Browser Usage\" below).\n- QuickStart Guide: https://siebly.io/sdk/okx/javascript\n- OKX JavaScript Tutorial: https://siebly.io/sdk/okx/javascript/tutorial\n\n## Table of Contents\n\n- [Installation](#installation)\n- [Issues & Discussion](#issues--discussion)\n- [Related Projects](#related-projects)\n- [Documentation](#documentation)\n- [Contributions & Thanks](#contributions--thanks)\n- [Structure](#structure)\n- [Usage](#usage)\n - [REST Client](#rest-client)\n - [Requests & Responses](#requests--responses)\n - [Example](#example)\n - [WebSockets](#websockets)\n - [Sending Orders via WebSockets](#sending-orders-via-websockets)\n - [Receiving Realtime Data](#receiving-realtime-data)\n - [Public Events](#public-events)\n - [Private Events](#private-events)\n- [Browser/Frontend Usage](#browserfrontend-usage)\n - [Import](#import)\n - [Webpack](#webpack)\n- [Use with LLMs & AI](#use-with-llms--ai)\n- [Contributions & Pull Requests](#contributions--pull-requests)\n- [Used By](#used-by)\n- [Star History](#star-history)\n\n## Installation\n\n```bash\nnpm install okx-api\n```\n\n## Issues & Discussion\n\n- Issues? Check the [issues tab](https://github.com/sieblyio/okx-api/issues).\n- Discuss & collaborate with other node devs? Join our [Node.js Algo Traders](https://t.me/nodetraders) engineering community on telegram.\n- Follow our announcement channel for real-time updates on [X/Twitter](https://x.com/sieblyio)\n\n\n\n## Related Projects\n\nCheck out our JavaScript/TypeScript/Node.js SDKs & Projects:\n\n- Visit our website: [https://Siebly.io](https://siebly.io/)\n- Try our REST API & WebSocket SDKs published on npmjs:\n - [Bybit JavaScript SDK: bybit-api](https://www.npmjs.com/package/bybit-api)\n - [Kraken JavaScript SDK: @siebly/kraken-api](https://www.npmjs.com/package/@siebly/kraken-api)\n - [OKX JavaScript SDK: okx-api](https://www.npmjs.com/package/okx-api)\n - [Binance JavaScript SDK: binance](https://www.npmjs.com/package/binance)\n - [Gate (gate.com) JavaScript SDK: gateio-api](https://www.npmjs.com/package/gateio-api)\n - [Bitget JavaScript SDK: bitget-api](https://www.npmjs.com/package/bitget-api)\n - [Kucoin JavaScript SDK: kucoin-api](https://www.npmjs.com/package/kucoin-api)\n - [Coinbase JavaScript SDK: coinbase-api](https://www.npmjs.com/package/coinbase-api)\n - [HTX JavaScript SDK: @siebly/htx-api](https://www.npmjs.com/package/@siebly/htx-api)\n- Try my misc utilities:\n - [OrderBooks Node.js: orderbooks](https://www.npmjs.com/package/orderbooks)\n - [Crypto Exchange Account State Cache: accountstate](https://www.npmjs.com/package/accountstate)\n- Check out my examples:\n - [awesome-crypto-examples Node.js](https://github.com/sieblyio/awesome-crypto-examples)\n \n\n## Documentation\n\nMost methods accept JS objects. These can be populated using parameters specified by okx's API documentation, or check the type definition in the rest-client class methods.\n\n- [RestClient](src/rest-client.ts)\n- [OKX API Documentation](https://www.okx.com/docs-v5/en/#rest-api)\n- [REST Endpoint Function List](./docs/endpointFunctionList.md)\n\n## Contributions & Thanks\n\nSupport my efforts to make algo trading accessible to all - register with my referral links:\n\n- [Bybit](https://www.bybit.com/en-US/register?affiliate_id=9410&language=en-US&group_id=0&group_type=1)\n- [Binance](https://www.binance.com/en/register?ref=20983262)\n- [OKX](https://www.okx.com/join/18504944)\n\nFor more ways to give thanks & support my efforts, visit [Contributions & Thanks](https://github.com/sieblyio/awesome-crypto-examples/wiki/Contributions-&-Thanks)!\n\n## Structure\n\nThis project uses typescript. Resources are stored in 3 key structures:\n\n- [src](./src) - the whole connector written in typescript\n- [lib](./lib) - the javascript version of the project (compiled from typescript). This should not be edited directly, as it will be overwritten with each release. This is also the version published to npm.\n- [dist](./dist) - the packed bundle of the project for use in browser environments (manual, using webpack).\n- [examples](./examples) - some implementation examples & demonstrations. Contributions are welcome!\n\n---\n\n## Usage\n\nCreate API credentials at okx\n\n- [OKX/account/API](https://www.okx.com/account/my-api)\n\n## REST Client\n\n### Requests & Responses\n\n- If your IDE doesn't have IntelliSense, check the [rest-client.ts](./src/rest-client.ts) for a list of methods, params & return types.\n- Requests follow the same ordering and format as the categories in the [API docs](https://www.okx.com/docs-v5/en/#rest-api).\n- Responses are parsed automatically for less nesting. Error responses are thrown in full:\n - If the response looks successful (HTTP 200 and \"code\" in the response body === \"0\"), only the `data` property is directly (without the `code`, `data` & `msg` properties).\n - If the response looks like an error (HTTP error OR the \"code\" property in the response does not equal \"0\"), the full response is thrown (including `code` and `msg` properties). See the interface for [APIResponse](./src/types/rest/shared.ts).\n\n### Example\n\n```ts\nimport { RestClient } from 'okx-api';\n\nconst client = new RestClient({\n apiKey: 'apiKeyHere',\n apiSecret: 'apiSecretHere',\n apiPass: 'apiPassHere',\n // For Global users (www.okx.com), you don't need to set the market.\n // It will use global by default.\n // Not needed: market: 'GLOBAL',\n\n // For EEA users (my.okx.com), set market to \"EEA\":\n // market: 'EEA',\n\n // For US users (app.okx.com), set market to \"US\":\n // market: 'US',\n});\n\n// Submit a buy and sell market order\n(async () => {\n try {\n const allBalances = await client.getBalance();\n console.log('All balances: ', allBalances);\n\n const buyResult = await client.submitOrder({\n instId: 'BTC-USDT',\n ordType: 'market',\n side: 'buy',\n sz: '0.1',\n tdMode: 'cash',\n tgtCcy: 'base_ccy',\n });\n console.log('buy order result: ', buyResult);\n\n const sellResult = await client.submitOrder({\n instId: 'BTC-USDT',\n ordType: 'market',\n side: 'sell',\n sz: '0.1',\n tdMode: 'cash',\n tgtCcy: 'base_ccy',\n });\n console.log('Sell order result: ', sellResult);\n } catch (e) {\n console.error('request failed: ', e);\n }\n})();\n```\n\n## WebSockets\n\nThis connector includes a high-performance Node.js, TypeScript & JavaScript WebSocket client for the OKX public & private WebSocket, including the OKX WebSocket API for order placement. API credentials are optional unless private streams will be used (such as account order updates).\n\n- If your IDE doesn't have IntelliSense, check the [websocket-client.ts](./src/websocket-client.ts) for a list of methods, params & return types.\n- When subscribing to channels, only the \"args\" should be passed as an object or array when calling the websocket client subcribe() function: [API docs](https://www.okx.com/docs-v5/en/#websocket-api-subscribe).\n- TypeScript recommended (but it is not required) for a richer experience:\n \n- The ws client will automatically open connections as needed when subscribing to a channel.\n- If the connection is lost for any reason, the ws client will detect this (via the connection heartbeats). It will then:\n - Automatically teardown the dead connection.\n - Automatically respawn a fresh connection.\n - Automatically reauthenticate, if using private channels.\n - Automatically resubscribe to previously subscribed topics.\n - Resume producing events as before, without extra handling needed in your logic.\n- The ws client will automatically authenticate if accounts are provided and a private channel is subscribed to.\n- Up to 100 accounts are supported on the private connection, as per the [API docs](https://www.okx.com/docs-v5/en/#websocket-api-login). Authentication is automatic if accounts are provided.\n- For examples in using the websocket client, check the examples in the repo:\n - Private channels (account data): [examples/ws-private.ts](./examples/ws-private.ts)\n - Public chanels (market data): [examples/ws-public.ts](./examples/ws-public.ts)\n - These examples are written in TypeScript, so can be executed with ts-node for easy testing:\n `ts-node examples/ws-private.ts`\n - Or convert them to javascript:\n - Change the `import { ... } from 'okx-api'` to `const { ... } = require('okx-api');`\n - Rename the file to `ws-private.js`\n - And execute with node: `node examples/ws-private.js`\n\n### Sending orders via WebSockets\n\nOKX supports some order management capabilities via a persisted WebSocket connection. This SDK supports this with two convenient approaches.\n\nThe recommended route is to use the dedicated WebsocketAPIClient class, included with this SDK:\n\n- Dedicated functions for every available WebSocket API operation\n- Fully typed requests and responses\n- Asynchronous promisified wrapper around WS API commands.\n\nIt looks & feels like a REST API client, but uses WebSockets, via the WebsocketClient's sendWSAPIRequest method (which you can use directly if you prefer).\n\nA simple example is below but for a more thorough example, check the example here: [./examples/ws-api-client.ts](./examples/ws-api-client.ts).\n\n```typescript\nimport { WebsocketAPIClient } from 'okx-api';\n// or if you prefer require:\n// const { WebsocketAPIClient } = require(\"okx-api\");\n\n// For private events, all 3 of the following are required (per account):\nconst API_KEY = process.env.API_KEY_COM;\nconst API_SECRET = process.env.API_SECRET_COM;\nconst API_PASSPHRASE = process.env.API_PASSPHRASE_COM;\n\n// If running from CLI in unix, you can pass env vars as such:\n// API_KEY_COM='lkm12n3-2ba3-1mxf-fn13-lkm12n3a' API_SECRET_COM='035B2B9637E1BDFFEE2646BFBDDB8CE4' API_PASSPHRASE_COM='ComplexPa$$!23$5^' ts-node examples/ws-private.ts\n\nconst wsClient = new WebsocketAPIClient({\n // For Global users (www.okx.com), you don't need to set the market.\n // It will use global by default.\n // Not needed: market: 'GLOBAL',\n\n // For EEA users (my.okx.com), set market to \"EEA\":\n // market: 'EEA',\n\n // For US users (app.okx.com), set market to \"US\":\n // market: 'US',\n\n accounts: [\n {\n apiKey: API_KEY,\n apiSecret: API_SECRET,\n apiPass: API_PASSPHRASE,\n },\n ],\n});\n\nasync function start() {\n // Optional: prepare the WebSocket API connection in advance.\n // This happens automatically but you can do this early before making any API calls, to prevent delays from a cold start.\n // await wsClient.connectWSAPI();\n\n /**\n * 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.\n *\n * Each request sent via the WebsocketAPIClient will automatically:\n * - route via the active WS API connection\n * - return a Promise, which automatically resolves/rejects when a matching response is received\n */\n\n /**\n * Place Order\n * https://www.okx.com/docs-v5/en/#order-book-trading-trade-ws-place-order\n */\n try {\n const res = await wsClient.submitNewOrder({\n instId: 'BTC-USDT',\n tdMode: 'cash',\n side: 'buy',\n ordType: 'market',\n sz: '100',\n });\n /**\n const res = {\n id: '2',\n op: 'order',\n code: '1',\n msg: '',\n data: [\n {\n tag: '159881cb7207BCDE',\n ts: '1753714603721',\n ordId: '',\n clOrdId: '',\n sCode: '51008',\n sMsg: 'Order failed. Insufficient USDT balance in account.'\n }\n ],\n inTime: '1753714603720755',\n outTime: '1753714603721942',\n wsKey: 'prodPrivate',\n isWSAPIResponse: false\n }\n\n const res = {\n id: '2',\n op: 'order',\n code: '1',\n msg: '',\n data: [\n {\n tag: '159881cb7207BCDE',\n ts: '1753714567149',\n ordId: '',\n clOrdId: '',\n sCode: '51010',\n sMsg: \"You can't complete this request under your current account mode.\"\n }\n ],\n inTime: '1753714567149196',\n outTime: '1753714567149913',\n wsKey: 'prodPrivate',\n isWSAPIResponse: false\n }\n */\n\n console.log(new Date(), 'WS API \"submitNewOrder()\" result: ', res);\n } catch (e) {\n console.error(new Date(), 'Exception with WS API \"submitNewOrder()\": ', e);\n }\n\n /**\n * Submit multiple orders in a batch\n * https://www.okx.com/docs-v5/en/#order-book-trading-trade-ws-place-multiple-orders\n */\n try {\n const res = await wsClient.submitMultipleOrders([\n {\n instId: 'BTC-USDT',\n tdMode: 'cash',\n side: 'buy',\n ordType: 'market',\n sz: '100',\n },\n {\n instId: 'BTC-USDT',\n tdMode: 'cash',\n side: 'buy',\n ordType: 'market',\n sz: '50',\n },\n ]);\n console.log(new Date(), 'WS API \"submitMultipleOrders()\" result: ', res);\n } catch (e) {\n console.error(\n new Date(),\n 'Exception with WS API \"submitMultipleOrders()\": ',\n e,\n );\n }\n}\n\nstart();\n```\n\n### Receiving realtime data\n\nThe below example demonstrates connecting as a consumer, to receive WebSocket events from OKX, using the included WebsocketClient:\n\n```javascript\nimport { WebsocketClient } from 'okx-api';\n// or if you prefer require:\n// const { WebsocketClient } = require(\"okx-api\");\n\n// For private events, all 3 of the following are required (per account):\nconst API_KEY = process.env.API_KEY_COM;\nconst API_SECRET = process.env.API_SECRET_COM;\nconst API_PASSPHRASE = process.env.API_PASSPHRASE_COM;\n\n// If running from CLI in unix, you can pass env vars as such:\n// API_KEY_COM='lkm12n3-2ba3-1mxf-fn13-lkm12n3a' API_SECRET_COM='035B2B9637E1BDFFEE2646BFBDDB8CE4' API_PASSPHRASE_COM='ComplexPa$$!23$5^' ts-node examples/ws-private.ts\n\n// Note the single quotes, preventing special characters such as $ from being incorrectly passed\n\nconst wsClient = new WebsocketClient({\n // For Global users (www.okx.com), you don't need to set the market.\n // It will use global by default.\n // Not needed: market: 'GLOBAL',\n\n // For EEA users (my.okx.com), set market to \"EEA\":\n // market: 'EEA',\n\n // For US users (app.okx.com), set market to \"US\":\n // market: 'US',\n\n accounts: [\n // For private topics, include one or more accounts in an array. Otherwise only public topics will work\n {\n apiKey: API_KEY,\n apiSecret: API_SECRET,\n apiPass: API_PASSPHRASE,\n },\n // {\n // apiKey: 'yourApiKeyHere',\n // apiSecret: 'yourApiSecretHere',\n // apiPass: 'yourApiPassHere',\n // },\n // {\n // apiKey: 'anotherAccountKey',\n // apiSecret: 'anotherAccountSecret',\n // apiPass: 'anotherAccountPass',\n // },\n ],\n});\n\n// Raw data will arrive on the 'update' event\nwsClient.on('update', (data) => {\n console.log('ws update (raw data received)', JSON.stringify(data));\n});\n\nwsClient.on('open', (data) => {\n console.log('connection opened open:', data.wsKey);\n});\n\n// Replies (e.g. authenticating or subscribing to channels) will arrive on the 'response' event\nwsClient.on('response', (data) => {\n // console.log('ws response: ', JSON.stringify(data, null, 2));\n console.log('ws response: ', JSON.stringify(data));\n});\n\nwsClient.on('reconnect', ({ wsKey }) => {\n console.log('ws automatically reconnecting.... ', wsKey);\n});\nwsClient.on('reconnected', (data) => {\n console.log('ws has reconnected ', data?.wsKey);\n});\nwsClient.on('exception', (data) => {\n console.error('ws exception: ', data);\n});\n\n/**\n * Simply call subscribe to request the channels that you're interested in.\n *\n * If authentication is required, the WSClient will automatically authenticate with the available credentials.\n */\n\n// Subscribe one event at a time:\nwsClient.subscribe({\n channel: 'account',\n});\n\n// OR, combine multiple subscription events into one request using an array instead of an object:\nwsClient.subscribe([\n {\n channel: 'account',\n },\n {\n channel: 'positions',\n instType: 'ANY',\n },\n]);\n\n// Public topics, for comparison. These do not require authentication / api keys:\nwsClient.subscribe([\n {\n channel: 'instruments',\n instType: 'SPOT',\n },\n {\n channel: 'instruments',\n instType: 'FUTURES',\n },\n {\n channel: 'tickers',\n instId: 'LTC-BTC',\n },\n]);\n```\n\n#### Public Events\n\nSee [examples/ws-public.ts](./examples/ws-public.ts) for a full example:\n\n\n\n#### Private Events\n\nSee [examples/ws-private.ts](./examples/ws-private.ts) for a full example:\n\n\n\n## Browser/Frontend Usage\n\n### Import\n\nThis is the \"modern\" way, allowing the package to be directly imported into frontend projects with full typescript support.\n\n1. Install these dependencies\n ```sh\n npm install crypto-browserify stream-browserify\n ```\n2. Add this to your `tsconfig.json`\n ```json\n {\n \"compilerOptions\": {\n \"paths\": {\n \"crypto\": [\n \"./node_modules/crypto-browserify\"\n ],\n \"stream\": [\n \"./node_modules/stream-browserify\"\n ]\n }\n ```\n3. Declare this in the global context of your application (ex: in polyfills for angular)\n ```js\n (window as any).global = window;\n ```\n\n### Webpack\n\nThis is the \"old\" way of using this package on webpages. This will build a minified js bundle that can be pulled in using a script tag on a website.\n\nBuild a bundle using webpack:\n\n- `npm install`\n- `npm build`\n- `npm pack`\n\nThe bundle can be found in `dist/`. Altough usage should be largely consistent, smaller differences will exist. Documentation is still TODO.\n\n## Use with LLMs & AI\n\nThis SDK includes a bundled `llms.txt` file in the root of the repository. If you're developing with LLMs, use the included `llms.txt` with your LLM - it will significantly improve the LLMs understanding of how to correctly use this SDK.\n\nThis file contains AI optimised structure of all the functions in this package, and their parameters for easier use with any learning models or artificial intelligence.\n\n---\n\n\n\n### Contributions & Thanks\n\nHave my projects helped you? Share the love, there are many ways you can show your thanks:\n\n- Star & share my projects.\n- Are my projects useful? Sponsor me on Github and support my effort to maintain & improve them: https://github.com/sponsors/tiagosiebler\n- Have an interesting project? Get in touch & invite me to it.\n- Or buy me all the coffee:\n - ETH(ERC20): `0xA3Bda8BecaB4DCdA539Dc16F9C54a592553Be06C` \n- Sign up with my referral links:\n - OKX (receive a 20% fee discount!): https://www.okx.com/join/42013004\n - Binance (receive a 20% fee discount!): https://accounts.binance.com/register?ref=OKFFGIJJ\n - HyperLiquid (receive a 4% fee discount!): https://app.hyperliquid.xyz/join/SIEBLY\n - Gate: https://www.gate.io/signup/NODESDKS?ref_type=103\n\n\n\n\n## Contributions & Pull Requests\n\nContributions are encouraged, I will review any incoming pull requests. See the issues tab for todo items.\n\n## Used By\n\nThe following represents some of the known public projects that use this SDK on GitHub:\n\n[](https://github.com/sieblyio/okx-api/network/dependents)\n\n\n\n## Star History\n\n[](https://star-history.com/#sieblyio/bybit-api&sieblyio/okx-api&sieblyio/binance&sieblyio/bitget-api&sieblyio/bitmart-api&sieblyio/gateio-api&sieblyio/kucoin-api&sieblyio/coinbase-api&sieblyio/orderbooks&sieblyio/accountstate&sieblyio/awesome-crypto-examples&Date)\n\n\n","readmeFilename":"README.md"}
![\"SDK](\"https://github.com/sieblyio/okx-api/blob/master/docs/images/logoDarkMode2.svg?raw=true#gh-dark-mode-only\")
\n