Pharos
Contract

exchange.SetDualMode()

设置持仓模式:单向持仓(One-way)或双向持仓(Hedge)。

语法

python
exchange.SetDualMode(dualSide)

参数

参数类型必填说明
dualSidebool持仓模式:True(双向持仓)或 False(单向持仓)

返回值

无返回值。如果设置失败会抛出异常。

说明

持仓模式介绍

  • 单向持仓模式(One-way Mode)

    • 同一合约只能持有一个方向的仓位(多仓或空仓)
    • 开反向单会直接平掉当前持仓
    • 适合趋势跟踪策略
    • 操作简单,适合新手
  • 双向持仓模式(Hedge Mode)

    • 同一合约可以同时持有多仓和空仓
    • 多空仓位独立计算盈亏
    • 适合对冲、套利、网格等策略
    • 可以锁仓(同时持有等量多空)

注意事项

  1. 持仓限制:切换持仓模式前必须平掉所有持仓和挂单
  2. 交易所支持
    • ✅ Gate.io 永续合约:完全支持(API: POST /futures/{settle}/dual_mode
    • ✅ Binance 永续合约:完全支持(API: POST /fapi/v1/positionSide/dual
    • ❌ 现货交易:不支持(会返回错误)
  3. 与仓位模式的区别
    • SetPositionMode():设置保证金模式(全仓/逐仓)
    • SetDualSidePosition():设置持仓方向模式(单向/双向)
    • 两者可以独立设置,互不影响
  4. 下单方向
    • 单向持仓:使用 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("网格订单挂单完成")

相关方法

常见问题

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.ioPOST /futures/{settle}/dual_mode?dual_mode=true/false
  • BinancePOST /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 期货