对于数字货币交易平台的开发者而言，及时了解 API 的变更至关重要。一份清晰的更新日志不仅能帮助开发者快速适配新功能，还能避免因接口变动导致的系统异常。本文将系统梳理近期主要的 API 更新，并提供关键功能的开发指南。
核心功能更新概览
USDⓈ-M 永续合约
近期，USDⓈ-M 永续合约的 REST API 迎来了多项重要更新。
- 历史持仓查询限制调整：自 2024 年 10 月 30 日起，
GET /fapi/v1/userTrades端点将仅支持查询最近 6 个月内的交易历史。开发者需要调整数据归档策略，确保能访问更早期的历史数据。 - 新增账户与交易信息端点：引入了多个高性能新端点，例如
GET /fapi/v3/account和GET /fapi/v3/positionRisk。这些端点优化了响应结构，仅返回用户持有仓位或存在挂单的标的，并移除了配置相关字段，性能显著提升。 - WebSocket API 服务升级：WebSocket API 现已正式可用，支持通过 WebSocket 连接进行下单、撤单等操作。请注意，交易接口与行情数据接口是独立的服务，需要建立两个不同的 WebSocket 连接。
COIN-M 币本位合约
币本位合约的更新主要集中在功能增强和查询优化上。
- 自成交防护（STP）机制：系统新增了自成交防护功能，有效防止同一账户或相同交易组 ID 下的账户之间的订单相互成交。下单时可设置
selfTradePreventionMode参数来指定处理模式。 - 价格匹配（Price Match）功能：支持限价单/止损单/止盈单在不输入价格的情况下下单。系统将根据订单簿情况，按照设定的价格匹配模式（如对手方最优价格、同侧队列价格等）实时确定订单价格，大大提升了下单的灵活性和效率。
- 历史数据下载端点：新增了异步订单和交易历史下载端点（如
GET /dapi/v1/trade/asyn），方便用户获取大规模的历史数据。
组合保证金模式
组合保证金（Portfolio Margin）及相关专业版功能持续扩展，提供了更灵活的风险管理工具。
- 新增抵押品管理端点：支持将 Earn 资产（如 LDUSDT）转为抵押品，相关端点为
POST /sapi/v1/portfolio/earn-asset-transfer。 - 借贷与还款记录查询：新增端点用于查询用户负余额自动兑换记录（
GET /papi/v1/portfolio/negative-balance-exchange-record）和 PM 贷款还款记录（GET /sapi/v1/portfolio/pmloan-history）。 - BFUSD 铸造与赎回：支持通过
POST /sapi/v1/portfolio/mint和POST /sapi/v1/portfolio/redeem端点进行 BFUSD 的铸造与赎回操作。
开发实践与注意事项
在实际开发过程中，除了关注新功能，还需留意一些底层规范的变更，这些变更可能直接影响应用的稳定性和性能。
1. 请求格式规范化
务必使用标准的 HTTP 请求格式。避免使用非标准的字符转义（如用 \x22 代替双引号）、嵌套 JSON 格式或错误的数据类型。所有请求参数都应进行正确的 URL 编码。
2. 查询时间范围限制
多个历史数据查询端点的可查询时间范围已被调整。例如，用户交易记录（userTrades）的查询窗口缩短，超过期限的数据需通过异步下载接口获取。开发者需检查现有代码的逻辑，确保不会因查询超期而报错。
3. WebSocket 连接维护
WebSocket 服务完成了升级，连接保活机制发生变化。服务器会每 3 分钟发送一次 ping 帧，客户端必须在 10 分钟内回复包含相同载荷数据的 pong 帧，否则连接会被断开。👉 查看实时连接状态监测工具
常见问题解答
Q1: 自成交防护（STP）有哪些模式？如何选择？
A1: STP 提供四种模式：NONE（无防护）、EXPIRE_TAKER（STP 触发时使吃单订单过期）、EXPIRE_MAKER（使挂单订单过期）以及 EXPIRE_BOTH（使双方订单均过期）。选择取决于您的交易策略，通常为了避免不必要的手续费损失，可选择 EXPIRE_TAKER。
Q2: 如何高效获取长时间范围内的历史订单或交易数据？
A2: 官方推荐使用异步下载接口。首先调用 GET /fapi/v1/order/asyn 等接口获取一个下载 ID，然后使用该 ID 调用 GET /fapi/v1/order/asyn/id 获取包含历史数据的下载链接。这种方式专为批量获取数据设计，避免了对历史查询端点的频繁调用。
Q3: WebSocket API 和 REST API 有何异同？
A3: 它们在功能上是等效的，提供相同的特性、接受相同的参数、返回相同的状态和错误码，并遵守相同的频率限制规则。主要区别在于通信协议。WebSocket 适合需要低延迟实时交互的场景（如高频下单），而 REST API 更适用于常规的请求响应式操作。
Q4: 价格匹配（Price Match）功能中的 OPPONENT 和 QUEUE 模式有什么区别？
A4: OPPONENT 系列模式是针对订单簿对手方的价格。例如，买入订单设置为 OPPONENT，则订单价格将为当前最优卖一价。而 QUEUE 系列模式是针对订单簿同侧的价格。例如，买入订单设置为 QUEUE_5，则订单价格将为订单簿买一侧的第 5 档价格。
Q5: 组合保证金模式下，新增的抵押品功能有什么好处？
A5: 允许将 Earn 等生息资产转为抵押品，可以在一定程度上提高资金利用效率。用户无需赎回或卖出这些资产，即可将其价值计入抵押品总额，从而可能开立更大的头寸或满足保证金要求，同时这些资产可能还在产生收益。