OKX API 最新更新完全指南：子账户、提现参数与交易体验升级

关键词：OKX API、子账户管理、提现合规、余额查询、交易参数升级、API 错误码、手续费计算

1. 更新速览：开发者必须拿到的新能力

过去 6 个月，OKX API 陆续上线了子账户仅限开发者的核心接口、对土耳其实体用户的提现合规增强，并在余额字段、手续费模型、订单状态枚举等领域全面迭代。

👉 想第一时间体验这些功能？官方沙盒通道已经同步更新，点击即刻试调

2. 子账户管理全新四重奏

V5 版本为子账户准备了 4 条 REST 专属端点：

Create sub-account – 直接在代码里创建子账户，无需登录网页。
Create an API Key for a sub-account – 一键生成阅读/交易/提现权限。
Query the API Key of a sub-account – 快速检查子账户的 Key 权限列表。
Delete the API Key of sub-accounts – 回收或轮换不再使用的 API Key。

这些接口让 Broker、资管团队与高频套利程序都能程序化地横向扩容，极大降低手动维护风险。

开发者实战示例

# 创建子账户
POST /api/v5/users/subaccount
{
  "pwd":"main_pwd",
  "subAcct":"AlgoDesk_01",
  "note":"专用于做市"
}

返回 subAcct、label、uid 等信息即刻可用，5 秒内同步到撮合引擎。

3. 土耳其实体用户提现合规升级

由于本地监管要求，该批次用户调用withdrawal接口时，需新增 rcvrInfo 结构体。

3.1 提现至交易所钱包

必填字段：

rcvrFirstName / rcvrLastName – 当收款主体为企业时，FirstName 填公司名、LastName 填 "N/A"。
rcvrCountry、rcvrCountrySubDivision、rcvrTownName、rcvrStreetName – 精确到注册办事处街道级地址。

为方便获取匹配到的交易所列表，可调用 Get exchange list (public) 端点。示例：

"rcvrInfo": {
  "rcvrFirstName": "ABC Exchange Ltd.",
  "rcvrLastName": "N/A",
  "rcvrCountry": "SG",
  "rcvrCountrySubDivision": "SG",
  "rcvrTownName": "Singapore",
  "rcvrStreetName": "12 Marina Boulevard"
}

3.2 提现至私人钱包

同样需传递 rcvrInfo，但逻辑更轻：FirstName 填写实际姓名即可。

4. 新增错误码速查表

错误码	场景场景含义
59515	未进入托管白名单，需先完成认证
59516	需先创建 Copper 托管资金账户
59517	需先创建 Komainu 托管资金账户
59518	API 禁止直接创建子账户，请使用网页或 App
59519	功能被冻结，返回 `freezereason` 详解原因

出现59518时无需惊慌，可用上文 Create sub-account 新接口；如遇 59515-59517，先建好托管账户再走 API。

5. 余额与风险度新字段：把杠杆和名义开值一次性看全

接口：

Get balance
Get sub-account trading balance
Account channel (WebSocket)

新增 4 个以 notionalUsdFor 前缀的字段，对应借贷名义值、永续 / 交割 / 期权仓位名义值，全部以 USD 计价，可直接用于风控引擎计算杠杆比率或组合 VaR。

示例 JSON:

{
  "notionalUsdForBorrow": "125000.00",
  "notionalUsdForSwap": "3000000.50",
  "notionalUsdForFutures": "150000.00",
  "notionalUsdForOption": "25000.00"
}

👉 在实盘里想直观看见这些数值？打开官方 API Explorer，填入 Access Key 后便可持续监听

6. 手续费计算模型：固定费率时代来临

6.1 Get currencies 响应升级

过去 minFee / maxFee / minFeeForCtAddr / maxFeeForCtAddr 已被标记为 deprecated。新字段仅保留：

fee：链上提币统一固定手续费
burningFeeRate：燃烧费率，例如 "0.05" 表示 5%，计算基准为 提币数量 × rate，与链上矿工费分开计扣。

6.2 子账户费率查询

新增 Get sub-account fee rates 端点，可批量获取每个子账户的现货、合约、期权手续费配置，便于动态调优利润模型。

7. Nitro Spread 交易更自由

支持市价单：ordType 枚举新增 market，直接挂单跳到盘口最优价。
新增取消状态：cancelSource = 15 时，订单因“价格超越限制”被自动撤单，开发者可无感兜底。

涉及端点：Place order / Get order details / Get active orders / 各 WebSocket 频道全部同步更新。

8. 轻量公告获取能力

公共接口 GET /Announcements 与 GET /Announcement types 无需鉴权即可调用，适合用来做推送与弹窗提示，保持零售用户、App、机器人的消息一致性。

9. 开发者 FAQ：高频疑问 5 连击

Q1：子账户数量有无上限？
A：软上限默认 20 个，需扩容请联系机构客服邮件申请。

Q2：土耳其用户能否免除 rcvrInfo？
A：不可以，除非账户实体迁移到不受该法规约束的司法辖区。

Q3：固定手续费会频繁调整吗？
A：链上矿工费波动大时，平台每日自动微调一次，请关注公告接口。

Q4：burningFeeRate 是额外扣吗？
A：对，先从提币数量扣燃烧费，再扣固定矿工费，两段分离可见。

Q5：Nitro Spread 的 market 市价单滑点保护阈值是多少？
A：当前为 500 bps，持仓超过 50000 USD 名义值时升级为 800 bps，后台自动计算。

10. 立即行动清单

在老项目中批量替换 Get currencies 字段，减少废弃字段。
为土耳其用户 withdrawal 请求补充 rcvrInfo，提前灰度。
利用 notionalUsdForxxx 聚合值，重写风险监控脚本。
将 Nitro Spread 的枚举值同步到 UI 订单类型列表。
订阅 Announcements WebSocket 公开频道，官方公告±1 秒推送。

事无巨细，一朝就绪，祝开发愉快！