公告 Gate 永续合约 API 更新：新增分仓持仓模式功能

Gate 永续合约 API 更新：新增分仓持仓模式功能

2026-04-28 12:09:20 UTC 350 閱讀

[//]:content-type-MARKDOWN-DONOT-DELETE
为进一步提升永续合约交易的策略灵活性，Gate 永续合约已于此前上线分仓持仓模式。现为满足 API 用户的自动化交易需求，我们将于 **2026 年 4 月 30 日** **UTC+8** 对永续合约相关 API 接口进行升级，API 正式支持分仓持仓模式。

### 一、功能概述
分仓持仓模式支持用户在同一永续合约市场下同时持有多方向、多模式的仓位，包括：全仓多头、全仓空头、逐仓多头、逐仓空头。
逐仓模式下，多头与空头仓位可分别设置不同杠杆倍数，且与全仓仓位的杠杆设置相互独立。
详情请参考产品公告：https://www.gate.com/zh/announcements/article/49810

### 二、API 变更细节
#### 1.设置持仓模式,替换dual_mode接口
新增接口：POST /api/v4/futures/{settle}/set_position_mode

* 请求参数 position_mode ，可选值：
single：单向持仓
dual：双向持仓
dual_plus：分仓持仓
* 返回值在dual_mode接口基础上新增字段 position_mode
* 成功切换至分仓模式后，返回 position_mode = dual_plus
* 详情请参考该 <a href="https://www.gate.com/docs/developers/apiv4/zh_CN/futures/#设置持仓模式-替换dual-mode接口" target="_blank">接口文档</a> 。

#### 2. 下单接口
接口
* POST /api/v4/futures/{settle}/orders
* 新增请求字段 pos_margin_mode ，取值：
cross：全仓
isolated：逐仓
* 返回值结构保持不变
* 详情请参考该 <a href="https://www.gate.com/docs/developers/apiv4/zh_CN/futures/#合约交易下单" target="_blank">接口文档</a> 。

#### 3. 账户查询
接口：GET /api/v4/futures/{settle}/accounts

* 返回值新增字段 position_mode ，取值：
single：单向
dual：双向
dual_plus：分仓
* 详情请参考该 <a href="https://www.gate.com/docs/developers/apiv4/zh_CN/futures/#获取合约账号" target="_blank">接口文档</a> 。

#### 4. 仓位查询
接口：GET /api/v4/futures/{settle}/positions/{contract}

* 新增出参字段 pos_margin_mode：表示该仓位的保证金模式
cross：全仓
isolated：逐仓
* 新增返回字段 lever：表示该仓位当前杠杆倍数，将逐步替代原有的 leverage 与 cross_leverage_limit 字段
* 详情请参考该 <a href="https://www.gate.com/docs/developers/apiv4/zh_CN/futures/#获取单个仓位信息" target="_blank">接口文档</a> 。

#### 5. 订单查询
接口：GET /api/v4/futures/{settle}/orders

* 返回值新增字段 pos_margin_mode ，取值：
cross：全仓
isolated：逐仓
* 详情请参考该 <a href="https://www.gate.com/docs/developers/apiv4/zh_CN/futures/#查询合约订单列表" target="_blank">接口文档</a> 。

#### 6. 设置仓位杠杆
新增接口：
POST /api/v4/futures/{settle}/positions/{contract}/set_leverage

参数说明：

* margin_mode（必选）：保证金模式，cross（全仓）或 isolated （逐仓）
* dual_side（可选）：逐仓模式下设置不同方向杠杆时使用，可传dual_long（多头）或 dual_short（空头），全仓不传
* leverage（必选）：杠杆倍数，字符串类型

使用示例：

| 场景 | margin_mode | dual_side | leverage |
| :--- | :--- | :--- | :--- |
| 设置逐仓多头杠杆 | isolated | dual_long | "10" |
| 设置逐仓空头杠杆 | isolated | dual_short | "10" |
| 设置全仓杠杆 | cross | —— | "10" |

详情请参考该 <a href="https://www.gate.com/docs/developers/apiv4/zh_CN/futures/#更新指定模式的杠杆" target="_blank">接口文档</a> 。

### 三、注意事项

* **带单状态限制：** 当前处于带单状态的用户暂不支持切换至分仓持仓模式，请先结束带单后再进行模式切换。
* **风险确认** ：切换至分仓模式前，请确保已充分了解相关风险与保证金规则。
* **杠杆字段迁移** ：原有 leverage 与 cross_leverage_limit 杠杆相关字段仍将保留，分仓模式下建议使用新字段 lever 获取仓位实际杠杆。
* **保证金模式判断** ：请使用 pos_margin_mode 字段判断仓位/订单的全仓或逐仓属性（ cross / isolated ），不依赖原有的 leverage 是否为 0 的判断逻辑（原有逻辑： leverage ≠ 0 为逐仓模式， leverage = 0 为全仓模式）。

漲跌幅與 K 線開盤時間

漲跌顏色

Pay With

Gate 永续合约 API 更新：新增分仓持仓模式功能

Gate 永续合约 API 更新：新增分仓持仓模式功能

選擇語言及地區

選擇您所在的地區

法幣匯率