Contract
exchange.SetDualMode()
设置持仓模式:单向持仓(One-way)或双向持仓(Hedge)。
语法
python
exchange.SetDualMode(dualSide)参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| dualSide | bool | 是 | 持仓模式:True(双向持仓)或 False(单向持仓) |
返回值
无返回值。如果设置失败会抛出异常。
说明
持仓模式介绍:
-
单向持仓模式(One-way Mode):
- 同一合约只能持有一个方向的仓位(多仓或空仓)
- 开反向单会直接平掉当前持仓
- 适合趋势跟踪策略
- 操作简单,适合新手
-
双向持仓模式(Hedge Mode):
- 同一合约可以同时持有多仓和空仓
- 多空仓位独立计算盈亏
- 适合对冲、套利、网格等策略
- 可以锁仓(同时持有等量多空)
注意事项:
- 持仓限制:切换持仓模式前必须平掉所有持仓和挂单
- 交易所支持:
- ✅ Gate.io 永续合约:完全支持(API:
POST /futures/{settle}/dual_mode) - ✅ Binance 永续合约:完全支持(API:
POST /fapi/v1/positionSide/dual) - ❌ 现货交易:不支持(会返回错误)
- ✅ Gate.io 永续合约:完全支持(API:
- 与仓位模式的区别:
SetPositionMode():设置保证金模式(全仓/逐仓)SetDualSidePosition():设置持仓方向模式(单向/双向)- 两者可以独立设置,互不影响
- 下单方向:
- 单向持仓:使用
SetDirection("buy"/"sell") - 双向持仓:使用
SetDirection("buy"/"sell"/"closebuy"/"closesell")
- 单向持仓:使用
示例
基础用法
python
# 设置为双向持仓模式(可同时持有多空)
exchange.SetDualMode(True)
Log("已切换到双向持仓模式")
# 设置为单向持仓模式(只能持有一个方向)
exchange.SetDualMode(False)
Log("已切换到单向持仓模式")安全切换持仓模式
python
def switch_dual_side_mode(enable_dual_side):
"""安全地切换单向/双向持仓模式"""
# 1. 检查当前持仓
positions = exchange.GetPosition()
if positions:
Log("⚠️ 检测到当前持仓,无法切换持仓模式")
Log("请先平仓后再切换")
return False
# 2. 检查挂单
orders = exchange.GetOrders()
if orders:
Log("⚠️ 检测到未完成订单,正在取消...")
for order in orders:
exchange.CancelOrder(order['Id'])
Sleep(1000)
# 3. 切换模式
try:
exchange.SetDualMode(enable_dual_side)
mode_name = "双向持仓" if enable_dual_side else "单向持仓"
Log(f"✓ 成功切换到{mode_name}模式")
return True
except Exception as e:
Log(f"✗ 切换失败: {e}")
return False
# 切换到双向持仓模式
switch_dual_side_mode(True)初始化策略配置
python
def init_futures_strategy():
"""期货策略初始化:完整配置交易环境"""
Log("========== 初始化期货交易环境 ==========")
# 1. 设置合约类型
exchange.SetContractType("swap")
Log("✓ 设置为永续合约")
# 2. 设置持仓模式(单向/双向)
exchange.SetDualMode(True) # 启用双向持仓
Log("✓ 设置为双向持仓模式")
# 3. 设置保证金模式(全仓/逐仓)
exchange.SetPositionMode("cross") # 全仓模式
Log("✓ 设置为全仓模式")
# 4. 设置杠杆倍数
exchange.SetMarginLevel(10) # 10倍杠杆
Log("✓ 设置杠杆为10倍")
Log("========== 初始化完成 ==========")
# 策略启动时调用
init_futures_strategy()双向持仓对冲策略示例
python
def hedge_strategy():
"""双向持仓对冲策略示例"""
# 启用双向持仓模式
exchange.SetDualMode(True)
# 获取当前价格
ticker = exchange.GetTicker()
price = ticker['Last']
# 同时开多仓和空仓(锁仓)
# 开多仓
exchange.SetDirection("buy") # 或 "long"
exchange.Buy(price * 1.001, 1) # 稍高价格挂单
Log("开多仓订单已提交")
# 开空仓
exchange.SetDirection("sell") # 或 "short"
exchange.Sell(price * 0.999, 1) # 稍低价格挂单
Log("开空仓订单已提交")
Sleep(5000)
# 查看持仓(应该同时有多仓和空仓)
positions = exchange.GetPosition()
for pos in positions:
Log(f"持仓: {pos['Type']} | 数量: {pos['Amount']} | 盈亏: {pos['Profit']}")单向持仓趋势策略示例
python
def trend_strategy():
"""单向持仓趋势跟踪策略示例"""
# 设置为单向持仓模式
exchange.SetDualMode(False)
# 获取K线判断趋势
records = exchange.GetRecords()
ma5 = TA.MA(records, 5)
ma20 = TA.MA(records, 20)
current_price = records[-1]['Close']
# 获取当前持仓
position = exchange.GetPosition()
# 金叉做多
if ma5[-1] > ma20[-1] and ma5[-2] <= ma20[-2]:
if position and position[0]['Type'] == 'short':
# 单向模式:直接开多单会自动平空仓
Log("检测到金叉,平空开多")
else:
Log("检测到金叉,开多")
exchange.SetDirection("buy")
exchange.Buy(-1, 1) # 市价开多
# 死叉做空
elif ma5[-1] < ma20[-1] and ma5[-2] >= ma20[-2]:
if position and position[0]['Type'] == 'long':
# 单向模式:直接开空单会自动平多仓
Log("检测到死叉,平多开空")
else:
Log("检测到死叉,开空")
exchange.SetDirection("sell")
exchange.Sell(-1, 1) # 市价开空双向持仓网格策略示例
python
def grid_strategy_dual_side():
"""双向持仓网格策略示例"""
# 启用双向持仓
exchange.SetDualMode(True)
# 网格参数
base_price = 50000 # 基准价格
grid_num = 5 # 网格数量
grid_gap = 100 # 网格间距
amount = 0.01 # 每格数量
# 在基准价上方挂空单,下方挂多单
for i in range(1, grid_num + 1):
# 上方空单
sell_price = base_price + grid_gap * i
exchange.SetDirection("sell")
exchange.Sell(sell_price, amount)
Log(f"挂空单: 价格={sell_price}, 数量={amount}")
# 下方多单
buy_price = base_price - grid_gap * i
exchange.SetDirection("buy")
exchange.Buy(buy_price, amount)
Log(f"挂多单: 价格={buy_price}, 数量={amount}")
Log("网格订单挂单完成")相关方法
SetPositionMode()- 设置保证金模式(全仓/逐仓)SetDirection()- 设置开仓方向SetMarginLevel()- 设置杠杆倍数GetPosition()- 获取持仓信息
常见问题
1. 单向持仓和双向持仓有什么区别?
- 单向持仓:同一合约只能持有一个方向,开反向单会自动平仓并反手
- 双向持仓:同一合约可以同时持有多空仓位,适合对冲策略
2. 如何选择持仓模式?
- 使用单向持仓:趋势跟踪、简单的做多做空策略
- 使用双向持仓:套利、对冲、网格、锁仓等复杂策略
3. 切换模式时提示"有持仓无法切换"怎么办?
必须先平掉所有持仓和挂单才能切换模式:
python
# 1. 取消所有挂单
orders = exchange.GetOrders()
for order in orders:
exchange.CancelOrder(order['Id'])
# 2. 平掉所有持仓
positions = exchange.GetPosition()
for pos in positions:
if pos['Type'] == 'long':
exchange.SetDirection("closebuy")
exchange.Sell(-1, pos['Amount'])
else:
exchange.SetDirection("closesell")
exchange.Buy(-1, pos['Amount'])
Sleep(2000)
# 3. 切换模式
exchange.SetDualMode(True)4. Gate.io 和 Binance 的 API 有什么不同?
- Gate.io:
POST /futures/{settle}/dual_mode?dual_mode=true/false - Binance:
POST /fapi/v1/positionSide/dual?dualSidePosition=true/false
两者功能相同,本平台已封装统一接口,直接调用 SetDualMode() 即可。
5. 双向持仓模式下如何平仓?
python
# 获取持仓
positions = exchange.GetPosition()
for pos in positions:
if pos['Type'] == 'long':
# 平多仓
exchange.SetDirection("closebuy") # 或 "close_long"
exchange.Sell(-1, pos['Amount'])
elif pos['Type'] == 'short':
# 平空仓
exchange.SetDirection("closesell") # 或 "close_short"
exchange.Buy(-1, pos['Amount'])技术细节
Gate.io 实现
go
// 调用 Gate.io SDK
_, resp, err := apiClient.SetDualMode(ctx, settle, dualSide)
// settle: "usdt" 或 "btc"
// dualSide: true (双向) 或 false (单向)Binance 实现
go
// 调用 Binance SDK
err := client.NewChangePositionModeService().
DualSide(dualSide).
Do(ctx)
// dualSide: true (Hedge Mode) 或 false (One-way Mode)更新历史
- 2025-12-04:新增
SetDualMode()方法,支持 Gate.io 和 Binance 期货