本手册面向所有正在对接 OKX 开放接口 的开发者，无论你是交易机器人作者、量化策略师还是 Web3 产品经理，都能在这里找到即拿即用的答案。
1. API Key 管理
1.1 Passphrase 是什么？
Passphrase 是在申请 API 密钥 时额外填写的二次密码。
- 它不会被加密保存，服务器也无法找回。
- 一旦忘记，只能重新生成一条新的 API Key，旧 Key 会立即失效。
1.2 如何创建“模拟盘”API Key？
OKX 为开发者提供零成本的 模拟盘（Demo Trading）。创建步骤如下：
- 登录后点击顶栏「交易」 → 「模拟盘」
- 右上角进入「个人中心」 → 「创建模拟盘 API Key」
- 一键复制 Key，立刻开始 零风险回测。
1.3 API Key 会过期吗？
取决于 权限与 IP 限制：
- 未绑定 IP 但拥有 下单或提币权限 的 Key：14 天无任何调用即自动删除。
- Key 至少调用过一次「私有接口」（查余额、下单、查账单等）即可重置 14 天倒计时。
- 仅带 读取权限 且已绑定 IP 的 Key 永久有效。
2. 下单与合约交易
2.1 合约下单单位是 USDT 还是张数？
OKX 合约接口只认「张数」（Contract 张）。如果你想把 USDT 换算成张数，可在 /api/v5/public/instruments 接口读取 ctVal 与 minSz，再自行计算。
示例：
合约面值(ctVal): 0.0001 BTC/张
最小下单(minSz): 1 张
USDT 数量 ÷ 合约面值 ÷ 仓位杠杆 = 张数2.2 如何同时挂止盈/止损？
在下单接口里传入 attachAlgoOrds 数组参数即可「主单+止盈止损」捆绑执行。
若想让止盈/止损独立成一个 策略单，请改用 /api/v5/trade/order-algo。
2.3 为什么收到 51000 posSide error？
- 单向持仓模式（默认）：
posSide字段可缺省或填net。 - 双向持仓模式：必须带
posSide，且只能填long或short。
👉 查看 30 秒代码示例，避免再次触发 posSide 报错。
3. 公共市场数据
3.1 24 小时涨跌怎么算？
接口不会直接给“涨幅 %”，但你可以用以下公式：
涨跌幅 = (last - open24h) / open24h * 100%数据字段可在市场接口 /api/v5/market/ticker 找到 last 与 open24h。
3.2 如何拿到合约面值、最小变动价？
调用 /api/v5/public/instruments?instType=SWAP 即可一次兜底：
ctVal：每张合约对应的标的数量tickSz：最小价格跳动单位minSz：最小下单张数
4. instId 格式大全
instId 是调用所有交易接口的“币种+市场”入口。请务必大写、无空格。
- 现货杠杆：
BTC-USDT - 永续 U 本位：
BTC-USDT-SWAP - 永续币本位：
BTC-USD-SWAP - 季度交割：
BTC-USDT-240627（年周或年月格式） - 期权：行权价+方向，
BTC-USD-240627-50000-C
5. 常见错误码速查
| 错误码 | 错误信息 | 解决要点 |
|---|---|---|
| 50102 | Timestamp expired | 本地时间未同步；请拉服务器时间 /api/v5/public/time 并与 UTC0 对齐，误差<30 s |
| 50101 | APIKey mismatch | Demo Key 调实盘或反之；注意 Header 参数 x-simulated-trading 0/1 开关 |
| 51010 | Unsupported under account mode | 账户模式只开了「现货」，需要先在网页或 APP 开启「杠杆/交割/永续」，再调用合约接口 |
| 51121 | Not multiple of lot size | 合约张数必须是 minSz 的整数倍；可再读一次 /instruments 校验 |
| 58207 | Address not whitelisted | API 提币必须先在「资金—提币地址」添加地址，并勾选“免验证”方可调用 |
| 50004 | Endpoint timeout | 0 点、8 点、16 点资金费结算高峰可用重试；成功与否需额外查订单状态 |
6. FAQ：开发者最关心的 5 个问题
Q1：我能在 USDT 现货账户直接用合约下单接口吗？
A：不可以。合约与现货账户独立分离，需确保对应账户已开启杠杆或合约模式。
Q2：如何确保请求的签名不会被重放？
A：每次请求都需在 Header 加入 OK-ACCESS-TIMESTAMP，误差不超过 30 秒，并配合 OK-ACCESS-SIGN 生成 32 位 HMAC-SHA256。
Q3：模拟盘跟主网的数据延迟大约多久？
A：K 线及深度数据完全一致；撮合延迟平均 <150 ms，可放心做策略回测。
Q4：为什么我在 04:00 (UTC+8) 频繁超时？
A：此时段为系统清算窗口，资金费、自动减仓集中处理。可改用 WebSocket 私有频道订阅订单回报，降低轮询压力。
Q5：下单接口一次最多支持多少条挂单？
A：单账号单交易对无官方上限，但为保持性能，建议每次批量≤20 条，超出请分页或分时调用。
7. 最后的小贴士
- 想第一时间获知系统升级或频率调整，请订阅官方 WebSocket 通知频道。
- 调试接口可下载 Postman 集合，避免手写签名出错。
祝各位开发者高效集成，早日跑出稳健 Alpha！