使用 OKX-API：完整 Node.js / TypeScript 对接攻略

核心关键词：okx-api、Node.js、TypeScript、WebSocket、SDK、加密货币量化、REST API、算法交易

概览：为什么选择 okx-api

okx-api（版本 2.0.5，社区维护开源）在 Node.js 与 TypeScript 场景中提供了一站式、类型完备的 OKX 接口解决方案：

• 100 % 覆盖 v5 版 REST & WebSocket 端点
• 自动重连、鉴权、心跳保活的高性能 WebSocket 客户端
• 通过 100+ 用真实交易所做测试的端到端集成测试持续把关
• 内嵌浏览器兼容包，前端一键引用即可使用
• MIT 开源，社区迭代速度快，高于官方示例的颗粒度

👉 想 3 分钟完成从 npm install 到第一条下单指令？点此抢先体验完整 Demo！

快速开始

1. 创建 API Key

登录 OKX ➝ 账户安全 ➝ API 管理 ➝ 创建 API Key ➝ 选择「交易」「读取」权限，记下 apiKey、secret、passphrase。

2. 安装依赖

npm install okx-api

TypeScript 项目无需额外安装 @types/xxx，声明文件已在包内。

3. 三行代码验证连通性

import { RestClient } from 'okx-api';

const client = new RestClient({
  apiKey: 'your-key',
  apiSecret: 'your-secret',
  apiPass: 'your-passphrase',
});

(async () => {
  const balance = await client.getBalance();
  console.log(balance);
})();

REST 深度用法

统一响应处理

• 成功：直接返回 data 字段，避免多层解构。
• 失败：以异常形式抛出完整对象，便于分布式日志接入。

示例：获取标记价格后立刻挂单 BTC-USDT

const markPx = await client.getMarkPrice({ instId: 'BTC-USDT' });
const orderRes = await client.submitOrder({
  instId: 'BTC-USDT',
  ordType: 'limit',
  side: 'buy',
  px: `${markPx.data.markPx * 0.99}`, // 打 9.9 折
  sz: '0.01',
  tdMode: 'cash',
});

高性能 WebSocket 实时通道

WebSocket = 低延迟 算法交易 生命线。okx-api 做了 5 重自动化：心跳、掉线重连、断流重订阅、多账号鉴权、限流自适应。

订阅行情

import { WebsocketClient } from 'okx-api';

const ws = new WebsocketClient({});

ws.on('update', (topic, data) => {
  console.log('深度盘口：', data);
});

ws.subscribe({ channel: 'books', instId: 'BTC-USDT' });

订阅私有账户事件

const wsPrivate = new WebsocketClient({
  apiKey: 'your-key',
  apiSecret: 'your-secret',
  apiPass: 'your-passphrase',
});

wsPrivate.on('message', (m) => m.arg?.channel === 'account' && console.log('资金变动', m));
wsPrivate.subscribe({ channel: 'account' });

浏览器端调用（Webpack 方式）

适合 win32 原生项目的无浏览器内置加密环境：

1. 安装 polyfill：npm install crypto-browserify stream-browserify

2. webpack.prod.js 添加

   resolve: {
     fallback: { crypto: require.resolve('crypto-browserify'), stream: require.resolve('stream-browserify') }
   }

3. 打包：npm run build ➝ 生成的 dist/*.min.js 直接用 <script src="..."> 引入即可。

FAQ

Q1：okx-api 与官方 Node.js SDK 有何不同？
A：官方 SDK 面向 REST 为主，okx-api 在此基础上补充了 TypeScript 类型定义、WebSocket 高并发场景的重连缓存、第三方接口统一封装，无需补丁即可体验 v5 新功能。

Q2：是否会因为频繁心跳导致配额耗尽？
A：心跳和重连策略均可通过 pingInterval、reconnectTimeout 自定义；在高频场景下建议将心跳置于非交易时段以减少流量。

Q3：能否一次性订阅 100 个账户？
A：可以。创建 WebsocketClient 时传入 accounts 数组，然后在私人频道订阅上如 account 即可自动完成多重鉴权。

Q4：断网场景下交易异常怎么办？
A：在 算法交易 架构中建议加入本地状态机，收到 connectionStateChanged 事件时暂停策略逻辑，等待 update 或 connected 再恢复交易。

Q5：浏览器端如何全局注入 Buffer？
A：在入口文件顶部执行

import { Buffer } from 'buffer';
window.Buffer = window.Buffer || Buffer;

Q6：生产环境如何隐身 key？
A：可使用运行时环境变量 + .env 文件合并 vite-plugin-env-compatible，密钥不会写入源码仓库，符合 加密货币量化 保密规范。

最佳实践场景

进阶：自动化测试与 CI

okx-api 内部集成真实接口的 Jest 测试。开发者可 fork 后：

git clone [email protected]:tiagosiebler/okx-api.git
cp tests/private.env.example tests/private.env # 填自己的 key
npm test

测试覆盖率 ≈ 92%，持续集成推送到 GitHub Actions，保证每次发版不破坏 REST API 与 WebSocket 的兼容性。

贡献与致谢

觉得好用就给星，提 PR 永远优先合并。工作组通过以下方式持续智能迭代：

1. GitHub Issues 细分 label（enhancement、web、tests）。
2. Telegram 群 Node.js Algo Traders 实时答疑。
3. 赞助咖啡：ETH(ERC20) 0xA3Bda8BecaB4DCdA539Dc16F9C54a592553Be06C。

立即实战

👉 想用一套代码连接三大所？点击解锁通用交易积木！