随着 OKX 全新统一账户交易系统的推出，其 API v5 版本也带来了多项重要升级与功能增强。本文将全面介绍 API v5 的主要变化，帮助交易者快速掌握新版本的使用方法，包括账户配置、杠杆设置、订单管理和数据订阅等关键操作。
API v5 的主要变化
统一的产品接口
与 API v3 不同，API v5 对所有产品类型提供了统一的接口。例如，下单操作只需调用同一个端点，并通过请求体指定产品类型：
POST /api/v5/trade/order同一接口适用于所有产品类型，无需再为不同产品单独建模，大幅简化了开发流程。
更简洁的命名规范
API v5 采用驼峰命名法并使用缩写，减少了字段名称的长度，有助于节省带宽和内存。例如：
- 货币字段从
currency简化为ccy - 产品ID从
instrument_id简化为instId - 未实现盈亏从
unrealized_pnl简化为upl
标准化的 WebSocket 压缩
API v5 支持标准的 WebSocket 扩展“Per-Message Deflate”，无需再手动解压消息。启用压缩功能时，需确保客户端请求头包含 permessage-deflate。
公私分离的 WebSocket 连接
WebSocket 通道分为公共频道（如行情、K线）和私有频道（如持仓、账户），使用不同的连接地址。公共频道无需登录即可订阅，私有频道则需先进行认证。
支持通过 WebSocket 下单
除了 REST API，现在还可通过 WebSocket 进行下单、改单和撤单操作，降低了通信开销，提升了交易效率。
认证机制
REST 认证方式与 v3 保持一致（在请求头中签名），WebSocket 认证也类似，但格式改为键值对形式：
{
"op": "login",
"args": [{
"apiKey": "您的API密钥",
"passphrase": "密码",
"timestamp": "时间戳",
"sign": "签名"
}]
}子账户API密钥管理
主账户可通过 API v5 直接管理子账户的API密钥，支持创建、查询、修改和删除操作。为安全起见，强烈建议为API密钥绑定特定IP地址。
账户与子账户配置
创建子账户及其API密钥后，可通过 API 进行交易前的各项配置。
账户配置查询
通过以下接口可获取账户的当前配置：
GET /api/v5/account/config返回信息包括：账户模式、持仓模式、自动借币设置和期权希腊值类型。
账户模式
OKX 统一账户支持三种模式：简单模式、单币种保证金模式和跨币种保证金模式。注意，模式切换需通过网页端完成，API 暂不支持此操作。
持仓模式
统一账户引入了净持仓模式，与原有的多空持仓模式并存：
- 净持仓：只能持有单向头寸，系统根据指定方向自动开平仓
- 多空持仓：可同时持有双向头寸
切换持仓模式需通过以下接口，且要求所有现有持仓均已平仓：
POST /api/v5/account/set-position-mode自动借币
自动借币功能仅适用于跨币种保证金模式，且只能通过网页端进行设置。
期权希腊值类型
与 v3 类似，可通过以下接口设置期权希腊值类型：
POST /api/v5/account/set-greeks保证金模式
在统一账户系统中，同一产品可同时使用全仓（跨币种或单币种）和逐仓保证金模式。因此，不再提供按标的物设置保证金模式的API，改为在下单时指定保证金模式。
杠杆管理
获取杠杆信息
通过以下接口可查询当前的杠杆设置：
GET /api/v5/account/leverage-info目前没有全局杠杆设置，杠杆可在不同范围内进行配置。
设置杠杆
获取杠杆信息后，可通过以下接口进行设置：
POST /api/v5/account/set-leverage利用这两个API，可以编写程序预先设置各产品的杠杆率。
例如，在跨币种保证金模式和净持仓模式下，希望将多个产品的杠杆统一设置为3.0：
- 对于现货/保证金产品，按币种设置杠杆
- 对于永续和合约产品，按产品或标的物设置杠杆
通过6次API调用即可完成8个产品的杠杆设置，具体参数配置请参考官方文档。
API v5 交易实战
交易模式
在下单时需要指定交易模式（tdMode），根据账户模式和产品类型选择正确的值。
例如，在跨币种保证金模式下交易 BTC-USDT-SWAP，tdMode 应设置为 cross。
为提高订单识别度，建议设置客户端订单ID（clOrdId），格式为字母开头的32位以内字母数字组合。
订阅订单频道
下单前应先通过 WebSocket 订阅订单频道，以便实时监控订单状态变化。API v5 提供多种订阅粒度：
- 按产品类型订阅
- 按产品类型+标的物订阅（仅衍生品）
- 按产品类型+产品ID订阅
也可使用 ANY 作为产品类型，一次性订阅所有产品类型的订单更新。
订单频道不提供订阅前的订单快照，只推送状态变更消息。如需获取所有未成交订单，可调用：
GET /api/v5/trade/orders-pending下单操作
API v5 支持通过 REST 或 WebSocket 下单。
REST 方式：
POST /api/v5/trade/order请求体包含产品ID、交易模式、方向、类型、价格和数量等参数。成功响应会返回交易所分配的订单ID（ordId），但这仅表示请求已被接收，不代表订单已生效。
WebSocket 方式：
理论上比 REST 更高效，开销更小。由于是异步操作，需要提供消息ID（id）来匹配响应。登录私有 WebSocket 后，发送操作类型为 order 的消息即可。
无论哪种方式，都需通过订单频道确认订单最终状态。
查询订单状态
下单后，可通过订单频道接收状态更新。订单可能经历以下状态变化：
- live：订单已生效，等待成交
- filled：订单已完全成交
- canceled：订单已撤销
成交回报中会包含成交ID（tradeId），可用于与持仓记录进行核对。
改单与撤单
API v5 支持对所有产品类型的订单进行改单操作，可修改价格和/或数量。如改单失败，可选择是否自动撤销原订单。
改单和撤单都支持 REST 和 WebSocket 两种方式，操作后需等待确认消息。已完全成交或已撤销的订单无法再进行修改。
批量操作
支持批量下单、改单和撤单，最多同时处理20个订单。统一接口的优势在于可混合处理不同类型产品的订单。
批量操作不是原子性的，允许部分成功。收到响应后，需检查每个订单的单独状态码和信息字段。
账户与持仓信息
统一账户
在统一账户系统下，所有产品类型共享一个账户，不再区分现货、保证金、合约、永续或期权账户。
WebSocket 订阅
推荐通过 WebSocket 订阅账户频道获取实时账户更新。订阅时可指定币种，只关注特定货币的余额变化。
账户频道会推送初始快照（仅包含非零余额的币种）和后续更新。更新分为事件驱动和定时推送两种方式。
REST 查询
也可通过 REST API 查询账户余额：
GET /api/v5/account/balance可指定单个或多个币种查询。与 WebSocket 不同，REST API 会返回所有曾持有过的币种余额，即使当前余额为零。
最大可交易量
在跨币种保证金模式下启用自动借币后，可交易超过可用现金余额的数量。通过以下接口可查询产品的最大可买卖数量：
GET /api/v5/account/max-avail-size返回结果分别以报价货币（买）和基础货币（卖）表示最大可交易量，与网页端显示一致。
持仓信息
API v5 的持仓接口也实现了统一，推荐使用 WebSocket 订阅获取实时数据。
订阅粒度与订单频道类似，可按产品类型、产品类型+标的物或产品类型+产品ID进行订阅。持仓频道会推送非零持仓的初始快照和后续更新。
每个持仓都包含唯一的持仓ID（posId），由保证金模式、持仓方向、产品ID和币种生成，可作为 REST 查询的参数。
成交与持仓核对
通过订单频道中的成交ID（tradeId），可以将成交记录与持仓变动进行关联核对。但需注意以下情况：
- 不是每个订单更新都能匹配到持仓更新，多个仓位变动可能被聚合推送
- 强平或自动减仓不会产生订单更新
- 由强平或自动减仓引起的持仓更新不会更新成交ID
因此，在核对时除了比较成交ID，还应考虑持仓更新时间（uTime）等因素。
常见问题
API v5 与 v3 的主要区别是什么？
API v5 采用了统一接口设计，所有产品类型使用相同的端点和数据模型；改进了命名规范，使用更简洁的字段名；增强了 WebSocket 功能，支持压缩和公私频道分离；增加了子账户API密钥管理功能。
如何选择正确的交易模式？
交易模式（tdMode）取决于账户模式和产品类型。简单模式下只能使用"cash"模式；单币种保证金模式下可使用"cash"或"isolated"；跨币种保证金模式下可使用"cross"或"isolated"。具体选择请参考官方文档的交易模式表格。
WebSocket 订阅有哪些注意事项？
公共频道无需认证即可订阅，私有频道需先登录；订单频道不提供初始快照，只推送状态变更；账户和持仓频道会推送非零余额/持仓的初始快照；支持多种订阅粒度，可按需选择。
批量操作失败如何处理？
批量操作不是原子性的，可能部分成功部分失败。响应中会包含每个操作的独立状态码和信息，需要根据这些信息分别处理失败的操作。
如何确保API调用的安全性？
为API密钥绑定IP地址；使用加密通信；妥善保管API密钥和密码；定期更换密钥；遵循最小权限原则，只授予必要的操作权限。
成交与持仓核对有哪些常见问题？
多个仓位变动可能被聚合推送，只显示最后的成交ID；强平和自动减仓不会产生订单更新；这些情况下需要结合持仓更新时间等额外信息进行核对。
本文内容基于当前API版本，随着OKX统一账户交易系统的持续升级，具体细节可能发生变化。请始终参考官方API v5文档获取最新信息。