杠杆档位与仓位限制

概述

ZTDX 的每个 USDⓈ-M 永续合约都配置了一组按交易对维度的风险参数，共同决定了用户可选的最大杠杆以及单笔订单和持仓的最大规模。本页是这些限制的统一参考——每项参数的含义、对外暴露在哪个 API，以及在 POST /fapi/v1/order 入口哪些会作为硬约束被强制执行。

全仓（Unified Margin）模式使用按名义价值分档的杠杆梯度，详见 Unified Margin Overview。以下规则适用于默认的逐仓（Isolated）模式。

按交易对的风险参数

每个交易对都带有以下配置，由后端统一管理，热更新无需重启：

参数	默认值	暴露方式
`max_leverage`	`100`	exchangeInfo 的 `maxLeverage`；用于钳制 `POST /fapi/v1/leverage`
`min_leverage`	`1`	`POST /fapi/v1/leverage` 的下界
`min_order_size_usd`	按交易对配置	下单硬约束（`-1013 FILTER_FAILURE`）
`max_order_size_usd`	按交易对配置	下单硬约束（`-1013 FILTER_FAILURE`）
`max_position_size_usd`	`10,000,000`	Change Leverage 与 Position Risk 响应中的 `maxNotionalValue`
`max_long_oi_usd`	按交易对配置	该交易对全市场 Long 方向持仓总量上限
`max_short_oi_usd`	按交易对配置	该交易对全市场 Short 方向持仓总量上限

参数会随时间调整——上线日、上线后稳定窗口、行情剧烈波动期是临时收紧的常见原因，不要把参数硬编码到客户端，始终从实时 API 读取。

杠杆

杠杆是如何选定的

某个交易对上的有效杠杆是持久化的，不是逐单携带的：

调用 POST /fapi/v1/leverage 设置目标杠杆。服务端会校验它落在 [min_leverage, max_leverage] 区间内，越界返回 -4028 Leverage {n} is not valid. Max: {max_leverage}。
通过校验后，按 (用户, symbol) 维度持久化。
后续的 POST /fapi/v1/order 如果不显式带 leverage 字段，会读取持久值并在入口再次钳制到 [1, max_leverage]。如果交易对的 max_leverage 在用户设置之后被下调，则取两者中较小的一个——持久值不会被自动改写。
如果用户从未为该交易对调用过 POST /fapi/v1/leverage，下单时使用该交易对当前的 max_leverage 作为兜底默认值。

持仓状态下调整杠杆

在已有持仓时下调杠杆不会修改现有仓位的杠杆和强平价格—— 这两个值是开仓时（或最近一次加仓时）锁定的，详见订单、仓位与杠杆流程。新设置只对之后的新订单生效。

单笔订单大小限制

订单 quantity 会先按交易对的 LOT_SIZE 步长向下取整。所得名义价值（quantity × ref_price， ref_price 在 LIMIT 单上是限价、MARKET 单上是当前 mark 价）随后按 [min_order_size_usd, max_order_size_usd] 校验，越界返回 -1013 FILTER_FAILURE：

Order notional 12500.00 exceeds the maximum 10000 USD for ETHUSDT.
Order notional 4.50    is below the minimum 5 USD for ETHUSDT.

max_order_size_usd 是单笔订单的上限。若需要开/加仓到超过这个上限，请拆成多笔订单。

单笔仓位大小限制

max_position_size_usd 以 maxNotionalValue 字段暴露在以下两个响应里：

POST /fapi/v1/leverage — 调整杠杆后该交易对的持仓上限
GET /fapi/v1/positionRisk — 当前持仓所适用的上限

可用此值提前规划策略——例如设计加仓挂单梯度时保持总持仓不会撞到 -1013 而被拒绝。

多空持仓总量上限（OI Cap）

max_long_oi_usd 与 max_short_oi_usd 限制的是该交易对在 全市场多/空方向上各自的总持仓量。仅当订单的净效果是新开或同向加仓时校验（纯平仓单和 reduceOnly 单跳过）。触发时返回：

{
  "error": "BTCUSDT OI cap exceeded on Long side: current $9800000, cap $10000000, requested delta $300000",
  "code": "OI_CAP_EXCEEDED"
}

