更新日志
衍生品交易 API 的所有变更和更新记录。
2026-05-07
REST API — 账户 / 用户数据流
- 新增：
POST / PUT / DELETE /fapi/v1/listenKey（HMAC SHA256）。 申请、续期、撤销 64 字符 listenKey,用于私有 WebSocket 频道认证。 TTL 3600 秒,每用户一个活跃 key (POST 幂等)。详见 用户数据流。 - 新增：
GET / POST /fapi/v1/marginType（HMAC SHA256）。Binance 兼容 stub ——GET始终返回marginType=CROSSED,POST CROSSED幂等,POST ISOLATED返回-4046(fapi/HMAC 命名空间只跑全仓)。需要真正 的逐仓核算请使用 JWT 鉴权的POST /api/v1/account/margin-mode。详见 保证金模式。
REST API — 行情数据
- 变更：
GET /fapi/v1/exchangeInfo现在填充symbols[*].filters(此前为空)。返回的 filter:PRICE_FILTER、LOT_SIZE、MARKET_LOT_SIZE、MIN_NOTIONAL。详见 交易规则和交易对。 - 变更：
GET /api/v1/markets(非 fapi 列表接口)同步增加min_order_size_usd、lot_size、tick_size,客户端做下单 sizing 不必再逐 symbol 拉 detail。
REST API — 订单
- 变更：
POST /fapi/v1/order现在对reduceOnly=true订单豁免MIN_NOTIONAL过滤器。被资金费 / 手续费侵蚀到 < 10 USD 的仓位 可以通过 reduce-only 平掉 —— 之前根本下不了单。LOT_SIZE与MAX_NOTIONAL仍然适用。 - 变更：
-1013拒单消息按 Binance 标准格式开头加上Filter failure: <FILTER>.前缀(LOT_SIZE/MIN_NOTIONAL/MAX_NOTIONAL),客户端可据此 switch 失败的过滤器类型。
WebSocket — 认证
- 新增： WebSocket auth 接受 fapi listenKey:
{"type":"auth","listenKey":"<key>"}。该 lookup 顺带刷新底层 Redis key 的 TTL,长连 WebSocket 等同隐式 keepalive。详见 WebSocket 通用。
2026-04-28
REST API — 订单
- 新增：
PUT /fapi/v1/order（修改订单）。底层走撤单‑重新挂单 并重新冻结保证金，对调用方而言orderId保持不变。side字段可选 （未传时沿用原订单方向）。详见 修改订单。 - 新增： Symbol 分片路由（Plan A）—— 写路径请求会被透明转发到
持有该 symbol 分片的 pod，客户端无需任何改动；
clientOrderId仍 正常往返。 - 新增： 列表辅助路由
GET /orders、GET /orders/open、GET /positions/active，方便不走 Binance 风格路径的客户端。 - 变更：
POST /fapi/v1/order现在在请求进撮合引擎之前就 强制校验 lot size 与 symbol 的最小/最大名义额。子 lot 的数量会 向下对齐到 lot 网格（不会被拒），名义额越界返回-1013。 - 变更：
timeInForce接受GTX（post‑only）。GTX单若与 对手价交叉，返回-2010而非被静默成交为 taker。IOC/FOK/GTC语义在引擎层严格执行（此前IOC部分语义未生效）。 - 变更： 触发条件已被立即满足的 trigger 单（如
STOP当前价 已破stopPrice）直接以-2021拒绝，不再等下一 tick 才成交。 - 变更：
STOP_LIMIT与TAKE_PROFIT_LIMIT接受为STOP与TAKE_PROFIT的别名。 - 变更：
reduceOnly单在 admission 时按对侧持仓数量上限收口； 若该reduceOnly=true单本应开仓或反向，直接被拒。 - 变更： Trigger 单（
trigger_orders）在所有撤单路径——DELETE /fapi/v1/order、DELETE /fapi/v1/allOpenOrders、DELETE /fapi/v1/batchOrders——都会被识别并处理。父订单撤单 时其 TP/SL trigger 单会级联撤销。fapi 创建的订单在 cancel‑all 与 batch‑cancel 路径上正确释放冻结保证金。 - 变更：
POST /fapi/v1/order提交的 trigger 单现在能正确尊重stopPrice（先前在某些边界场景被错放进 resting 订单簿）。 - 修复：
newClientOrderId持久化；avg_price按订单存档，query-order/all-orders返回一致的均价，不再每次重新计算。 - 修复：
timeInForce持久化；openOrder正确返回终态；userTrades的startTime/endTime/fromId过滤参数生效。 补齐/fapi/v1与/api/v1/account/trades既有的 3 个 P0 数据 完整性 bug。 - 修复： Sub‑lot 成交漂移 —— 部分成交订单若剩余量低于一个 lot，
会被收口并切到
FILLED终态，不再永久卡在PARTIALLY_FILLED。 - 修复： 仓位"部分平仓 vs 反向开仓"的判定改用 token 单位（不再
用 USD），消除了一类 flip‑close 的 phantom‑credit 漂移。Flip 平仓
时未消耗的 collateral 会回写。手动平仓 / 强平 / ADL 路径补齐了
realized_pnl_events。
REST API — 账户与资金
- 新增：
GET /account/fee-info公开访问（无需登录）。 匿名调用返回完整的 VIP 费率表（以 VIP 0 为基线）；登录调用额外 返回当前等级、14d/30d 滚动量、待生效降级与综合折扣堆栈。 - 新增： Trader PnL 排行榜接口，底层用 Timescale 连续聚合 （CAGG），全量 排行也能亚秒级返回。
- 新增：
WITHDRAWALS_PAUSED运维 kill switch —— 事故对账期间 开启后，POST /withdraw/request返回503 SERVICE_UNAVAILABLEWITHDRAWALS_PAUSEDcode。撤单 / 确认 / 历史接口不受影响。
- 变更：
/account/trades与/account/orders支持 keyset 分页：query 加cursor不透明游标，响应回next_cursor。cursor模式下total: -1（不再计算总数）；旧的offset分页 仍兼容，但offset > 5000后变 O(N)。 - 变更：
POST /account/margin-mode接受mode作为margin_mode的别名（与 Binance 的marginType字段对齐，复用 同一份请求体）。 - 性能：
/account/trades改写为UNION ALL—— 高频账户上的 查询时间从 ~17.5 s 降到 ~7 ms（≈2,500×）。
REST API — 保证金 / 杠杆 / 持仓模式
- 变更：
POST /fapi/v1/leverage现在按(user, symbol)维度 持久化；后续未显式带 leverage 的下单会自动应用持久值。 - 变更：
POST /fapi/v1/positionSide/dual拒绝 hedge 模式 开关（dualSidePosition=true），返回-4059。仅支持 one‑way 模式。该字段同时接 受bool与string形式，方便客户端共享 请求结构。 - 新增：
GET /fapi/v2/positionRisk注册为 v1 路由的别名。 - 变更：
/unified/account快照现在把 resting（挂单） 占用的初始保证金计入，使 equity / 可用余额 /uniMMR与下单 admission 路径看到的一致。 - 变更：
/api/v1/orders的reduceOnly单同样适用 cap+reject 规则（与 fapi 一致）。
REST API — 行情
- 变更：
GET /fapi/v1/ticker/24hr去掉了相关子查询，symbol filter 下推。多 symbol 响应显著提速。 - 变更：
GET /fapi/v1/income改写为对手续费 / 资金费 / 已实现 PnL 三个来源的UNION ALL。
认证
- 变更： HMAC SHA‑256 签名校验同时接受 raw 与 URL‑encoded payload
两种形式。客户端发哪种（如
requestsvs 裸urllib3）不再影响 签名匹配。
REST API — 入参兼容
以下字段补齐 Binance 兼容的 bool 或 string 双形态接受（之前 对其中一种严格类型校验导致拒收）：
| 端点 | 字段 | 接受形式 |
|---|---|---|
POST /fapi/v1/order | reduceOnly | true / false / "true" / "false" |
POST /fapi/v1/order | dualSidePosition | 同上 |
POST /fapi/v1/leverage | leverage | int / "int"（数字字符串） |
WebSocket
- 新增： 私有频道
balances—— 由 PostgresLISTEN/NOTIFY驱动的余额推送（Decimal 字段以字符串发送以保留精度）。可替代 对GET /account/balances的轮询。详见 User Data Stream。 - 变更：
orderbook频道深度从 20 档扩到 30 档。 - 修复： 订阅路径不再被高频 broadcast 饿死 —— WS 处理器重写为 writer task + biased select + 有界 MPSC + snapshot 信号量；初次 订阅快照即使在 ~50 trade events/s 时也能及时返回。
2026-04-15
- 新增： 6 档 VIP 手续费表（VIP 0 – VIP 5），按 14 天滚动成交量 计算。详见 VIP 等级费率表。 升 级即时生效；降级缓冲到下一个 UTC 00:00。
- 新增：
GET /account/fee-info返回完整费率表、用户当前 / 实际 生效费率、14d/30d 滚动量、距离下一档差多少、当前 referral / 代币 staking 折扣堆栈。 - 新增： 私有 WebSocket 频道
vip_tier推送vip_tier_changed事件（upgrade_immediate/downgrade_scheduled/downgrade_applied）。 - 变更：
/fapi/v1/commissionRate现在返回 实际生效 费率 （base ×discount_multiplier），不再是 base 费率。 - 修复：
POST /orders/preview的est_slippage改为真实订单簿 扫描结果（先前硬编码为 0）；max_slippage在市价单到达撮合引擎 之前就生效，超限以SLIPPAGE_EXCEEDED拒绝。 - 修复：
/external/markets/:symbol/ticker的next_funding_time返回下一个 UTC 整点，不再返回 0。 - 修复： Symbol 路径参数（
/funding-rates/:symbol、.../details、/markets/:symbol/...）大小写均接受。
2026-03-26
- 基础文档 / U本位合约 初始发布