关键词：交割 USDT 保证金合约、OpenAPI V3、API 升级、合约账户信息、Websocket API、币本位、USDT 本位、接口变更
1. 升级背景与时间
自即日起，交易所将通过 V3 OpenAPI 提供完整的 交割 USDT 保证金合约 模拟盘和实盘交易功能。为了给开发者留出充足的接口适配空间，本次变更将遵循“模拟→实盘”分步上线的原则：
- 上线时间：10 月 31 日 16:00（HKT）
- 文档同步：API 文档当日即更新，官网可见
- 模拟&实盘开放时间：后续另行通知，请关注官方公告
温馨提示：
- 本次改造仅对 使用 API 交易的开发者 生效；网页/UI 用户不受影响。
- V1 OpenAPI 本身 不支持 任何形式的 USDT 保证金合约，务必尽早迁移至 V3。
2. 核心改动速览
2.1 参数命名统一：从 currency 改为 underlying
原有 URL 结构无法区分 币本位（Reverse）与 USDT 本位（Linear）。改版后统一使用 underlying 表示合约标的。
| 类别 | 旧传参 | 新传参示例 |
|---|---|---|
| 币本位保证金 | BTC | BTC-USD |
| USDT 保证金 | 不存在 | BTC-USDT |
→ 为了保持向后兼容，/BTC 等旧写法仍会被映射为 /BTC-USD，但强烈建议按照新规范改写，以规避未来歧义。
示例对比
# 旧
GET /api/futures/v3/accounts/BTC
# 币本位可用，但未区分
# 新
GET /api/futures/v3/accounts/BTC-USD # 币本位
GET /api/futures/v3/accounts/BTC-USDT # USDT 保证金👉 立即查阅完整参数示例与错误码对照，避免踩坑。
2.2 REST API 受影响接口一览
| 编号 | 接口 | 路径 | 改动要点 |
|---|---|---|---|
| a | 单币种合约账户信息 | /api/futures/v3/accounts/<underlying> | underlying 必传 |
| b | 账单流水查询 | 同上 | 同上 |
| c | 调整合约杠杆（全仓） | POST /api/futures/v3/accounts/<underlying>/leverage | underlying 必传 |
| d | 查询杠杆倍数 | GET /api/futures/v3/accounts/<underlying>/leverage | 同上 |
| e | 获取合约信息 | GET /api/futures/v3/instruments | 返回字段新增 is_linear, settle_currency |
| f | 设置账户模式 | POST /api/futures/v3/accounts/margin_mode | 本接口 不向下兼容，务必传递 <underlying> |
| g | 获取全币种资产 | GET /api/futures/v3/accounts | 额外字段可在 data 内识别合约本位类型 |
新增返回字段一览
is_linear:true则为 USDT 本位合约，false为币本位settle_currency: 结算货币，USDT或各币本位币种
2.3 WebSocket API 调整
开发者若使用私有频道 futures/account 监听余额变动，订阅语法需新增 -USDT 后缀：
| 场景 | 旧订阅格式 | 新订阅格式 |
|---|---|---|
| 币本位 | {"op":"subscribe","args":["futures/account:BTC"]} | 同上 |
| USDT 本位 | —— | {"op":"subscribe","args":["futures/account:BTC-USDT"]} |
- 公共频道
futures/instruments同步增加字段，依旧在一条推送内返回，无需切换频道。 - 如不交易 USDT 保证金，程序零改动能继续运行。
3. 换用 V3 的 3 大理由
- 稳定性提升：相较 V1，V3 采用新网关，通过率和延迟分别优化 20% 与 25%。
- 功能迭代快：V3 可优先享用交割合约、次季合约、组合保证金等高级功能。
- 后续维护风险：官方将在无预警情况下 关闭 V1 REST 服务；越早迁移越安全。
👉 不想迁移踩坑？提前测一测 API 兼容性清单。
4. 快速迁移 4 步曲
- 模拟环境干跑：先在
/api/futures/v3/accounts/<underlying>-USDT空 JTI（JSON Test Input）测试，确认签名、URL 拼接无误。 - 批量更新 URL：对于约 60% 的路径需改成
-USD或-USDT，推荐用脚本全局替换。 - 检查订阅句柄：WebSocket 需区分
-USDT，订阅失败将收到4300 Invalid Argument错误码，记入日志即可。 - 监控附加字段：新字段对解析不破坏现有结构，可直接忽略；如需使用，升级解析逻辑。
5. FAQ：一次解决 7 个高频问题
Q1：只用网页下单，会被影响吗？
A：完全不会，本次只调整 API 层，不影响任何 UI 用户。
Q2：币本位参数必须全加上 -USD 吗？
A：不强制，旧写法如 BTC 仍将映射为 BTC-USD；但未来若新增其他基差合约，-USD 会增强可读性。
Q3：margin_mode 接口不兼容是什么意思？
A：之前调用 /margin_mode 可以不写 <underlying>；改版后必须写，否则返回 400 Bad Request。
Q4：V1 已弃用，有限迁移窗口吗？
A：官方提供至少 3 个月 预警期，之后滚动关闭。请把 V3 设为生产主网关。
Q5：如何分辨当前已经订阅的频道是线性还是反向？
A：查看返回包内的 settle_currency：USDT → USDT 本位，其余为币本位。
Q6：合约费率是否有额外优惠？
A：API 准入无差异。官方手续费档位与账号 VIP 等级绑定；详见官网费率规则。
Q7：SDK、权限错误如何求助？
A：文档角落地图标注「技术支持 Bot」，可在线提交 JSON 日志，工作日 2h 响应。
6. 对接小贴士
- 建议采用 版本化分支：主分支沿用旧 API，新建
v3-linear-dev分支逐一回测。 - 开发完成后，使用 流量复制（shadow traffic）并行跑 24h，无异常再正式切换。
- 若使用
curl调试，加--verbose能迅速定位 404/400 细节所在。
7. 结语
V3 OpenAPI 对 交割 USDT 保证金合约 的全面适配，意味着开发者将拥有更广阔的策略空间：跨期套利、网格对冲、永续与交割组合尽享低时延、高并发。请抓住升级窗口，尽早完成接口迁移，以免后续业务中断。
祝开发顺利，交易长虹！