V3 OpenAPI 升级：全面支持交割 USDT 保证金合约交易

·

欧易 OKX 平台近期宣布上线交割 USDT 保证金合约，并对现有 V3 OpenAPI 接口进行了相应升级，以支持模拟盘及实盘交易。本次升级旨在提升交易效率与系统稳定性，为开发者及专业交易者提供更完善的工具支持。

升级概览与时间安排

本次 API 升级预计于 2019 年 10 月 31 日 16:00 (HKT) 正式上线，API 文档将同步更新。模拟盘及实盘交易的具体开放时间将在后续公告中公布。

请注意，本次升级仅涉及 V3 OpenAPI 用户，V1 OpenAPI 不支持 USDT 保证金合约交易。

核心改造内容

接口参数调整

改造前，API 接口无法通过请求参数区分“币本位保证金合约”和“USDT 保证金合约”。具体调整如下：

示例调用：

系统仍兼容原有请求格式，例如 GET /api/futures/v3/accounts/BTC 将自动等价于 GET /api/futures/v3/accounts/BTC-USD。

注意：RestAPI 中的“设置账户模式接口”（POST /api/futures/v3/accounts/margin_mode）不提供兼容处理，使用此接口需传入相应的 underlying 参数。

受影响接口清单

RestAPI 接口

以下接口在此次升级中进行了调整：

  1. 单个币种合约账户信息：GET /api/futures/v3/accounts/
  2. 账单流水查询：GET /api/futures/v3/accounts/
  3. 设定合约杠杆倍数（全仓）：POST /api/futures/v3/accounts/
  4. 获取合约币种杠杆倍数：GET /api/futures/v3/accounts/
  5. 公共获取合约信息：GET /api/futures/v3/instruments（返回值增加必要字段）
  6. 设置合约账户模式：POST /api/futures/v3/accounts/margin_mode（不兼容旧格式）
  7. 获取所有币种合约账户信息：GET /api/futures/v3/accounts（返回值增加必要字段）

WebsocketAPI 接口

以下频道同样进行了更新：

  1. 公共-全量合约信息频道：futures/instruments（返回值增加必要字段）
  2. 个人-订阅账户信息频道：futures/account

订阅示例：

兼容性说明与影响评估

如果您不交易 USDT 保证金合约，现有程序将不受影响。但请注意，部分接口返回值中会新增字段，建议提前检查程序兼容性。

V3 API 在稳定性、效率和功能全面性上均优于 V1 版本，且 V1 Restful API 将于未来停止服务。我们强烈建议用户优先使用 V3 API，以获得更优质的交易体验。

👉 获取详细的 V3 API 接口文档与升级指南

常见问题

1. 本次升级会影响我正在运行的交易程序吗？

如果您目前仅使用币本位保证金合约且不升级程序，原有交易可正常运行。但若计划使用 USDT 保证金合约或希望获取完整账户信息，则需根据新文档调整接口调用方式。

2. 升级后，如何区分两种保证金合约的接口调用？

关键在于 underlying 参数的值：使用 XXXX-USDT 表示 USDT 保证金合约，使用 XXXX-USD 表示币本位保证金合约。系统对旧参数格式保留有限兼容性。

3. 为什么设置账户模式接口不兼容旧格式？

该接口用于关键账户设置，要求明确指定合约类型以确保操作准确性。因此强制要求使用新的 underlying 参数格式，避免误操作风险。

4. Websocket 订阅需要做哪些改动？

订阅账户频道时，需在频道名后明确指定合约类型，例如 futures/account:BTC-USDT。未指定或格式错误的订阅请求可能无法获取正确数据。

5. V1 API 何时会停止服务？

平台未来将停止 V1 API 服务，具体时间待后续公告。建议用户尽早迁移至功能更全、性能更稳定的 V3 API，以免影响后续交易。

6. 遇到技术问题如何寻求帮助？

开发过程中若遇到任何问题，或对 API 功能有需求建议，可通过官方渠道联系技术团队获取专业支持。

欧易 OKX 将持续优化产品功能与服务体验，致力于为用户提供安全、高效、专业的数字资产交易环境。