某一方向已经撞到上限时，所有该方向的开仓单都会被暂停，直到已有仓位被平掉腾出空间。反向（对冲）订单不受影响。

杠杆档位查询接口

为兼容 Binance 风格的客户端工具，按交易对的杠杆档位可结构化获取：

HTTP 请求

GET /api/v1/open-interest/{symbol}/leverage-brackets

无需鉴权。

响应示例

下例对应 max_leverage = 50 的交易对：

[
  {
    "symbol": "BTCUSDT",
    "brackets": [
      { "bracket": 1, "initialLeverage": 50, "notionalCap": 50000,     "notionalFloor": 0,         "maintMarginRatio": "0.004", "cum": "0"       },
      { "bracket": 2, "initialLeverage": 50, "notionalCap": 250000,    "notionalFloor": 50000,     "maintMarginRatio": "0.005", "cum": "50"      },
      { "bracket": 3, "initialLeverage": 25, "notionalCap": 1000000,   "notionalFloor": 250000,    "maintMarginRatio": "0.01",  "cum": "1300"    },
      { "bracket": 4, "initialLeverage": 10, "notionalCap": 5000000,   "notionalFloor": 1000000,   "maintMarginRatio": "0.025", "cum": "16300"   },
      { "bracket": 5, "initialLeverage": 5,  "notionalCap": 10000000,  "notionalFloor": 5000000,   "maintMarginRatio": "0.05",  "cum": "141300"  },
      { "bracket": 6, "initialLeverage": 2,  "notionalCap": 50000000,  "notionalFloor": 10000000,  "maintMarginRatio": "0.1",   "cum": "641300"  },
      { "bracket": 7, "initialLeverage": 1,  "notionalCap": 100000000, "notionalFloor": 50000000,  "maintMarginRatio": "0.125", "cum": "1891300" }
    ]
  }
]

字段含义

字段	含义
`bracket`	1 起步的档位编号
`initialLeverage`	仓位名义价值落在 `[notionalFloor, notionalCap)` 区间时允许的最大杠杆。会被该交易对 `max_leverage` 从上方钳制。
`notionalFloor` / `notionalCap`	该档位覆盖的仓位名义价值区间，单位 USD
`maintMarginRatio`	该档位内适用的维持保证金率
`cum`	用于让维持保证金阶梯连续的累计扣减项（USD），公式为 `MM = notional × maintMarginRatio − cum`

逐仓模式说明： 上述档位是按交易对的 max_leverage 请求时合成的；默认杠杆超过 max_leverage 的档位会被钳到 max_leverage。因此在逐仓模式下，单一仓位实际只看到一个有效杠杆上限（即 max_leverage），与名义价值落在哪一档无关。接口返回多档结构主要是为了兼容风险显示控件、并与全仓（Unified-Margin）模式下逐档生效的 ladder 保持形状一致。

下单入口的校验顺序

提交 POST /fapi/v1/order 时，上述限制按以下顺序逐项校验。任何一项失败都会立即终止：

交易对启用 & 时间戳窗口 — -1121 / 签名时间窗口错误
LOT_SIZE — quantity 按步长向下取整
订单名义价值区间 — min_order_size_usd ≤ quantity × ref_price ≤ max_order_size_usd（-1013）
杠杆钳制 — 持久杠杆钳制到 [1, max_leverage]
reduceOnly 约束 — 必须存在反向持仓（否则 -2022）；quantity 上限为反向仓位规模
保证金充足 — available_balance ≥ required_margin × (1 + buffer)（-2019）
OI 上限 — 仅当订单新开或同向加仓时校验（OI_CAP_EXCEEDED）
撮合引擎入口 — 引擎层检查（GTX 撮上、IOC / FOK 语义等）

排查被拒订单时，先看错误码——它与上面规则一一对应。

概述​

按交易对的风险参数​

杠杆​

杠杆是如何选定的​

持仓状态下调整杠杆​

单笔订单大小限制​

单笔仓位大小限制​

多空持仓总量上限（OI Cap）​

杠杆档位查询接口​

HTTP 请求​

响应示例​

字段含义​

下单入口的校验顺序​

相关文档​

概述