七、交易所API直接访问

七、交易所API直接访问

7.1 订单管理

📊 get_orders(account_id, symbol, start, end, extra=None, generate=False)

功能: 获取指定时间范围内的订单列表

参数:

• account_id: 整数，账户ID
• symbol: 字符串，交易对名称
• start: 整数，开始时间戳(毫秒)
• end: 整数，结束时间戳(毫秒)
• extra: 字典，可选，额外参数
• generate: 布尔值，可选，默认为False，设为True时只生成命令而不执行

返回值:

• 订单列表（Order结构数组），每个订单包含:
  • id: 字符串，订单ID
  • cid: 字符串，可选，客户自定义订单ID
  • timestamp: 整数，订单创建时间戳（毫秒）
  • status: 字符串，订单状态，可选值："Open", "PartiallyFilled", "Filled", "Canceled"
  • symbol: 字符串，交易对符号
  • order_type: 字符串，订单类型："Limit", "Market"
  • side: 字符串，订单方向："Buy", "Sell"
  • pos_side: 字符串，可选，仓位方向："Long", "Short"
  • time_in_force: 字符串，订单有效期："GTC", "IOC", "FOK", "PostOnly", "RPI", "GTD"
  • price: 浮点数，可选，订单价格
  • amount: 浮点数，可选，订单数量（基础货币）
  • quote_amount: 浮点数，可选，订单金额（报价货币）
  • filled: 浮点数，已成交数量
  • filled_avg_price: 浮点数，已成交均价
  • fee_detail: 列表，可选，手续费详情，每个元素包含:
    • fee: 浮点数，可选，手续费
    • fee_rate: 浮点数，可选，手续费率
    • fee_coin: 字符串，手续费币种
    • is_maker: 布尔值，可选，是否为maker
  • source: 字符串，来源："Order", "UserTrade"

📊 get_open_orders(account_id, symbol, extra=None, generate=False)

功能: 获取指定交易对的未成交订单列表

参数:

• account_id: 整数，账户ID
• symbol: 字符串，交易对名称
• extra: 字典，可选，额外参数
• generate: 布尔值，可选，默认为False，设为True时只生成命令而不执行

返回值:

• 未成交订单列表（Order结构数组，结构同get_orders返回值）

📊 get_all_open_orders(account_id, extra=None, generate=False)

功能: 获取账户下所有交易对的未成交订单

参数:

• account_id: 整数，账户ID
• extra: 字典，可选，额外参数
• generate: 布尔值，可选，默认为False，设为True时只生成命令而不执行

返回值:

• 所有未成交订单列表（Order结构数组，结构同get_orders返回值）

📊 get_order_by_id(account_id, symbol, order_id=None, cid=None, extra=None, generate=False)

功能: 通过订单ID或客户端订单ID查询单个订单详情

参数:

• account_id: 整数，账户ID
• symbol: 字符串，交易对名称
• order_id: 字符串，可选，订单ID
• cid: 字符串，可选，客户端订单ID
• extra: 字典，可选，额外参数
• generate: 布尔值，可选，默认为False，设为True时只生成命令而不执行

注意: order_id 和 cid 不能同时为空，必须提供其中一个

示例:

# 通过订单ID查询
result = trader.get_order_by_id(
    account_id=0,
    symbol="BTC_USDT",
    order_id="123456789"
)

# 通过客户端订单ID查询
result = trader.get_order_by_id(
    account_id=0,
    symbol="BTC_USDT",
    cid="my_order_001"
)

if "Ok" in result:
    order = result["Ok"]
    print(f"订单ID: {order['id']}")
    print(f"状态: {order['status']}")
    print(f"方向: {order['side']}")
    print(f"已成交: {order['filled']} / {order.get('amount', 0)}")
    print(f"成交均价: {order['filled_avg_price']}")
else:
    print(f"查询失败: {result.get('Err', '未知错误')}")

返回值:

• 订单详情（Order结构，字段同get_orders返回值中的单个元素）

📊 place_order(account_id, order, params=None, extra=None, sync=True, generate=False)

功能: 下单

参数:

• account_id: 整数，账户ID

• order: 字典或对象，订单信息，包含以下字段:

  • symbol: 字符串，必填，交易对名称
  • side: 字符串，必填，交易方向，支持的值:
    • "Buy": 买入
    • "Sell": 卖出
  • order_type: 字符串，必填，订单类型，支持的值:
    • "Limit": 限价单
    • "Market": 市价单
  • amount: 浮点数，可选，基础货币数量（如BTC数量）
  • quote_amount: 浮点数，可选，报价货币数量（如USDT数量），仅部分交易所的现货市价买单需要使用
  • price: 浮点数，可选，订单价格（限价单必填，市价单可选）
  • pos_side: 字符串，可选，仓位方向，支持的值:
    • "Long": 多仓方向
    • "Short": 空仓方向
    • 在双向持仓模式下必须指定，单向持仓模式下可选
  • time_in_force: 字符串，可选，订单有效期，支持的值:
    • "GTC": Good Till Cancel，一直有效直到取消（默认）
    • "IOC": Immediate Or Cancel，无法立即成交的部分就撤销
    • "FOK": Fill Or Kill，无法全部立即成交就撤销
    • "PostOnly": 只做maker，保证订单不会立即成交
  • cid: 字符串，可选，客户端订单ID，建议使用traderv2.create_cid(exchange_name)生成（如traderv2.create_cid("BinanceSwap")）
  • id: 字符串，只读，订单ID（由交易所生成，下单时无需填写）
  • timestamp: 整数，只读，订单创建时间戳，毫秒（由系统生成）
  • status: 字符串，只读，订单状态（由系统维护），支持的值:
    • "Open": 开放状态
    • "PartiallyFilled": 部分成交
    • "Filled": 完全成交
    • "Canceled": 已取消
  • filled: 浮点数，只读，已成交的基础货币数量（由系统维护）
  • filled_avg_price: 浮点数，只读，已成交均价（由系统维护）
  • fee_detail: 列表，只读，手续费详情信息（由系统维护），包含以下字段：
    • fee: 浮点数，可选，手续费具体数值（与fee_rate互斥）
    • fee_rate: 浮点数，可选，手续费费率（如0.0002，与fee互斥）
    • fee_coin: 字符串，手续费币种
    • is_maker: 布尔值，可选，是否为maker订单
    • 注意: 目前仅Bitget Swap和Binance Swap支持此字段
  • source: 字符串，只读，订单来源（由系统维护），支持的值:
    • "Order": 普通订单
    • "UserTrade": 用户成交

• params: 字典或对象，可选，下单参数，包含以下可选字段:

  • is_dual_side: 布尔值，是否使用双向持仓模式，默认为false
  • leverage: 整数，杠杆倍数（仅Huobi需要），默认为1
  • margin_mode: 字符串，保证金模式（仅OKX需要），支持的值:
    • "Cross": 全仓模式
    • "Isolated": 逐仓模式
  • leverage_order_mode: 字符串，可选，杠杆订单模式，支持的值:
    • "Normal": 普通下单（默认）
    • "AutoLoan": 自动借款下单
    • "AutoRepay": 自动还款下单
    • "AutoLoanAndRepay": 自动借款还款下单

  ⚠️ 注意: 以下参数已在 v0.11.0 中废弃，请使用 config.toml 中的 [visitor.order_normalizer] 配置：

  • market_order_mode → visitor.order_normalizer.market_order_mode
  • market_order_slippage → visitor.order_normalizer.market_order_slippage
  • process_amount → visitor.order_normalizer.amount_rounding
  • process_price → visitor.order_normalizer.price_rounding

  详见 配置文件完整指南 中的 Visitor 访问器配置 章节。

• extra: 字典，可选，额外参数，用于兼容各交易所特殊字段

• sync: 布尔值，可选，默认为True，是否同步等待订单结果

  • True: 同步执行，等待订单结果后返回
  • False: 异步执行，立即返回，订单结果通过on_order_submitted回调函数返回

• generate: 布尔值，可选，默认为False，设为True时只生成命令而不执行

重要说明:

1. amount与quote_amount使用说明:

   • amount: 基础货币数量，适用于绝大多数场景（合约交易、现货限价单等）
   • quote_amount: 报价货币数量，仅在部分交易所的现货市价买单时使用，如使用500 USDT市价买入BTC
   • 一般情况下只使用amount字段即可

2. 市价单模式说明（v0.11.0+ 通过 config.toml 的 [visitor.order_normalizer] 配置）:

   • "Safe": 安全模式，将市价单转换为带滑点的IOC限价单，需要传递价格
   • "Normal": 普通模式，真正的市价单，无需传递价格

3. RoundingStrategy 处理方式说明（v0.11.0+ 通过 config.toml 的 [visitor.order_normalizer] 配置）:

   • "BuyCeilSellFloor": 根据买卖方向决定，买入时向上取整，卖出时向下取整
   • "BuyFloorSellCeil": 根据买卖方向决定，买入时向下取整，卖出时向上取整
   • "Ceil": 始终向上取整
   • "Floor": 始终向下取整
   • "Round": 四舍五入
   • "None": 不进行任何处理，保持原始精度

   全局配置示例（config.toml）:

   [visitor.order_normalizer]
   enabled = true
   price_rounding = "BuyCeilSellFloor"  # 价格处理，默认买向上取整，卖向下取整
   amount_rounding = "Round"            # 数量处理，默认四舍五入
   market_order_mode = "Safe"           # 市价单模式，默认安全模式
   market_order_slippage = 0.002        # 市价单滑点，默认0.2%

pos_side参数说明:

• "Long": 多仓方向
• "Short": 空仓方向
• 在双向持仓模式(is_dual_side=True)下，此参数为必填
• 在单向持仓模式下，此参数可选，但建议填写以提高订单明确性
• 当需要只减仓(reduce_only)时，必须传递此参数

返回值:

• Result结构: 包含Ok或Err字段的字典
• 成功时: {"Ok": order_result} - 下单成功结果
• 失败时: {"Err": error_info} - 包含错误信息

示例:

# ✅ 完整的下单示例 - 限价单（合约交易）
order = {
    "cid": traderv2.create_cid("BinanceSwap"),
    "symbol": "BTC_USDT",
    "order_type": "Limit",
    "side": "Buy",
    "pos_side": "Long",  # 指定仓位方向
    "price": 50000.0,
    "amount": 0.01,       # 使用amount字段，不需要quote_amount
    "time_in_force": "GTC"
}

params = {
    "is_dual_side": True,  # 双向持仓模式
    # "leverage": 10,      # 仅Huobi需要，其他交易所使用set_leverage接口
    # "margin_mode": "Cross" # 仅OKX需要
}
# 注意：价格和数量的处理方式现在通过 config.toml 的 [visitor.order_normalizer] 全局配置

result = trader.place_order(0, order, params, sync=True)

if "Ok" in result:
    order_result = result["Ok"]
    print(f"下单成功: {order_result}")
else:
    error = result.get("Err", "未知错误")
    print(f"下单失败: {error}")

# ✅ 市价单示例（合约交易）
# 注意：市价单模式现在通过 config.toml 的 [visitor.order_normalizer.market_order_mode] 全局配置
# 默认为 "Safe" 模式，需要传递价格；如需使用 "Normal" 模式，请在配置文件中修改
market_order = {
    "cid": traderv2.create_cid("BinanceSwap"),
    "symbol": "ETH_USDT",
    "order_type": "Market",
    "side": "Sell",
    "pos_side": "Short",  # 空仓
    "price": 3500.0,      # Safe 模式下需要提供价格
    "amount": 0.5,        # 使用amount字段，标准合约市价单
    "time_in_force": "IOC"
}

params = {
    "is_dual_side": True
}

result = trader.place_order(0, market_order, params, sync=True)

# ✅ 使用quote_amount下单（仅部分交易所现货市价买单需要）
quote_order = {
    "cid": traderv2.create_cid("BinanceSpot"),  # 现货交易所示例
    "symbol": "BTC_USDT",
    "order_type": "Market",
    "side": "Buy",
    # "pos_side": "Long",    # 现货不需要pos_side
    "quote_amount": 1000.0,  # 使用1000 USDT市价买入BTC（特定交易所现货功能）
    "time_in_force": "IOC"
}

params = {
    "is_dual_side": False
}

# 注意：这是特殊用法，大多数情况下请使用amount字段
result = trader.place_order(0, quote_order, params, sync=True)

# ✅ 精确控制示例
# 注意：数量和价格的处理方式现在通过 config.toml 的 [visitor.order_normalizer] 全局配置
# 如需自定义，请在配置文件中设置 price_rounding 和 amount_rounding
precision_order = {
    "cid": traderv2.create_cid("BinanceSwap"),
    "symbol": "SOL_USDT",
    "order_type": "Limit",
    "side": "Sell",
    "pos_side": "Short",
    "price": 100.0,
    "amount": 5.678901,  # 原始数量，将根据配置文件中的 amount_rounding 处理
    "time_in_force": "GTC"
}

params = {
    "is_dual_side": True
}

result = trader.place_order(0, precision_order, params, sync=True)

# ✅ 单向持仓模式示例（pos_side可选但建议添加）
single_side_order = {
    "cid": traderv2.create_cid("BinanceSwap"),
    "symbol": "SOL_USDT",
    "order_type": "Limit",
    "side": "Buy",
    "pos_side": "Long",  # 虽然单向持仓可选，但建议添加
    "price": 100.0,
    "amount": 1.0,
    "time_in_force": "PostOnly"
}

params = {
    "is_dual_side": False  # 单向持仓模式
    # "leverage": 3        # 仅Huobi需要
}

result = trader.place_order(0, single_side_order, params, sync=True)

# ⚠️ 错误示例 - 双向持仓模式下缺少pos_side
wrong_order = {
    "symbol": "BTC_USDT",
    "order_type": "Limit",
    "side": "Buy",
    # "pos_side": "Long",  # 缺少此字段在双向持仓下会报错
    "price": 50000.0,
    "amount": 0.01
}

params = {"is_dual_side": True}
result = trader.place_order(0, wrong_order, params)
# 这会返回错误: {"Err": "pos_side is required in dual side mode"}

# ✅ 异步下单示例
async_order = {
    "cid": traderv2.create_cid("BinanceSwap"),
    "symbol": "BTC_USDT",
    "order_type": "Limit",
    "side": "Buy",
    "pos_side": "Long",
    "price": 50000.0,
    "amount": 0.01,
    "time_in_force": "GTC"
}

params = {"is_dual_side": False}

# 异步执行，不等待结果，结果会在on_order_submitted回调中返回
result = trader.place_order(0, async_order, params, sync=False)
print("订单已提交，结果将在on_order_submitted回调中返回")

# 对应的回调函数处理：
def on_order_submitted(self, account_id, order_id_result, order):
    """
    异步订单提交完成时触发的回调

    Args:
        account_id: 账户ID
        order_id_result: 订单ID结果，格式为{"Ok": "订单ID"} 或 {"Err": "错误信息"}
        order: 订单信息
    """
    if "Ok" in order_id_result:
        order_id = order_id_result["Ok"]
        print(f"异步订单提交成功，订单ID: {order_id}")
    else:
        error = order_id_result.get("Err", "未知错误")
        print(f"异步订单提交失败: {error}")

# ✅ 生成命令不执行示例
command = trader.place_order(0, order, params, generate=True)
print(f"生成的命令: {command}")
# 可以稍后使用trader.publish(command)执行

# ✅ Huobi交易所专用示例（需要leverage参数）
huobi_order = {
    "cid": traderv2.create_cid("HuobiSwap"),
    "symbol": "BTC_USDT",
    "order_type": "Limit",
    "side": "Buy",
    "pos_side": "Long",
    "price": 50000.0,
    "amount": 0.01,
    "time_in_force": "GTC"
}

huobi_params = {
    "is_dual_side": True,
    "leverage": 10  # Huobi交易所必需的杠杆参数
}

result = trader.place_order(0, huobi_order, huobi_params, sync=True)

# ✅ OKX交易所专用示例（需要margin_mode参数）
okx_order = {
    "cid": traderv2.create_cid("OkxSwap"),
    "symbol": "BTC_USDT",
    "order_type": "Limit",
    "side": "Buy",
    "pos_side": "Long",
    "price": 50000.0,
    "amount": 0.01,
    "time_in_force": "GTC"
}

okx_params = {
    "is_dual_side": True,
    "margin_mode": "Cross"  # OKX交易所必需的保证金模式参数
}

result = trader.place_order(0, okx_order, okx_params, sync=True)

pos_side使用场景总结:

场景	is_dual_side	pos_side是否必需	说明
双向持仓开多仓	True	✅ 必需 "Long"	在多空并存模式下必须明确方向
双向持仓开空仓	True	✅ 必需 "Short"	在多空并存模式下必须明确方向
单向持仓开仓	False	📋 建议添加	提高订单明确性，避免歧义
只减仓订单	任意	✅ 必需	减仓时必须明确要平哪个方向的仓位
平仓订单	任意	✅ 必需	平仓时必须指定要平的仓位方向

常见问题解答:

1. Q: amount和quote_amount的区别？什么时候使用quote_amount？ A: amount是基础货币数量（如BTC数量），适用于绝大多数场景；quote_amount是报价货币数量（如USDT数量），仅在部分交易所的现货市价买单时使用。一般情况下只需要使用amount字段。

2. Q: 什么时候使用安全模式vs普通模式？ A: 安全模式适合对滑点控制要求较高的场景，通过market_order_slippage参数控制滑点；普通模式适合追求快速成交的场景。

3. Q: 如何判断是否需要设置pos_side？ A: 双向持仓模式必须设置，单向持仓模式建议设置以避免歧义。

4. Q: 同步和异步的区别？ A: sync=True会等待订单执行结果返回；sync=False立即返回不等待结果，订单结果会通过对应的回调函数返回，适合高频交易场景。具体回调函数如下：

   • place_order → on_order_submitted
   • amend_order → on_order_amended
   • cancel_order → on_order_canceled
   • batch_place_order → on_batch_order_submitted
   • batch_cancel_order → on_batch_order_canceled
   • batch_cancel_order_by_id → on_batch_order_canceled_by_ids

5. Q: 什么时候需要设置leverage参数？ A: 仅在使用Huobi交易所时需要设置leverage参数，其他交易所请使用set_leverage接口设置杠杆。

6. Q: 什么时候需要设置margin_mode？ A: 主要在OKX等支持保证金模式选择的交易所使用，Cross为全仓，Isolated为逐仓。

7. Q: 如何正确配置市价单的滑点控制？ A: 使用market_order_mode: "Safe"并通过market_order_slippage设置滑点，如market_order_slippage: 0.002表示0.2%滑点。

8. Q: 合约交易和现货限价单是否需要quote_amount？ A: 不需要。合约交易（如BinanceSwap、OkxSwap等）和现货限价单请使用amount字段。quote_amount仅在特定现货交易所的市价买单时才需要。

9. Q: 订单创建失败的常见原因？ A: 1) 双向持仓模式未设置pos_side 2) 余额不足 3) 超出最大杠杆 4) 价格精度不正确 5) 最小下单量不满足要求 6) 错误使用quote_amount字段。

10. Q: Bitget交易所下单有什么特殊要求？ A: Bitget交易所下单时，如果返回的order_id为null，系统会自动置空处理。这是正常现象，不会影响订单的正常执行。

11. Q: process_amount和process_price参数的作用是什么？ A: 这两个参数都使用RoundingStrategy枚举来控制OpenQuant对订单数量和价格的自动处理方式。process_amount控制数量精度处理（默认Round），process_price控制价格精度处理（默认BuyCeilSellFloor），可以根据交易策略需求选择合适的处理方式。

12. Q: 什么时候使用不同的RoundingStrategy处理方式？ A: BuyCeilSellFloor适合确保买入成交/数量充足，卖出获得更好价格/精确数量；BuyFloorSellCeil适合控制买入成本，确保卖出收益；Ceil适合确保订单成交/数量充足；Floor适合控制订单成本；Round适合平衡精度和成本；None适合保持原始精度。

📊 batch_place_order(account_id, orders, params=None, extra=None, sync=True, generate=False)

功能: 批量下单

参数:

• account_id: 整数，账户ID
• orders: 列表，多个订单信息，每个订单包含与place_order中order相同的字段
• params: 字典或对象，可选，下单参数，与place_order中params相同
• extra: 字典，可选，额外参数
• sync: 布尔值，可选，默认为True，是否同步等待订单结果
• generate: 布尔值，可选，默认为False，设为True时只生成命令而不执行

返回值:

• 批量下单结果数据列表

示例:

# 批量下单
orders = [
    {
        "cid": traderv2.create_cid("BinanceSwap"),
        "symbol": "BTC_USDT",
        "order_type": "Limit",
        "side": "Buy",
        "pos_side": "Long",
        "price": 50000.0,
        "amount": 0.01,
        "time_in_force": "GTC"
    },
    {
        "cid": traderv2.create_cid("BinanceSwap"),
        "symbol": "ETH_USDT",
        "order_type": "Limit",
        "side": "Buy",
        "pos_side": "Long",
        "price": 3000.0,
        "amount": 0.1,
        "time_in_force": "GTC"
    }
]

params = {"is_dual_side": False}

# 同步批量下单
result = trader.batch_place_order(0, orders, params, sync=True)

# 异步批量下单，结果会在on_batch_order_submitted回调中返回
result = trader.batch_place_order(0, orders, params, sync=False)
print("批量订单已提交，结果将在on_batch_order_submitted回调中返回")

# 对应的回调函数处理：
def on_batch_order_submitted(self, account_id, batch_order_rsp):
    """
    异步批量订单提交完成时触发的回调

    Args:
        account_id: 账户ID
        batch_order_rsp: 批量订单响应结果列表
    """
    for order_result in batch_order_rsp:
        if "Ok" in order_result.get("result", {}):
            order_id = order_result["result"]["Ok"]
            print(f"订单提交成功，订单ID: {order_id}")
        else:
            error = order_result.get("result", {}).get("Err", "未知错误")
            print(f"订单提交失败: {error}")

📊 amend_order(account_id, order, extra=None, sync=True, generate=False)

功能: 修改订单

参数:

• account_id: 整数，账户ID
• order: 字典或对象，订单修改信息，包含以下字段:
  • symbol: 字符串，交易对名称
  • order_id: 字符串，订单ID
  • price: 浮点数，可选，新价格
  • amount: 浮点数，可选，新数量
  • cid: 字符串，可选，客户端订单ID(用于替代order_id)
• extra: 字典，可选，额外参数
• sync: 布尔值，可选，默认为True，是否同步等待修改结果
• generate: 布尔值，可选，默认为False，设为True时只生成命令而不执行

返回值:

• 成功时返回修改后的订单ID（字符串）
• 失败时返回错误信息

示例:

# 修改订单价格
result = trader.amend_order(
    account_id=0,
    order={
        "symbol": "BTC_USDT",
        "order_id": "123456789",
        "price": 50000.0
    }
)

# 修改订单数量
result = trader.amend_order(
    account_id=0,
    order={
        "symbol": "BTC_USDT",
        "order_id": "123456789",
        "amount": 0.1
    }
)

# 同时修改价格和数量
result = trader.amend_order(
    account_id=0,
    order={
        "symbol": "BTC_USDT",
        "order_id": "123456789",
        "price": 50000.0,
        "amount": 0.1
    }
)

# 使用客户端订单ID修改订单
result = trader.amend_order(
    account_id=0,
    order={
        "symbol": "BTC_USDT",
        "cid": "my_order_001",
        "price": 50000.0
    }
)

# 异步修改订单，不等待结果，结果会在on_order_amended回调中返回
result = trader.amend_order(
    account_id=0,
    order={
        "symbol": "BTC_USDT",
        "order_id": "123456789",
        "price": 51000.0
    },
    sync=False
)
print("订单修改请求已提交，结果将在on_order_amended回调中返回")

# 对应的回调函数处理：
def on_order_amended(self, account_id, result, order):
    """
    异步订单修改完成时触发的回调

    Args:
        account_id: 账户ID
        result: 修改结果，格式为{"Ok": "订单ID"} 或 {"Err": "错误信息"}
        order: 订单信息
    """
    if "Ok" in result:
        order_id = result["Ok"]
        print(f"异步订单修改成功，订单ID: {order_id}")
    else:
        error = result.get("Err", "未知错误")
        print(f"异步订单修改失败: {error}")

注意事项:

1. Bitget交易所特殊要求: 当使用Bitget交易所时，修改订单接口需要在extra参数中传递new_cid字段来设置新的订单cid。例如：

   result = trader.amend_order(
       account_id=0,
       order={
           "symbol": "BTC_USDT",
           "order_id": "123456789",
           "price": 50000.0
       },
       extra={"new_cid": "new_order_cid_001"}
   )
2. 订单状态: 只能修改未成交的订单，已成交或已取消的订单无法修改
3. 修改限制: 不同交易所对订单修改的限制可能不同，请参考具体交易所的API文档
4. 价格精度: 修改价格时需要符合交易所的价格精度要求
5. 数量精度: 修改数量时需要符合交易所的数量精度要求

📊 batch_amend_order(account_id, orders, extra=None, sync=True, generate=False)

功能: 批量修改订单

支持的交易所: 目前仅 BinanceSwap 实现

参数:

• account_id: 整数，账户ID
• orders: 列表，多个订单修改信息，每个订单包含与amend_order中order相同的字段:
  • symbol: 字符串，交易对名称
  • order_id: 字符串，订单ID
  • price: 浮点数，可选，新价格
  • amount: 浮点数，可选，新数量
  • cid: 字符串，可选，客户端订单ID(用于替代order_id)
• extra: 字典，可选，额外参数
• sync: 布尔值，可选，默认为True，是否同步等待修改结果
• generate: 布尔值，可选，默认为False，设为True时只生成命令而不执行

返回值:

• 批量修改结果数据列表

示例:

# 批量修改订单
orders = [
    {
        "symbol": "BTC_USDT",
        "order_id": "123456789",
        "price": 50000.0
    },
    {
        "symbol": "ETH_USDT",
        "order_id": "987654321",
        "price": 3000.0,
        "amount": 0.1
    }
]

# 同步批量修改订单
result = trader.batch_amend_order(0, orders, sync=True)

# 处理返回结果
for order_result in result:
    if "Ok" in order_result.get("result", {}):
        order_id = order_result["result"]["Ok"]
        print(f"订单修改成功，订单ID: {order_id}")
    else:
        error = order_result.get("result", {}).get("Err", "未知错误")
        print(f"订单修改失败: {error}")

# 异步批量修改订单，结果会在on_batch_amend_order回调中返回
result = trader.batch_amend_order(0, orders, sync=False)
print("批量订单修改请求已提交，结果将在on_batch_amend_order回调中返回")

# 对应的回调函数处理：
def on_batch_amend_order(self, account_id, order_ids_result):
    """
    异步批量订单修改完成时触发的回调

    Args:
        account_id: 账户ID
        order_ids_result: 批量订单修改响应结果列表
    """
    for order_result in order_ids_result:
        if "Ok" in order_result.get("result", {}):
            order_id = order_result["result"]["Ok"]
            print(f"订单修改成功，订单ID: {order_id}")
        else:
            error = order_result.get("result", {}).get("Err", "未知错误")
            print(f"订单修改失败: {error}")

注意事项:

1. 交易所支持: 目前仅BinanceSwap交易所实现了此接口，其他交易所调用会返回"未实现"错误
2. 订单状态: 只能修改未成交的订单，已成交或已取消的订单无法修改
3. 修改限制: 请参考具体交易所的API文档了解批量修改的数量限制
4. 价格精度: 修改价格时需要符合交易所的价格精度要求
5. 数量精度: 修改数量时需要符合交易所的数量精度要求

📊 cancel_order(account_id, symbol, order_id=None, cid=None, extra=None, sync=True, generate=False)

功能: 取消订单

参数:

• account_id: 整数，账户ID
• symbol: 字符串，交易对名称
• order_id: 字符串，可选，订单ID
• cid: 字符串，可选，客户端订单ID
• extra: 字典，可选，额外参数
• sync: 布尔值，可选，默认为True，是否同步等待取消结果
• generate: 布尔值，可选，默认为False，设为True时只生成命令而不执行

注意: order_id 和 cid 不能同时为空，必须提供其中一个

示例:

# 通过订单ID取消
result = trader.cancel_order(
    account_id=0,
    symbol="BTC_USDT",
    order_id="123456789"
)

# 通过客户端订单ID取消
result = trader.cancel_order(
    account_id=0,
    symbol="BTC_USDT",
    cid="my_order_001"
)

# 异步取消订单，结果会在on_order_canceled回调中返回
result = trader.cancel_order(
    account_id=0,
    symbol="BTC_USDT",
    order_id="123456789",
    sync=False
)
print("取消订单请求已提交，结果将在on_order_canceled回调中返回")

# 对应的回调函数处理：
def on_order_canceled(self, account_id, result, order_id, symbol):
    """
    异步取消订单完成时触发的回调

    Args:
        account_id: 账户ID
        result: 取消结果，格式为{"Ok": null} 或 {"Err": "错误信息"}
        order_id: 订单ID
        symbol: 交易对名称
    """
    if "Ok" in result:
        print(f"订单取消成功，订单ID: {order_id}, 交易对: {symbol}")
    else:
        error = result.get("Err", "未知错误")
        print(f"订单取消失败: {error}")

返回值:

• 成功时返回 None（取消成功无返回值）
• 失败时返回错误信息

📊 batch_cancel_order(account_id, symbol, extra=None, sync=True, generate=False)

功能: 批量取消指定交易对的所有未成交订单

参数:

• account_id: 整数，账户ID
• symbol: 字符串，交易对名称
• extra: 字典，可选，额外参数
• sync: 布尔值，可选，默认为True，是否同步等待取消结果
• generate: 布尔值，可选，默认为False，设为True时只生成命令而不执行

返回值:

• 批量取消订单结果（BatchOrderRsp结构），包含:
  • success_list: 列表，成功取消的订单，每个元素包含:
    • id: 字符串，可选，订单ID
    • cid: 字符串，可选，客户端订单ID
  • failure_list: 列表，取消失败的订单，每个元素包含:
    • id: 字符串，可选，订单ID
    • cid: 字符串，可选，客户端订单ID
    • error_code: 整数，错误码
    • error: 字符串，错误信息

示例:

# 同步批量取消指定交易对的所有未成交订单
result = trader.batch_cancel_order(
    account_id=0,
    symbol="BTC_USDT"
)

# 异步批量取消，结果会在on_batch_order_canceled回调中返回
result = trader.batch_cancel_order(
    account_id=0,
    symbol="BTC_USDT",
    sync=False
)
print("批量取消请求已提交，结果将在on_batch_order_canceled回调中返回")

# 对应的回调函数处理：
def on_batch_order_canceled(self, account_id, batch_order_rsp):
    """
    异步批量取消订单完成时触发的回调

    Args:
        account_id: 账户ID
        batch_order_rsp: 批量取消订单响应结果
    """
    print(f"批量取消订单完成，账户: {account_id}, 结果: {batch_order_rsp}")

📊 batch_cancel_order_by_id(account_id, symbol=None, order_ids=None, client_order_ids=None, extra=None, sync=True, generate=False)

功能: 批量取消指定ID的订单

参数:

• account_id: 整数，账户ID
• symbol: 字符串，可选，交易对名称
• order_ids: 字符串列表，可选，订单ID列表
• client_order_ids: 字符串列表，可选，客户端订单ID列表
• extra: 字典，可选，额外参数
• sync: 布尔值，可选，默认为True，是否同步等待取消结果
• generate: 布尔值，可选，默认为False，设为True时只生成命令而不执行

返回值:

• 批量取消订单结果（BatchOrderRsp结构，同batch_cancel_order返回值）

示例:

# 通过订单ID批量取消
result = trader.batch_cancel_order_by_id(
    account_id=0,
    symbol="BTC_USDT",
    order_ids=["123456789", "123456790", "123456791"]
)

# 通过客户端订单ID批量取消
result = trader.batch_cancel_order_by_id(
    account_id=0,
    symbol="BTC_USDT",
    client_order_ids=["my_order_001", "my_order_002"]
)

# 异步批量取消，结果会在on_batch_order_canceled_by_ids回调中返回
result = trader.batch_cancel_order_by_id(
    account_id=0,
    symbol="BTC_USDT",
    order_ids=["123456789", "123456790"],
    sync=False
)
print("批量取消请求已提交，结果将在on_batch_order_canceled_by_ids回调中返回")

# 对应的回调函数处理：
def on_batch_order_canceled_by_ids(self, account_id, batch_order_rsp):
    """
    异步批量按ID取消订单完成时触发的回调

    Args:
        account_id: 账户ID
        batch_order_rsp: 批量取消订单响应结果
    """
    print(f"批量取消订单完成，账户: {account_id}, 结果: {batch_order_rsp}")

🔧 CloseTrigger结构体说明

止损订单使用CloseTrigger结构体定义触发条件和执行行为，提供了丰富的配置选项：

CloseTrigger结构体字段:

• id: 可选，订单ID（下单时不填，系统自动生成）
• cid: 可选，客户自定义订单ID，便于订单跟踪
• trigger_price: 必填，触发价格配置（TriggerPrice枚举）
• trigger_action: 必填，触发后的执行行为（TriggerAction结构）

TriggerPrice（触发价格类型）:

• {"MarkPrice": 价格}: 标记价格触发，最稳定，推荐使用
• {"ContractPrice": 价格}: 最新成交价触发，响应最快
• {"IndexPrice": 价格}: 指数价格触发，最平滑

TriggerAction（触发行为）:

• quantity: 可选，触发数量，不填则全平持仓
• trailing_gap: 可选，回调幅度百分比，追踪止盈必填
• execute_type: 执行类型
  • "Market": 市价执行（默认）
  • {"Limit": 价格}: 限价执行
• typ: 订单类型
  • "Normal": 一般止损/止盈（默认）
  • "Trailing": 追踪止盈

特殊功能:

• 追踪止盈: 当typ为"Trailing"时，价格朝有利方向移动时止盈线会跟踪调整，直到价格回调达到trailing_gap幅度时触发
• 部分平仓: 通过quantity字段可以实现部分止盈/止损，其余仓位继续持有
• 多种触发价格: 支持标记价格、成交价格、指数价格三种触发方式，适应不同交易策略

📊 StopOrder数据结构

以下是止损订单相关的完整数据结构定义：

StopOrder（完整止损订单信息）:

{
    "symbol": "BTC_USDT",           # 交易对符号
    "take_profit": {                # 止盈订单配置（可选）
        "id": "123456789",          # 止盈订单ID（系统生成）
        "cid": "client_tp_001",     # 客户自定义ID（可选）
        "trigger_price": {"MarkPrice": 52000.0},  # 触发价格
        "trigger_action": {         # 触发行为
            "quantity": 0.5,        # 触发数量（可选，不填则全平）
            "trailing_gap": 2.0,    # 回调幅度(%)（可选，追踪止盈时必填）
            "execute_type": "Market", # 执行类型："Market"或{"Limit": 价格}
            "typ": "Normal"         # 订单类型："Normal"或"Trailing"
        }
    },
    "stop_loss": {                  # 止损订单配置（可选）
        "id": "987654321",          # 止损订单ID（系统生成）
        "cid": "client_sl_001",     # 客户自定义ID（可选）
        "trigger_price": {"ContractPrice": 48000.0}, # 触发价格
        "trigger_action": {         # 触发行为
            "quantity": null,       # 全平仓位
            "trailing_gap": null,   # 不使用追踪
            "execute_type": "Market", # 市价执行
            "typ": "Normal"         # 一般止损
        }
    },
    "status": "Open",               # 订单状态
    "c_time": 1640995200000,        # 创建时间（毫秒时间戳）
    "u_time": 1640998800000         # 更新时间（毫秒时间戳）
}

StopOrderStatus（止损订单状态枚举）:

• "Open": 未触发（默认状态）
• "Executed": 已触发执行
• "Canceled": 已取消
• "Failed": 触发失败

StopOrderIdRsp（止损订单操作返回结果）:

{
    "take_profit": {                # 止盈订单结果（可选）
        "Ok": "123456789"           # 成功时返回订单ID
        # 或
        "Err": "错误信息"            # 失败时返回错误信息
    },
    "stop_loss": {                  # 止损订单结果（可选）
        "Ok": "987654321"           # 成功时返回订单ID
        # 或
        "Err": "错误信息"            # 失败时返回错误信息
    }
}

ExecuteType（执行类型枚举）:

• "Market": 市价执行（默认）
• {"Limit": 价格}: 限价执行，如{"Limit": 50000.0}

ActionType（订单类型枚举）:

• "Normal": 一般止损/止盈（默认）
• "Trailing": 追踪止盈

TriggerPrice（触发价格类型）:

• {"MarkPrice": 价格}: 标记价格触发，如{"MarkPrice": 50000.0}
• {"ContractPrice": 价格}: 最新成交价触发，如{"ContractPrice": 50000.0}
• {"IndexPrice": 价格}: 指数价格触发，如{"IndexPrice": 50000.0}

📊 post_stop_order(account_id, symbol, pos_side, take_profit=None, stop_loss=None, is_dual_side=False, extra=None, generate=False)

功能: 下止损订单

参数:

• account_id: 整数，必需，账户ID
• symbol: 字符串，必需，交易对名称
• pos_side: 字符串，必需，仓位方向，例如"Long"或"Short"
• take_profit: 字典，可选，止盈订单配置（CloseTrigger结构），包含以下字段：
  • cid: 字符串，可选，客户自定义订单ID
  • trigger_price: 字典，触发价格配置，支持以下类型：
    • {"MarkPrice": 价格}: 标记价格触发
    • {"ContractPrice": 价格}: 最新成交价/市场价触发
    • {"IndexPrice": 价格}: 指数价格触发
  • trigger_action: 字典，触发行为配置，包含：
    • quantity: 浮点数，可选，触发数量，不填则全平
    • trailing_gap: 浮点数，可选，回调幅度(%)，追踪止盈时必填
    • execute_type: 字符串或字典，执行类型：
      • "Market": 市价平仓
      • {"Limit": 价格}: 限价平仓
    • typ: 字符串，可选，类型："Normal"(一般)或"Trailing"(追踪)，默认"Normal"
• stop_loss: 字典，可选，止损订单配置（CloseTrigger结构），字段同take_profit
• is_dual_side: 布尔值，可选，是否使用双向持仓模式，默认为False
• extra: 字典，可选，额外参数
• generate: 布尔值，可选，默认为False，设为True时只生成命令而不执行

重要:

• 此方法仅支持同步执行，无 sync 参数
• 必需参数: account_id、symbol、pos_side 为必需参数
• 配置要求: take_profit 和 stop_loss 至少需要提供其中一个，否则无法创建止损订单
• 仓位方向: pos_side 必须正确设置，与要保护的仓位方向一致

返回值:

• Result结构: 包含Ok或Err字段的字典
• 示例:

{
  "Ok": {
    "stop_loss": {
      "Ok": "1326362257269604352"
    },
    "take_profit": {
      "Ok": "1326362256586391552"
    }
  }
}

示例:

# ✅ 基础止损订单 - 标记价格触发
result = trader.post_stop_order(
    account_id=0,
    symbol="BTC_USDT",
    pos_side="Long",
    stop_loss={
        "trigger_price": {"MarkPrice": 49000.0},  # 标记价格触发
        "trigger_action": {
            "execute_type": "Market",  # 市价平仓
            "typ": "Normal"           # 一般止损
        }
    },
    is_dual_side=True
)

if "Ok" in result:
    order_result = result["Ok"]
    print(f"止损订单下达成功: {order_result}")
else:
    error = result.get("Err", "未知错误")
    print(f"止损订单失败: {error}")

# ✅ 止盈订单 - 合约价格触发，指定数量
result = trader.post_stop_order(
    account_id=0,
    symbol="ETH_USDT",
    pos_side="Long",
    take_profit={
        "cid": "my_take_profit_001",              # 自定义订单ID
        "trigger_price": {"ContractPrice": 3500.0},  # 合约价格触发
        "trigger_action": {
            "quantity": 0.5,                      # 止盈数量
            "execute_type": {"Limit": 3510.0},    # 限价3510平仓
            "typ": "Normal"
        }
    },
    is_dual_side=True
)

# ✅ 追踪止盈订单
result = trader.post_stop_order(
    account_id=0,
    symbol="SOL_USDT",
    pos_side="Long",
    take_profit={
        "trigger_price": {"MarkPrice": 100.0},    # 标记价格100触发
        "trigger_action": {
            "trailing_gap": 2.0,                  # 回调2%时执行
            "execute_type": "Market",              # 市价平仓
            "typ": "Trailing"                     # 追踪止盈
        }
    },
    is_dual_side=True
)

# ✅ 同时设置止损和止盈
result = trader.post_stop_order(
    account_id=0,
    symbol="BTC_USDT",
    pos_side="Short",
    take_profit={
        "trigger_price": {"MarkPrice": 48000.0},  # 止盈触发价
        "trigger_action": {
            "quantity": 0.01,                     # 部分止盈
            "execute_type": "Market",
            "typ": "Normal"
        }
    },
    stop_loss={
        "trigger_price": {"ContractPrice": 52000.0},  # 止损触发价
        "trigger_action": {
            "execute_type": "Market",             # 市价止损
            "typ": "Normal"
        }
    },
    is_dual_side=True
)

# ✅ 指数价格触发的止损订单
result = trader.post_stop_order(
    account_id=0,
    symbol="BTC_USDT",
    pos_side="Long",
    stop_loss={
        "trigger_price": {"IndexPrice": 49500.0},  # 指数价格触发
        "trigger_action": {
            "quantity": 0.02,                      # 指定止损数量
            "execute_type": {"Limit": 49000.0},    # 限价49000止损
            "typ": "Normal"
        }
    },
    is_dual_side=True
)

# 💡 完整的止损订单管理示例（基于实际策略代码）
def complete_stop_order_lifecycle():
    """完整的止损订单生命周期管理示例"""
    account_id = 0
    symbol = "XRP_USDT"

    print("=== 止损订单完整生命周期示例 ===")

    # 1. 检查持仓模式
    is_dual_side_result = trader.is_dual_side(account_id)
    if "Ok" not in is_dual_side_result:
        print("❌ 获取持仓模式失败")
        return

    is_dual_side = is_dual_side_result['Ok']
    print(f"📋 当前持仓模式: {'双向持仓' if is_dual_side else '单向持仓'}")

    # 2. 创建止盈止损订单
    print("\n📥 创建止盈止损订单...")
    result = trader.post_stop_order(
        account_id=account_id,
        symbol=symbol,
        pos_side="Long",  # 针对多头仓位设置止盈止损
        take_profit={
            "cid": "tp_xrp_001",              # 客户端止盈订单ID
            "trigger_price": {"MarkPrice": 3.0},  # 止盈触发价
            "trigger_action": {
                "quantity": 2,                     # 部分止盈数量
                "execute_type": "Market",          # 市价执行
                "typ": "Normal"                    # 一般止盈
            }
        },
        stop_loss={
            "cid": "sl_xrp_001",              # 客户端止损订单ID
            "trigger_price": {"ContractPrice": 2.0},  # 止损触发价
            "trigger_action": {
                "execute_type": "Market",             # 市价止损
                "typ": "Normal"                       # 一般止损
            }
        },
        is_dual_side=is_dual_side
    )

    if "Ok" not in result:
        print(f"❌ 下止盈止损订单失败: {result.get('Err')}")
        return

    order_result = result["Ok"]
    print(f"✅ 止盈止损订单下达成功:")

    # 提取订单ID
    take_profit_id = None
    stop_loss_id = None

    if order_result.get('take_profit') and "Ok" in order_result['take_profit']:
        take_profit_id = order_result['take_profit']['Ok']
        print(f"   🎯 止盈订单ID: {take_profit_id}")

    if order_result.get('stop_loss') and "Ok" in order_result['stop_loss']:
        stop_loss_id = order_result['stop_loss']['Ok']
        print(f"   🛡️ 止损订单ID: {stop_loss_id}")

    # 3. 查询并验证订单
    print("\n📊 查询止损订单...")
    result = trader.get_stop_orders(account_id, symbol)
    if "Ok" in result:
        orders = result["Ok"]
        open_orders = [order for order in orders if order['status'] == 'Open']
        print(f"   📋 当前开放的止损订单数量: {len(open_orders)}")

        # 找到我们刚才下的订单
        our_orders = []
        for order in open_orders:
            order_found = False
            if order.get('take_profit') and order['take_profit']['id'] == take_profit_id:
                order_found = True
            if order.get('stop_loss') and order['stop_loss']['id'] == stop_loss_id:
                order_found = True
            if order_found:
                our_orders.append(order)

        print(f"   ✅ 找到我们的订单: {len(our_orders)} 个")

        # 显示订单详情
        for i, order in enumerate(our_orders):
            print(f"   订单 {i+1}: 状态={order['status']}, 创建时间={order['c_time']}")
            if order.get('take_profit'):
                tp = order['take_profit']
                print(f"     止盈: 触发价={tp['trigger_price']}, 数量={tp['trigger_action'].get('quantity')}")
            if order.get('stop_loss'):
                sl = order['stop_loss']
                print(f"     止损: 触发价={sl['trigger_price']}")
    else:
        print(f"❌ 查询订单失败: {result.get('Err')}")

    # 4. 修改止盈订单（演示修改功能）
    if take_profit_id:
        print(f"\n🔧 修改止盈订单 {take_profit_id}...")
        result = trader.amend_stop_order(
            account_id=account_id,
            symbol=symbol,
            id=take_profit_id,
            take_profit={
                "trigger_price": {"MarkPrice": 3.1},  # 调整触发价格
                "trigger_action": {
                    "quantity": 3,                     # 调整数量
                    "execute_type": "Market",
                    "typ": "Normal"
                }
            }
        )

        if "Ok" in result:
            print(f"   ✅ 止盈订单修改成功: {result['Ok']}")

            # 验证修改结果
            verify_result = trader.get_stop_orders(account_id, symbol, id=take_profit_id)
            if "Ok" in verify_result and verify_result["Ok"]:
                updated_order = verify_result["Ok"][0]
                if updated_order.get('take_profit'):
                    tp = updated_order['take_profit']
                    new_trigger_price = tp['trigger_price']
                    new_quantity = tp['trigger_action'].get('quantity')
                    print(f"   📊 修改验证 - 新触发价: {new_trigger_price}, 新数量: {new_quantity}")
        else:
            print(f"   ❌ 止盈订单修改失败: {result.get('Err')}")

    # 5. 演示条件取消（这里模拟条件判断）
    print("\n🧹 清理订单...")
    should_cleanup = True  # 在实际策略中，这里会有具体的条件判断

    if should_cleanup:
        # 取消止盈订单
        if take_profit_id:
            result = trader.cancel_stop_order(account_id, symbol, id=take_profit_id)
            if "Ok" in result:
                print(f"   ✅ 止盈订单 {take_profit_id} 取消成功")
            else:
                print(f"   ❌ 止盈订单取消失败: {result.get('Err')}")

        # 取消止损订单
        if stop_loss_id:
            result = trader.cancel_stop_order(account_id, symbol, id=stop_loss_id)
            if "Ok" in result:
                print(f"   ✅ 止损订单 {stop_loss_id} 取消成功")
            else:
                print(f"   ❌ 止损订单取消失败: {result.get('Err')}")

    # 6. 最终验证
    print("\n🔍 最终验证...")
    result = trader.get_stop_orders(account_id, symbol)
    if "Ok" in result:
        orders = result["Ok"]
        open_orders = [order for order in orders if order['status'] == 'Open']
        print(f"   📋 剩余开放订单数量: {len(open_orders)}")

    print("\n✅ 止损订单完整生命周期示例完成!")

# 🚀 实际策略中的止损订单管理示例
def strategy_stop_order_management():
    """基于实际策略代码的止损订单管理"""
    account_id = 0
    symbol = "XRP_USDT"

    print("=== 策略级止损订单管理 ===")

    # 获取开放的止损订单（参考strategy.py代码）
    result = trader.get_stop_orders(account_id, symbol)
    if "Ok" in result:
        orders = result["Ok"]
        open_stop_orders = [order for order in orders if order['status'] == 'Open']

        print(f"📋 当前开放的止损订单: {len(open_stop_orders)} 个")

        # 撤销所有开放的止损订单（实际策略场景）
        for order in open_stop_orders:
            # 获取止损订单ID（优先取止损，如果没有则取止盈）
            order_id = None
            order_type = None

            if order.get('stop_loss'):
                order_id = order['stop_loss']['id']
                order_type = "止损"
            elif order.get('take_profit'):
                order_id = order['take_profit']['id']
                order_type = "止盈"

            if order_id:
                res = trader.cancel_stop_order(account_id, symbol, id=order_id)
                if 'Ok' in res:
                    print(f"   ✅ {order_type}订单 {order_id} 撤单成功")
                else:
                    print(f"   ❌ {order_type}订单 {order_id} 撤单失败: {res.get('Err')}")
    else:
        print(f"❌ 获取止损订单失败: {result.get('Err')}")

    # 设置新的风控订单
    print("\n📥 设置新的风控订单...")
    result = trader.post_stop_order(
        account_id=account_id,
        symbol=symbol,
        pos_side="Long",
        take_profit={
            "trigger_price": {"MarkPrice": 2.8},
            "trigger_action": {
                "execute_type": "Market",
                "typ": "Normal"
            }
        },
        stop_loss={
            "trigger_price": {"MarkPrice": 2.2},
            "trigger_action": {
                "execute_type": "Market",
                "typ": "Normal"
            }
        },
        is_dual_side=True
    )

    if "Ok" in result:
        print(f"✅ 新的风控订单设置成功: {result['Ok']}")
    else:
        print(f"❌ 风控订单设置失败: {result.get('Err')}")

# 调用示例函数
complete_stop_order_lifecycle()
print("\n" + "="*50 + "\n")
strategy_stop_order_management()

📊 get_stop_orders(account_id, symbol, limit=None, id=None, cid=None, extra=None, generate=False)

功能: 获取止损订单列表

参数:

• account_id: 整数，必需，账户ID
• symbol: 字符串，必需，交易对名称
• limit: 整数，可选，返回订单数量限制
• id: 字符串，可选，特定订单ID，用于查询指定订单
• cid: 字符串，可选，客户端订单ID，用于查询指定订单
• extra: 字典，可选，额外参数
• generate: 布尔值，可选，默认为False，设为True时只生成命令而不执行

重要:

• 此方法仅支持同步执行，无 sync 参数
• 必需参数: account_id、symbol 两个参数为必需
• 查询模式: 如果不提供id或cid，则返回所有止损订单；如果提供其中一个，则返回指定订单

返回值:

• Result结构: 包含Ok或Err字段的字典
• 示例:

{
  "Ok": [
    {
      "c_time": 1751955325429,
      "status": "Open",
      "stop_loss": {
        "cid": "1326362257261215744",
        "id": "1326362257269604352",
        "trigger_action": {
          "execute_type": "Market",
          "quantity": null,
          "trailing_gap": null,
          "typ": "Normal"
        },
        "trigger_price": {
          "ContractPrice": 2.0
        }
      },
      "symbol": "XRP_USDT",
      "take_profit": null,
      "u_time": 1751955325429
    },
    {
      "c_time": 1751954797851,
      "status": "Canceled",
      "stop_loss": {
        "cid": "1326360044434505728",
        "id": "1326360044447088640",
        "trigger_action": {
          "execute_type": "Market",
          "quantity": null,
          "trailing_gap": null,
          "typ": "Normal"
        },
        "trigger_price": {
          "ContractPrice": 2.0
        }
      },
      "symbol": "XRP_USDT",
      "take_profit": null,
      "u_time": 1751955183197
    },
  ]
}

示例:

# 获取BTC_USDT的所有止损订单
result = trader.get_stop_orders(
    account_id=0,
    symbol="BTC_USDT"
)

if "Ok" in result:
    stop_orders = result["Ok"]
    print(f"止损订单数量: {len(stop_orders)}")

    for order in stop_orders:
        symbol = order.get('symbol')
        status = order.get('status')
        create_time = order.get('c_time')

        # 检查止盈订单
        if order.get('take_profit'):
            tp = order['take_profit']
            tp_id = tp.get('id')
            tp_price = tp['trigger_price']
            print(f"止盈订单 - ID: {tp_id}, 触发价: {tp_price}, 状态: {status}")

        # 检查止损订单
        if order.get('stop_loss'):
            sl = order['stop_loss']
            sl_id = sl.get('id')
            sl_price = sl['trigger_price']
            print(f"止损订单 - ID: {sl_id}, 触发价: {sl_price}, 状态: {status}")
else:
    error = result.get("Err", "未知错误")
    print(f"获取止损订单失败: {error}")

# 通过订单ID获取特定订单
result = trader.get_stop_orders(
    account_id=0,
    symbol="BTC_USDT",
    id="1326362257269604352"  # 具体的订单ID
)

if "Ok" in result:
    orders = result["Ok"]
    if orders:
        print(f"找到订单: {orders[0]}")
    else:
        print("订单不存在")

# 通过客户端订单ID获取特定订单
result = trader.get_stop_orders(
    account_id=0,
    symbol="BTC_USDT",
    cid="client_stop_order_001"  # 客户端自定义ID
)

# 限制返回数量（获取最近10个止损订单）
result = trader.get_stop_orders(
    account_id=0,
    symbol="BTC_USDT",
    limit=10
)

if "Ok" in result:
    recent_orders = result["Ok"]
    print(f"最近{len(recent_orders)}个止损订单")

    # 分析订单状态分布
    status_count = {}
    for order in recent_orders:
        status = order.get('status', 'Unknown')
        status_count[status] = status_count.get(status, 0) + 1

    print(f"订单状态分布: {status_count}")

📊 amend_stop_order(account_id, symbol, id=None, cid=None, take_profit=None, stop_loss=None, extra=None, generate=False)

功能: 修改止损订单

参数:

• account_id: 整数，必需，账户ID
• symbol: 字符串，必需，交易对名称
• id: 字符串，可选，要修改的订单ID
• cid: 字符串，可选，要修改的客户端订单ID
• take_profit: 字典，可选，新的止盈订单配置（CloseTrigger结构），包含以下字段：
  • cid: 字符串，可选，客户自定义订单ID
  • trigger_price: 字典，触发价格配置，支持以下类型：
    • {"MarkPrice": 价格}: 标记价格触发
    • {"ContractPrice": 价格}: 最新成交价/市场价触发
    • {"IndexPrice": 价格}: 指数价格触发
  • trigger_action: 字典，触发行为配置，包含：
    • quantity: 浮点数，可选，触发数量，不填则全平
    • trailing_gap: 浮点数，可选，回调幅度(%)，追踪止盈时必填
    • execute_type: 字符串或字典，执行类型：
      • "Market": 市价平仓
      • {"Limit": 价格}: 限价平仓
    • typ: 字符串，可选，类型："Normal"(一般)或"Trailing"(追踪)，默认"Normal"
• stop_loss: 字典，可选，新的止损订单配置（CloseTrigger结构），字段同take_profit
• extra: 字典，可选，额外参数
• generate: 布尔值，可选，默认为False，设为True时只生成命令而不执行

重要:

• 此方法仅支持同步执行，无 sync 参数
• 必需参数: account_id、symbol 为必需参数
• 订单标识: id 和 cid 不能同时为空，必须提供其中一个用于标识要修改的订单
• 修改内容: take_profit 和 stop_loss 至少需要提供其中一个要修改的配置，否则修改操作无意义

返回值:

• Result结构: 包含Ok或Err字段的字典
• 示例:

{
  "Ok": {
    "stop_loss": {
      "Ok": "1326362257269604352"
    },
    "take_profit": {
      "Ok": "1326362256586391552"
    }
  }
}

示例:

# 首先获取现有的止损订单
result = trader.get_stop_orders(0, "BTC_USDT")
if "Ok" in result and result["Ok"]:
    stop_orders = result["Ok"]
    # 找到一个开放状态的订单
    open_orders = [order for order in stop_orders if order['status'] == 'Open']

    if open_orders:
        # 获取第一个开放订单的止损部分ID
        stop_loss_id = None
        if open_orders[0].get('stop_loss'):
            stop_loss_id = open_orders[0]['stop_loss']['id']

        if stop_loss_id:
            # 修改止损订单的触发价格 - 通过订单ID
            result = trader.amend_stop_order(
                account_id=0,
                symbol="BTC_USDT",
                id=stop_loss_id,  # 使用id参数
                stop_loss={
                    "trigger_price": {"MarkPrice": 48500.0},  # 修改为标记价格触发
                    "trigger_action": {
                        "execute_type": "Market",             # 市价执行
                        "typ": "Normal"
                    }
                }
            )

            if "Ok" in result:
                amend_result = result["Ok"]
                print(f"止损订单修改成功: {amend_result}")
            else:
                error = result.get("Err", "未知错误")
                print(f"止损订单修改失败: {error}")

# 通过客户端订单ID修改止盈订单为追踪止盈
result = trader.amend_stop_order(
    account_id=0,
    symbol="ETH_USDT",
    cid="client_tp_001",  # 使用客户端订单ID
    take_profit={
        "trigger_price": {"ContractPrice": 3600.0},  # 合约价格触发
        "trigger_action": {
            "quantity": 0.8,                         # 数量
            "trailing_gap": 1.5,                     # 回调1.5%
            "execute_type": "Market",
            "typ": "Trailing"                        # 改为追踪止盈
        }
    }
)

if "Ok" in result:
    print(f"追踪止盈修改成功: {result['Ok']}")
else:
    print(f"追踪止盈修改失败: {result.get('Err', '未知错误')}")

# 同时修改止盈和止损
result = trader.amend_stop_order(
    account_id=0,
    symbol="SOL_USDT",
    id="1326362257269604352",  # 止损订单ID
    take_profit={
        "trigger_price": {"MarkPrice": 120.0},
        "trigger_action": {
            "quantity": 1.0,
            "execute_type": {"Limit": 119.5},  # 限价执行
            "typ": "Normal"
        }
    },
    stop_loss={
        "trigger_price": {"MarkPrice": 95.0},
        "trigger_action": {
            "execute_type": "Market",
            "typ": "Normal"
        }
    }
)

if "Ok" in result:
    amend_result = result["Ok"]
    # 检查修改结果
    if amend_result.get('take_profit') and "Ok" in amend_result['take_profit']:
        print(f"止盈修改成功，订单ID: {amend_result['take_profit']['Ok']}")
    if amend_result.get('stop_loss') and "Ok" in amend_result['stop_loss']:
        print(f"止损修改成功，订单ID: {amend_result['stop_loss']['Ok']}")
else:
    print(f"修改失败: {result.get('Err', '未知错误')}")

# 完整的修改流程示例
def modify_stop_order_example():
    symbol = "BTC_USDT"
    account_id = 0

    # 1. 查询现有订单
    result = trader.get_stop_orders(account_id, symbol)
    if "Ok" not in result:
        print("获取止损订单失败")
        return

    orders = result["Ok"]
    open_orders = [order for order in orders if order['status'] == 'Open']

    if not open_orders:
        print("没有找到开放状态的止损订单")
        return

    # 2. 选择要修改的订单
    target_order = open_orders[0]

    # 3. 根据订单类型进行修改
    if target_order.get('take_profit'):
        tp_id = target_order['take_profit']['id']
        print(f"修改止盈订单: {tp_id}")

        # 修改止盈触发价格
        result = trader.amend_stop_order(
            account_id=account_id,
            symbol=symbol,
            id=tp_id,
            take_profit={
                "trigger_price": {"MarkPrice": 52000.0},  # 新的触发价格
                "trigger_action": {
                    "quantity": 0.05,  # 新的数量
                    "execute_type": "Market",
                    "typ": "Normal"
                }
            }
        )

        if "Ok" in result:
            print(f"止盈修改成功: {result['Ok']}")
        else:
            print(f"止盈修改失败: {result.get('Err')}")

    if target_order.get('stop_loss'):
        sl_id = target_order['stop_loss']['id']
        print(f"修改止损订单: {sl_id}")

        # 修改止损触发价格
        result = trader.amend_stop_order(
            account_id=account_id,
            symbol=symbol,
            id=sl_id,
            stop_loss={
                "trigger_price": {"ContractPrice": 47000.0},  # 新的触发价格
                "trigger_action": {
                    "execute_type": "Market",
                    "typ": "Normal"
                }
            }
        )

        if "Ok" in result:
            print(f"止损修改成功: {result['Ok']}")
        else:
            print(f"止损修改失败: {result.get('Err')}")

# 调用示例函数
modify_stop_order_example()

📊 cancel_stop_order(account_id, symbol, id=None, cid=None, extra=None, generate=False)

功能: 取消止损订单

参数:

• account_id: 整数，必需，账户ID
• symbol: 字符串，必需，交易对名称
• id: 字符串，可选，订单ID
• cid: 字符串，可选，客户端订单ID
• extra: 字典，可选，额外参数
• generate: 布尔值，可选，默认为False，设为True时只生成命令而不执行

重要:

• 此方法仅支持同步执行，无 sync 参数
• 必需参数: account_id、symbol 两个参数为必需
• 标识参数: id 和 cid 不能同时为空，必须提供其中一个用于标识要取消的订单

返回值:

• 成功时返回 None（取消成功无返回值）
• 失败时返回错误信息

示例:

# 通过订单ID取消止损订单
result = trader.cancel_stop_order(
    account_id=0,
    symbol="BTC_USDT",
    id="1326362257269604352"  # 具体的止损订单ID
)

if "Ok" in result:
    cancel_result = result["Ok"]
    print(f"止损订单取消成功: {cancel_result}")
else:
    error = result.get("Err", "未知错误")
    print(f"止损订单取消失败: {error}")

# 通过客户端订单ID取消
result = trader.cancel_stop_order(
    account_id=0,
    symbol="BTC_USDT",
    cid="my_stop_order_001"  # 客户端自定义ID
)

if "Ok" in result:
    print(f"止损订单取消成功: {result['Ok']}")
else:
    print(f"止损订单取消失败: {result.get('Err', '未知错误')}")

# 批量取消止损订单示例
def cancel_all_open_stop_orders(account_id, symbol):
    """取消指定交易对的所有开放止损订单"""
    # 1. 获取所有开放状态的止损订单
    result = trader.get_stop_orders(account_id, symbol)
    if "Ok" not in result:
        print(f"获取{symbol}止损订单失败: {result.get('Err')}")
        return

    orders = result["Ok"]
    open_orders = [order for order in orders if order['status'] == 'Open']

    if not open_orders:
        print(f"{symbol}没有开放状态的止损订单")
        return

    print(f"找到{len(open_orders)}个开放的止损订单，开始批量取消...")

    # 2. 逐个取消订单
    success_count = 0
    failed_count = 0

    for order in open_orders:
        # 取消止盈订单
        if order.get('take_profit'):
            tp_id = order['take_profit']['id']
            result = trader.cancel_stop_order(account_id, symbol, id=tp_id)

            if "Ok" in result:
                print(f"✅ 止盈订单 {tp_id} 取消成功")
                success_count += 1
            else:
                print(f"❌ 止盈订单 {tp_id} 取消失败: {result.get('Err')}")
                failed_count += 1

        # 取消止损订单
        if order.get('stop_loss'):
            sl_id = order['stop_loss']['id']
            result = trader.cancel_stop_order(account_id, symbol, id=sl_id)

            if "Ok" in result:
                print(f"✅ 止损订单 {sl_id} 取消成功")
                success_count += 1
            else:
                print(f"❌ 止损订单 {sl_id} 取消失败: {result.get('Err')}")
                failed_count += 1

    print(f"批量取消完成: 成功 {success_count} 个, 失败 {failed_count} 个")

# 调用批量取消函数
cancel_all_open_stop_orders(0, "BTC_USDT")

# 根据条件取消止损订单
def cancel_stop_orders_by_condition():
    """根据特定条件取消止损订单"""
    symbol = "ETH_USDT"
    account_id = 0

    # 获取所有止损订单
    result = trader.get_stop_orders(account_id, symbol)
    if "Ok" not in result:
        return

    orders = result["Ok"]

    for order in orders:
        if order['status'] != 'Open':
            continue  # 跳过非开放状态的订单

        # 示例条件：取消所有标记价格触发价格低于3000的止盈订单
        if order.get('take_profit'):
            tp = order['take_profit']
            trigger_price = tp['trigger_price']

            # 检查是否是标记价格触发且价格低于3000
            if ('MarkPrice' in trigger_price and
                trigger_price['MarkPrice'] < 3000):

                tp_id = tp['id']
                result = trader.cancel_stop_order(account_id, symbol, id=tp_id)

                if "Ok" in result:
                    print(f"取消低价止盈订单: {tp_id} (触发价: {trigger_price['MarkPrice']})")
                else:
                    print(f"取消订单失败: {tp_id}")

# 使用示例策略中的代码片段
def example_from_strategy():
    """基于策略代码的实际使用示例"""
    account_id = 0
    symbol = "XRP_USDT"

    # 获取开放的止损订单
    result = trader.get_stop_orders(account_id, symbol)
    if "Ok" in result:
        orders = result["Ok"]
        open_stop_orders = [order for order in orders if order['status'] == 'Open']

        # 撤销所有开放的止损订单
        for order in open_stop_orders:
            # 获取止损订单ID（优先取止损，如果没有则取止盈）
            order_id = None
            if order.get('stop_loss'):
                order_id = order['stop_loss']['id']
            elif order.get('take_profit'):
                order_id = order['take_profit']['id']

            if order_id:
                res = trader.cancel_stop_order(account_id, symbol, id=order_id)
                if 'Ok' in res:
                    print(f"撤单成功: {order_id}")
                else:
                    print(f"撤单失败: {order_id}, 错误: {res.get('Err')}")

# 调用示例函数
example_from_strategy()

止损订单使用最佳实践:

1. 风险管理: 建议为每个开仓都设置对应的止损订单，控制单笔交易最大亏损

2. 触发价格类型选择:

   • MarkPrice: 标记价格触发，适用于大多数场景，可避免市场价格异常波动误触发
   • ContractPrice: 最新成交价触发，响应最快，适合高频交易
   • IndexPrice: 指数价格触发，最稳定，适合长期持仓

3. 执行类型策略:

   • Market: 市价执行，确保能够成交，但可能有滑点
   • Limit: 限价执行，控制成交价格，但可能无法成交

4. 追踪止盈的使用:

   • 设置合理的trailing_gap回调幅度，通常1-3%
   • 追踪止盈适用于趋势明确的单边行情
   • 震荡行情建议使用一般止盈避免频繁触发

5. 数量设置:

   • 不设置quantity将全平持仓
   • 部分止盈可设置具体数量，实现分批平仓策略

6. 仓位方向: 必须正确设置pos_side参数，与要保护的仓位方向一致

7. 双向持仓: 在双向持仓模式下，is_dual_side应设置为True

8. 持续监控: 定期检查止损订单状态，根据市场变化及时调整

9. 参数要求: 严格按照必需参数要求传递参数

   • post_stop_order: account_id、symbol、pos_side 为必需
   • get_stop_orders: account_id、symbol 为必需
   • amend_stop_order: account_id、symbol 为必需，id或cid二选一
   • cancel_stop_order: account_id、symbol 为必需，id或cid二选一

10. 同步执行: 所有止损订单操作都是同步执行，无 sync 参数，确保操作的即时性和可靠性

7.2 基础请求

🌐 request(account_id, method, path, auth, query=None, body=None, url=None, headers=None, generate=False)

功能: 向交易所发送原始API请求

参数:

• account_id: 整数，账户ID
• method: 字符串，HTTP方法(GET, POST等)
• path: 字符串，API路径
• auth: 布尔值，是否需要验证
• query: 字典，可选，URL查询参数
• body: 任意类型，可选，请求体数据。可以是Python字典、列表或任何可序列化的Python对象，会自动转换为JSON字符串
• url: 字符串，可选，完整URL(设置时会覆盖默认URL)
• headers: 字典，可选，HTTP头信息
• generate: 布尔值，可选，默认为False，设为True时只生成命令而不执行

返回值:

• Result结构: 包含Ok或Err字段的字典
• 成功时: {"Ok": response_data} - 交易所API返回的响应数据已转换为Python对象
• 失败时: {"Err": error_info} - 包含错误信息

示例:

# ✅ GET请求示例 - 获取OKX市场行情数据
query_params = {"instId": "BTC-USD-SWAP"}
result = trader.request(
    account_id=0,
    method="GET",
    path="/api/v5/market/ticker",
    auth=False,  # 公开接口不需要认证
    query=query_params,
    body=None,
    url=None,
    headers=None,
    generate=False
)

if "Ok" in result:
    ticker_data = result["Ok"]
    print(f"BTC-USD-SWAP行情数据: {ticker_data}")
else:
    error = result.get("Err", "未知错误")
    print(f"获取OKX行情失败: {error}")

重要说明:

• 自动序列化: body参数支持Python字典、列表等可序列化对象，会在Rust端自动转换为JSON字符串
• URL覆盖: 设置url参数时会覆盖交易所的默认API基础URL，用于调用其他服务的API
• 认证处理: auth=True时会自动添加交易所要求的签名和认证头
• Result处理: 所有返回值都需要检查Ok字段来确定是否成功
• 命令生成: generate=True时只生成命令对象，不立即执行，用于批量操作

7.3 持仓与账户

📊 get_position(account_id, symbol, extra=None, generate=False)

功能: 获取指定交易对的持仓信息

参数:

• account_id: 整数，账户ID
• symbol: 字符串，交易对名称
• extra: 字典，可选，额外参数
• generate: 布尔值，可选，默认为False，设为True时只生成命令而不执行

返回值:

• Result结构: 包含Ok或Err字段的字典
• 成功时: {"Ok": position_data} - 持仓信息数据，如果无持仓返回None
• 失败时: {"Err": error_info} - 包含错误信息
• 数据结构: 参见7.2 Position（持仓）数据结构

📊 get_positions(account_id, extra=None, generate=False)

功能: 获取账户下所有持仓信息

参数:

• account_id: 整数，账户ID
• extra: 字典，可选，额外参数
• generate: 布尔值，可选，默认为False，设为True时只生成命令而不执行

返回值:

• Result结构: 包含Ok或Err字段的字典
• 成功时: {"Ok": positions_list} - 持仓信息列表，如果无持仓返回空列表
• 失败时: {"Err": error_info} - 包含错误信息
• 数据结构: 列表中每个元素的结构参见7.2 Position（持仓）数据结构

📊 get_max_position(account_id, symbol, level=None, extra=None, generate=False)

功能: 获取交易对的最大可开仓数量

参数:

• account_id: 整数，账户ID
• symbol: 字符串，交易对名称
• level: 浮点数，可选，杠杆倍数
• extra: 字典，可选，额外参数
• generate: 布尔值，可选，默认为False，设为True时只生成命令而不执行

返回值:

{
    "long_notional": 1000.0,
    "short_notional": 1000.0,
    "long_quantity": 0.001,
    "short_quantity": 0.001
}

• 最大可开仓数量数据字典，包含:
  • long_notional: 浮点数，多仓对应Quote名义价值
  • short_notional: 浮点数，空仓对应Quote名义价值
  • long_quantity: 浮点数，多仓对应Base数量
  • short_quantity: 浮点数，空仓对应Base数量

示例:

# 查询BTC_USDT的最大可开仓数量
result = trader.get_max_position(
    account_id=0,
    symbol="BTC_USDT"
)

if "Ok" in result:
    max_position = result["Ok"]
    print(f"最大可开仓数量: {max_position}")
    print(f"多仓最大名义价值: {max_position['long_notional']} USDT")
    print(f"空仓最大名义价值: {max_position['short_notional']} USDT")
    print(f"多仓最大数量: {max_position['long_quantity']} BTC")
    print(f"空仓最大数量: {max_position['short_quantity']} BTC")
else:
    error = result.get("Err", "未知错误")
    print(f"查询最大可开仓数量失败: {error}")

# 指定杠杆倍数查询
result = trader.get_max_position(
    account_id=0,
    symbol="BTC_USDT",
    level=5.0  # 5倍杠杆
)

if "Ok" in result:
    max_position_5x = result["Ok"]
    print(f"5倍杠杆下最大可开仓: {max_position_5x}")
else:
    error = result.get("Err", "未知错误")
    print(f"查询5倍杠杆最大可开仓失败: {error}")

# 使用publish方法调用
cmd = {
    "account_id": 0,
    "method": "GetMaxPosition",
    "symbol": "BTC_USDT",
    "level": 3.0,
    "sync": True
}
result = trader.publish(cmd)
print(f"最大可开仓结果: {result}")

💰 get_usdt_balance(account_id, extra=None, generate=False)

功能: 获取账户USDT余额

参数:

• account_id: 整数，账户ID
• extra: 字典，可选，额外参数
• generate: 布尔值，可选，默认为False，设为True时只生成命令而不执行

返回值:

• USDT余额数据字典，包含:
  • asset: 字符串，资产名称（"USDT"）
  • balance: 浮点数，总余额+浮动盈亏
  • available_balance: 浮点数，可用余额
  • unrealized_pnl: 浮点数，浮动盈亏

💰 get_balances(account_id, extra=None, generate=False)

功能: 获取账户所有币种余额

参数:

• account_id: 整数，账户ID
• extra: 字典，可选，额外参数
• generate: 布尔值，可选，默认为False，设为True时只生成命令而不执行

返回值:

• 所有币种余额数据列表，每个元素为字典，包含:
  • asset: 字符串，资产名称（如"USDT", "BTC"等）
  • balance: 浮点数，总余额+浮动盈亏
  • available_balance: 浮点数，可用余额
  • unrealized_pnl: 浮点数，浮动盈亏

💰 get_balance_by_coin(account_id, asset, extra=None, generate=False)

功能: 获取指定币种的余额

参数:

• account_id: 整数，账户ID
• asset: 字符串，币种名称
• extra: 字典，可选，额外参数
• generate: 布尔值，可选，默认为False，设为True时只生成命令而不执行

返回值:

• 指定币种余额数据字典，包含:
  • asset: 字符串，资产名称（与请求的asset相同）
  • balance: 浮点数，总余额+浮动盈亏
  • available_balance: 浮点数，可用余额
  • unrealized_pnl: 浮点数，浮动盈亏

💰 get_fee_rate(account_id, symbol, extra=None, generate=False)

功能: 获取交易对的手续费率

参数:

• account_id: 整数，账户ID
• symbol: 字符串，交易对名称
• extra: 字典，可选，额外参数
• generate: 布尔值，可选，默认为False，设为True时只生成命令而不执行

返回值:

• 手续费率数据字典（FeeRate结构），包含:
  • taker: 浮点数，taker手续费率（吃单成交，如0.0004表示0.04%）
  • maker: 浮点数，maker手续费率（挂单成交，如0.0002表示0.02%）
  • buyer: 浮点数，买方附加费率（吃买单费率 = taker + buyer）
  • seller: 浮点数，卖方附加费率（吃卖单费率 = taker + seller）

示例:

# 获取 BTC_USDT 的手续费率
result = trader.get_fee_rate(0, "BTC_USDT")

if "Ok" in result:
    fee = result["Ok"]
    print(f"Taker费率: {fee['taker']*100:.4f}%")
    print(f"Maker费率: {fee['maker']*100:.4f}%")
    print(f"买方附加: {fee['buyer']*100:.4f}%")
    print(f"卖方附加: {fee['seller']*100:.4f}%")

    # 计算实际费率
    buy_taker_fee = fee['taker'] + fee['buyer']
    sell_taker_fee = fee['taker'] + fee['seller']
    print(f"吃买单实际费率: {buy_taker_fee*100:.4f}%")
    print(f"吃卖单实际费率: {sell_taker_fee*100:.4f}%")
else:
    print(f"获取手续费率失败: {result.get('Err', '未知错误')}")

💰 get_fee_discount_info(account_id, extra=None, generate=False)

功能: 获取费用折扣信息

参数:

• account_id: 整数，账户ID
• extra: 字典，可选，额外参数
• generate: 布尔值，可选，默认为False，设为True时只生成命令而不执行

返回值:

• 费用折扣信息数据字典，包含:
  • enabled: 布尔值，费用折扣是否启用
  • discount_rate: 浮点数，可选，当前折扣率
  • vip_level: 整数，可选，VIP等级

💰 is_fee_discount_enabled(account_id, extra=None, generate=False)

功能: 检查费用折扣是否已启用

参数:

• account_id: 整数，账户ID
• extra: 字典，可选，额外参数
• generate: 布尔值，可选，默认为False，设为True时只生成命令而不执行

返回值:

• 布尔值，表示费用折扣是否已启用

💰 set_fee_discount_enabled(account_id, enabled, extra=None, generate=False)

功能: 设置费用折扣启用状态

参数:

• account_id: 整数，账户ID
• enabled: 布尔值，是否启用费用折扣
• extra: 字典，可选，额外参数
• generate: 布尔值，可选，默认为False，设为True时只生成命令而不执行

返回值:

• 成功时返回 None（设置成功无返回值）
• 失败时返回错误信息

7.4 市场数据

📈 get_ticker(account_id, symbol, extra=None, generate=False)

功能: 获取指定交易对的24小时行情数据

参数:

• account_id: 整数，账户ID
• symbol: 字符串，交易对名称
• extra: 字典，可选，额外参数
• generate: 布尔值，可选，默认为False，设为True时只生成命令而不执行

返回值:

• 交易对行情数据字典（Ticker结构），包含:
  • symbol: 字符串，交易对符号
  • timestamp: 整数，数据时间戳（毫秒）
  • high: 浮点数，24小时最高价
  • low: 浮点数，24小时最低价
  • open: 浮点数，24小时开盘价
  • close: 浮点数，24小时收盘价（最新价）
  • volume: 浮点数，24小时成交量（基础货币）
  • quote_volume: 浮点数，24小时成交额（报价货币）
  • change: 浮点数，24小时价格变动
  • change_percent: 浮点数，24小时价格变动百分比

示例:

# 获取 BTC_USDT 的行情数据
result = trader.get_ticker(0, "BTC_USDT")

if "Ok" in result:
    ticker = result["Ok"]
    print(f"交易对: {ticker['symbol']}")
    print(f"最新价: {ticker['close']}")
    print(f"24h开盘价: {ticker['open']}")
    print(f"24h最高: {ticker['high']}")
    print(f"24h最低: {ticker['low']}")
    print(f"24h涨跌: {ticker['change']}")
    print(f"24h涨跌幅: {ticker['change_percent']:.2f}%")
    print(f"24h成交量: {ticker['volume']}")
    print(f"24h成交额: {ticker['quote_volume']}")
else:
    print(f"获取行情失败: {result.get('Err', '未知错误')}")

📈 get_tickers(account_id, extra=None, generate=False)

功能: 获取所有交易对的24小时行情数据

参数:

• account_id: 整数，账户ID
• extra: 字典，可选，额外参数
• generate: 布尔值，可选，默认为False，设为True时只生成命令而不执行

返回值:

• 所有交易对行情数据列表，每个元素为Ticker字典（结构同get_ticker返回值）

示例:

# 获取所有交易对的行情
result = trader.get_tickers(0)

if "Ok" in result:
    tickers = result["Ok"]
    print(f"共获取 {len(tickers)} 个交易对行情")

    # 筛选涨幅前5的交易对
    sorted_tickers = sorted(tickers, key=lambda x: x.get('change_percent', 0), reverse=True)
    print("\n涨幅前5:")
    for ticker in sorted_tickers[:5]:
        print(f"  {ticker['symbol']}: {ticker['change_percent']:.2f}%")
else:
    print(f"获取行情失败: {result.get('Err', '未知错误')}")

📉 get_bbo(account_id, symbol, extra=None, generate=False)

功能: 获取交易对的最优买卖报价(Best Bid & Offer)

参数:

• account_id: 整数，账户ID
• symbol: 字符串，交易对名称
• extra: 字典，可选，额外参数
• generate: 布尔值，可选，默认为False，设为True时只生成命令而不执行

返回值:

• 最优买卖报价数据字典（BboTicker结构），包含:
  • symbol: 字符串，交易对符号
  • bid_price: 浮点数，买一价（最高买价）
  • bid_qty: 浮点数，买一量
  • ask_price: 浮点数，卖一价（最低卖价）
  • ask_qty: 浮点数，卖一量
  • timestamp: 整数，数据时间戳（毫秒）

示例:

# 获取 BTC_USDT 的最优买卖价
result = trader.get_bbo(0, "BTC_USDT")

if "Ok" in result:
    bbo = result["Ok"]
    bid = bbo['bid_price']
    ask = bbo['ask_price']
    spread = ask - bid
    spread_bps = (spread / bid) * 10000  # 基点

    print(f"交易对: {bbo['symbol']}")
    print(f"买一价: {bid}")
    print(f"卖一价: {ask}")
    print(f"价差: {spread:.4f} ({spread_bps:.2f} bps)")

    # 计算中间价
    mid_price = (bid + ask) / 2
    print(f"中间价: {mid_price:.4f}")
else:
    print(f"获取BBO失败: {result.get('Err', '未知错误')}")

📉 get_bbo_tickers(account_id, extra=None, generate=False)

功能: 获取所有交易对的最优买卖报价

参数:

• account_id: 整数，账户ID
• extra: 字典，可选，额外参数
• generate: 布尔值，可选，默认为False，设为True时只生成命令而不执行

返回值:

• 所有交易对最优买卖报价数据列表，每个元素为BBO字典（结构同get_bbo返回值）

示例:

# 获取所有交易对的BBO
result = trader.get_bbo_tickers(0)

if "Ok" in result:
    bbos = result["Ok"]
    print(f"共获取 {len(bbos)} 个交易对BBO")

    # 分析价差最小的交易对（流动性最好）
    valid_bbos = [b for b in bbos if b['bid_price'] > 0 and b['ask_price'] > 0]
    for bbo in valid_bbos:
        bbo['spread_bps'] = (bbo['ask_price'] - bbo['bid_price']) / bbo['bid_price'] * 10000

    sorted_bbos = sorted(valid_bbos, key=lambda x: x['spread_bps'])
    print("\n价差最小的5个交易对（流动性最好）:")
    for bbo in sorted_bbos[:5]:
        print(f"  {bbo['symbol']}: {bbo['spread_bps']:.2f} bps")
else:
    print(f"获取BBO失败: {result.get('Err', '未知错误')}")

📊 get_depth(account_id, symbol, limit=None, extra=None, generate=False)

功能: 获取交易对的深度数据(订单簿)

参数:

• account_id: 整数，账户ID
• symbol: 字符串，交易对名称
• limit: 整数，可选，深度条数限制（默认返回全部档位）
• extra: 字典，可选，额外参数
• generate: 布尔值，可选，默认为False，设为True时只生成命令而不执行

返回值:

• 深度数据字典，包含:
  • symbol: 字符串，交易对符号
  • timestamp: 整数，数据时间戳（毫秒）
  • bids: 列表，买盘挂单，每个元素为[price, quantity]，按价格从高到低排序
  • asks: 列表，卖盘挂单，每个元素为[price, quantity]，按价格从低到高排序

示例:

# 获取 BTC_USDT 的深度数据（前10档）
result = trader.get_depth(0, "BTC_USDT", limit=10)

if "Ok" in result:
    depth = result["Ok"]
    print(f"交易对: {depth['symbol']}")
    print(f"时间戳: {depth['timestamp']}")

    # 打印买盘前5档
    print("\n买盘（前5档）:")
    for i, (price, qty) in enumerate(depth['bids'][:5]):
        print(f"  {i+1}. 价格: {price}, 数量: {qty}")

    # 打印卖盘前5档
    print("\n卖盘（前5档）:")
    for i, (price, qty) in enumerate(depth['asks'][:5]):
        print(f"  {i+1}. 价格: {price}, 数量: {qty}")

    # 计算买卖盘深度
    bid_depth = sum(price * qty for price, qty in depth['bids'])
    ask_depth = sum(price * qty for price, qty in depth['asks'])
    print(f"\n买盘总深度: {bid_depth:.2f} USDT")
    print(f"卖盘总深度: {ask_depth:.2f} USDT")

    # 计算不平衡比例
    total_depth = bid_depth + ask_depth
    if total_depth > 0:
        imbalance = (bid_depth - ask_depth) / total_depth
        print(f"深度不平衡: {imbalance:.4f} ({'买盘压力' if imbalance > 0 else '卖盘压力'})")
else:
    print(f"获取深度失败: {result.get('Err', '未知错误')}")

📊 get_instrument(account_id, symbol, extra=None, generate=False)

功能: 获取交易对的详细信息

参数:

• account_id: 整数，账户ID
• symbol: 字符串，交易对名称
• extra: 字典，可选，额外参数
• generate: 布尔值，可选，默认为False，设为True时只生成命令而不执行

返回值:

• 交易对详细信息字典（Instrument结构），包含:
  • symbol: 字符串，交易对符号
  • state: 字符串，交易对状态，可选值：
    • "Normal": 正常交易
    • "Maintenance": 交易所维护
    • "LimitOpen": 限制开仓
    • "Close": 关闭交易
  • price_tick: 浮点数，价格最小变动单位（价格步长）
  • amount_tick: 浮点数，数量最小变动单位（数量步长）
  • price_precision: 整数，价格小数位数
  • amount_precision: 整数，数量小数位数
  • min_qty: 浮点数，最小下单数量
  • min_notional: 浮点数，最小名义价值（下单价格×数量必须大于此值）
  • price_multiplier: 浮点数，价格乘数（策略计算价格转下单价格时需乘上）
  • amount_multiplier: 浮点数，数量乘数（策略计算数量转下单数量时需乘上）
  • max_order_value: 字典，可选，单笔限额信息，包含：
    • max_limit_notional: 浮点数，单笔限价单最大名义价值
    • max_market_notinal: 浮点数，单笔市价单最大名义价值
  • permissions: 列表，支持的操作权限，可选值："Web", "Api", "Rpi"

示例:

# 获取 BTC_USDT 的交易对信息
result = trader.get_instrument(0, "BTC_USDT")

if "Ok" in result:
    inst = result["Ok"]
    print(f"交易对: {inst['symbol']}")
    print(f"交易状态: {inst['state']}")
    print(f"价格精度: {inst['price_precision']} 位")
    print(f"数量精度: {inst['amount_precision']} 位")
    print(f"价格步长: {inst['price_tick']}")
    print(f"数量步长: {inst['amount_tick']}")
    print(f"最小下单数量: {inst['min_qty']}")
    print(f"最小名义价值: {inst['min_notional']}")
    print(f"价格乘数: {inst['price_multiplier']}")
    print(f"数量乘数: {inst['amount_multiplier']}")

    # 检查是否可交易
    if inst['state'] == 'Normal':
        print("交易对状态正常，可以交易")
    else:
        print(f"交易对状态异常: {inst['state']}")
else:
    print(f"获取交易对信息失败: {result.get('Err', '未知错误')}")

📊 get_instruments(account_id, extra=None, generate=False)

功能: 获取所有可交易的交易对信息

参数:

• account_id: 整数，账户ID
• extra: 字典，可选，额外参数
• generate: 布尔值，可选，默认为False，设为True时只生成命令而不执行

返回值:

• 所有交易对信息列表，每个元素为Instrument字典（结构同get_instrument返回值）

示例:

# 获取所有交易对信息
result = trader.get_instruments(0)

if "Ok" in result:
    instruments = result["Ok"]
    print(f"共有 {len(instruments)} 个交易对")

    # 筛选正常交易状态的交易对
    active_instruments = [inst for inst in instruments if inst.get('state') == 'Normal']
    print(f"活跃交易对: {len(active_instruments)} 个")

    # 筛选USDT计价的交易对
    usdt_pairs = [inst for inst in active_instruments if inst.get('quote_asset') == 'USDT']
    print(f"USDT交易对: {len(usdt_pairs)} 个")

    # 打印前5个交易对
    print("\n前5个交易对:")
    for inst in instruments[:5]:
        print(f"  {inst['symbol']}: 价格精度={inst['price_precision']}, 数量精度={inst['amount_precision']}")
else:
    print(f"获取交易对列表失败: {result.get('Err', '未知错误')}")

📊 get_mark_price(account_id, symbol=None, extra=None, generate=False)

功能: 获取标记价格

参数:

• account_id: 整数，账户ID
• symbol: 字符串，可选，交易对名称，不指定则获取所有交易对
• extra: 字典，可选，额外参数
• generate: 布尔值，可选，默认为False，设为True时只生成命令而不执行

返回值:

• 标记价格数据列表（MarkPrice结构），每个元素为字典，包含:
  • symbol: 字符串，交易对符号
  • price: 浮点数，标记价格
• 指定交易对时：返回包含单个元素的列表
• 不指定交易对时：返回所有交易对标记价格数据列表

示例:

# 获取单个交易对的标记价格
result = trader.get_mark_price(0, "BTC_USDT")

if "Ok" in result:
    mark_prices = result["Ok"]
    if mark_prices:
        mark = mark_prices[0]
        print(f"交易对: {mark['symbol']}")
        print(f"标记价格: {mark['price']}")
else:
    print(f"获取标记价格失败: {result.get('Err', '未知错误')}")

# 获取所有交易对的标记价格
result = trader.get_mark_price(0)

if "Ok" in result:
    mark_prices = result["Ok"]
    print(f"共获取 {len(mark_prices)} 个交易对标记价格")
    for mark in mark_prices[:5]:  # 显示前5个
        print(f"  {mark['symbol']}: {mark['price']}")
else:
    print(f"获取标记价格失败: {result.get('Err', '未知错误')}")

📊 get_funding_rates(account_id, extra=None, generate=False)

功能: 获取所有交易对的资金费率

参数:

• account_id: 整数，账户ID
• extra: 字典，可选，额外参数
• generate: 布尔值，可选，默认为False，设为True时只生成命令而不执行

返回值:

• 所有交易对资金费率数据列表，每个元素为字典，包含:
  • symbol: 字符串，交易对符号
  • funding_rate: 浮点数，当前资金费率（小数形式，如0.0001表示0.01%）
  • next_funding_at: 整数，下次资金费结算时间，Unix时间戳（毫秒）
  • min_funding_rate: 浮点数，资金费率最小值（交易所设定的下限）
  • max_funding_rate: 浮点数，资金费率最大值（交易所设定的上限）
  • funding_interval: 整数或None，资金费结算周期，以小时为单位（如8表示8小时结算一次）

📊 get_funding_rate_by_symbol(account_id, symbol, extra=None, generate=False)

功能: 获取指定交易对的资金费率

参数:

• account_id: 整数，账户ID
• symbol: 字符串，交易对名称
• extra: 字典，可选，额外参数
• generate: 布尔值，可选，默认为False，设为True时只生成命令而不执行

返回值:

• 指定交易对资金费率数据字典，包含:
  • symbol: 字符串，交易对符号
  • funding_rate: 浮点数，当前资金费率（小数形式，如0.0001表示0.01%）
  • next_funding_at: 整数，下次资金费结算时间，Unix时间戳（毫秒）
  • min_funding_rate: 浮点数，资金费率最小值（交易所设定的下限）
  • max_funding_rate: 浮点数，资金费率最大值（交易所设定的上限）
  • funding_interval: 整数或None，资金费结算周期，以小时为单位（如8表示8小时结算一次）

示例:

# 获取BTC_USDT的资金费率
result = trader.get_funding_rate_by_symbol(
    account_id=0,
    symbol="BTC_USDT"
)

if "Ok" in result:
    funding_rate_data = result["Ok"]
    current_rate = funding_rate_data['funding_rate']
    min_rate = funding_rate_data['min_funding_rate']
    max_rate = funding_rate_data['max_funding_rate']
    interval = funding_rate_data.get('funding_interval', 8)  # 默认8小时

    print(f"BTC_USDT 当前资金费率: {current_rate:.6f} ({current_rate*100:.4f}%)")
    print(f"费率范围: {min_rate:.6f} ~ {max_rate:.6f}")
    print(f"结算周期: 每{interval}小时")
    print(f"下次结算时间: {funding_rate_data['next_funding_at']}")
else:
    error = result.get("Err", "未知错误")
    print(f"获取资金费率失败: {error}")

# 获取所有交易对的资金费率并分析
result = trader.get_funding_rates(account_id=0)

if "Ok" in result:
    all_funding_rates = result["Ok"]

    for rate_data in all_funding_rates:
        symbol = rate_data['symbol']
        current_rate = rate_data['funding_rate']
        min_rate = rate_data['min_funding_rate']
        max_rate = rate_data['max_funding_rate']

        # 计算当前费率在允许范围内的位置（百分比）
        if max_rate != min_rate:
            position_pct = (current_rate - min_rate) / (max_rate - min_rate) * 100
            print(f"{symbol}: 当前 {current_rate:.6f}, 位置 {position_pct:.1f}% (范围: {min_rate:.6f} ~ {max_rate:.6f})")
        else:
            print(f"{symbol}: 当前 {current_rate:.6f} (固定费率)")
else:
    error = result.get("Err", "未知错误")
    print(f"获取所有资金费率失败: {error}")

📊 get_funding_rate_history(account_id, symbol=None, since_secs=None, limit=100, extra=None, generate=False)

功能: 获取资金费率历史记录

参数:

• account_id: 整数，账户ID
• symbol: 字符串，可选，交易对名称，不传则获取全部交易对
• since_secs: 整数，可选，开始时间，Unix时间戳（秒），不传则返回最近limit条数据
• limit: 整数，可选，返回数据条数限制，默认100
• extra: 字典，可选，额外参数
• generate: 布尔值，可选，默认为False，设为True时只生成命令而不执行

返回值:

• 资金费率历史记录列表，每条记录为字典，包含:
  • symbol: 字符串，交易对符号
  • funding_rate: 浮点数，资金费率（小数形式，如0.0001表示0.01%）
  • funding_time: 整数，结算时间，Unix时间戳（毫秒）

示例:

# 获取BTC_USDT的最近100条资金费率历史
result = trader.get_funding_rate_history(
    account_id=0,
    symbol="BTC_USDT",
    limit=100
)

if "Ok" in result:
    funding_history = result["Ok"]
    print(f"获取到{len(funding_history)}条资金费率历史记录")

    for record in funding_history:
        print(f"时间: {record['funding_time']}, "
              f"费率: {record['funding_rate']:.6f} ({record['funding_rate']*100:.4f}%), "
              f"交易对: {record['symbol']}")
else:
    error = result.get("Err", "未知错误")
    print(f"获取资金费率历史失败: {error}")

# 获取指定时间范围的资金费率历史
import time
since_time = int(time.time()) - 7 * 24 * 60 * 60  # 7天前的时间戳（秒）

result = trader.get_funding_rate_history(
    account_id=0,
    symbol="BTC_USDT",
    since_secs=since_time,
    limit=50
)

if "Ok" in result:
    funding_history = result["Ok"]
    print(f"获取7天内的资金费率历史: {len(funding_history)}条")

    # 计算平均资金费率
    if funding_history:
        avg_rate = sum(record['funding_rate'] for record in funding_history) / len(funding_history)
        print(f"平均资金费率: {avg_rate:.6f} ({avg_rate*100:.4f}%)")
else:
    error = result.get("Err", "未知错误")
    print(f"获取指定时间范围资金费率历史失败: {error}")

# 获取所有交易对的最近资金费率历史
result = trader.get_funding_rate_history(
    account_id=0,
    limit=20  # 每个交易对最近20条
)

if "Ok" in result:
    all_funding_history = result["Ok"]
    print(f"获取所有交易对资金费率历史: {len(all_funding_history)}条")

    # 按交易对分组统计
    symbol_stats = {}
    for record in all_funding_history:
        symbol = record['symbol']
        if symbol not in symbol_stats:
            symbol_stats[symbol] = []
        symbol_stats[symbol].append(record['funding_rate'])

    # 显示各交易对的资金费率统计
    for symbol, rates in symbol_stats.items():
        avg_rate = sum(rates) / len(rates)
        max_rate = max(rates)
        min_rate = min(rates)
        print(f"{symbol}: 平均 {avg_rate:.6f}, 最高 {max_rate:.6f}, 最低 {min_rate:.6f}")
else:
    error = result.get("Err", "未知错误")
    print(f"获取所有交易对资金费率历史失败: {error}")

# 使用publish方法调用
cmd = {
    "account_id": 0,
    "method": "FundingRateHistory",
    "symbol": "BTC_USDT",
    "since_secs": 1672531200,  # 2023-01-01的时间戳
    "limit": 100,
    "sync": True
}
result = trader.publish(cmd)
print(f"资金费率历史: {result}")

📊 get_funding_fee(account_id, symbol, start_time=None, end_time=None, extra=None, generate=False)

功能: 查询指定交易对的历史资金费用记录

参数:

• account_id: 整数，账户ID
• symbol: 字符串，交易对名称
• start_time: 整数，可选，开始时间，Unix时间戳（毫秒）
• end_time: 整数，可选，结束时间，Unix时间戳（毫秒）
• extra: 字典，可选，额外参数
• generate: 布尔值，可选，默认为False，设为True时只生成命令而不执行

返回值:

• 资金费用历史记录列表，每条记录为字典，包含:
  • symbol: 字符串，交易对符号
  • funding_fee: 浮点数，资金费用金额（正数表示收入，负数表示支出）
  • timestamp: 整数，结算时间，Unix时间戳（毫秒）

示例:

# 查询BTC_USDT的资金费用记录
result = trader.get_funding_fee(
    account_id=0,
    symbol="BTC_USDT"
)

if "Ok" in result:
    funding_fee_data = result["Ok"]
    print(f"资金费用记录: {funding_fee_data}")
else:
    error = result.get("Err", "未知错误")
    print(f"获取资金费用记录失败: {error}")
    funding_fee_data = None

# 查询指定时间范围的资金费用
import time
end_time = int(time.time() * 1000)  # 当前时间戳(毫秒)
start_time = end_time - 7 * 24 * 60 * 60 * 1000  # 7天前

result = trader.get_funding_fee(
    account_id=0,
    symbol="BTC_USDT",
    start_time=start_time,
    end_time=end_time
)

if "Ok" in result:
    funding_fee_data = result["Ok"]

    # 处理资金费用数据
    total_fee = 0
    for record in funding_fee_data:
        fee_type = "收入" if record['funding_fee'] > 0 else "支出"
        total_fee += record['funding_fee']
        print(f"时间: {record['timestamp']}, "
              f"费用: {record['funding_fee']:.6f} ({fee_type}), "
              f"交易对: {record['symbol']}")

    print(f"总资金费用: {total_fee:.6f}")
else:
    error = result.get("Err", "未知错误")
    print(f"获取指定时间范围资金费用失败: {error}")

# 使用publish方法调用
cmd = {
    "account_id": 1,
    "method": "FundingFee",
    "symbol": "BTC_USDT",
    "start_time": 1672531200000,
    "end_time": 1672617600000,
    "sync": True
}
result = trader.publish(cmd)

📈 get_kline(account_id, symbol, interval, start_time=None, end_time=None, limit=None, extra=None, generate=False)

功能: 获取指定交易对的K线数据

参数:

• account_id: 整数，账户ID
• symbol: 字符串，交易对符号
• interval: 字符串，K线时间粒度，支持的值包括:
  • "1m": 1分钟
  • "3m": 3分钟
  • "5m": 5分钟
  • "15m": 15分钟
  • "30m": 30分钟
  • "1h": 1小时
  • "2h": 2小时
  • "4h": 4小时
  • "6h": 6小时
  • "8h": 8小时
  • "12h": 12小时
  • "1d": 1天
  • "3d": 3天
  • "1w": 1周
  • "1M": 1月
• start_time: 整数，可选，开始时间，Unix时间戳（毫秒）
• end_time: 整数，可选，结束时间，Unix时间戳（毫秒）
• limit: 整数，可选，返回数据条数限制，默认100，最大1000
• extra: 字典，可选，扩展参数，用于特定交易所的额外参数
• generate: 布尔值，可选，默认为False，设为True时只生成命令而不执行

返回值:

• K线数据对象，包含以下字段:
  • symbol: 交易对符号
  • interval: K线时间粒度
  • candles: 蜡烛图数据列表，每个元素包含:
    • timestamp: 开盘时间，Unix时间戳（毫秒）
    • open: 开盘价
    • high: 最高价
    • low: 最低价
    • close: 收盘价
    • volume: 成交量（基础货币）
    • quote_volume: 成交额（报价货币）
    • trades: 成交笔数（可选）
    • taker_buy_volume: taker买入成交量（基础货币，可选）
    • taker_buy_quote_volume: taker买入成交额（报价货币，可选）
    • confirm: K线状态，false代表K线未完结，true代表K线已完结

示例:

# 获取BTC_USDT的1分钟K线数据，使用默认限制100条
result = trader.get_kline(
    account_id=0,
    symbol="BTC_USDT",
    interval="1m",
    limit=100
)

if "Ok" in result:
    kline_data = result["Ok"]
    print(f"交易对: {kline_data['symbol']}")
    print(f"时间粒度: {kline_data['interval']}")
    print(f"获取到{len(kline_data['candles'])}条K线数据")
else:
    error = result.get("Err", "未知错误")
    print(f"获取K线数据失败: {error}")
    kline_data = None

# 获取指定时间范围的K线数据
import time
end_time = int(time.time() * 1000)  # 当前时间戳(毫秒)
start_time = end_time - 24 * 60 * 60 * 1000  # 24小时前

result = trader.get_kline(
    account_id=0,
    symbol="BTC_USDT",
    interval="1h",
    start_time=start_time,
    end_time=end_time,
    limit=24  # 24小时数据
)

if "Ok" in result:
    kline_data = result["Ok"]
    print(f"获取24小时K线数据成功: {len(kline_data['candles'])}条")
else:
    error = result.get("Err", "未知错误")
    print(f"获取24小时K线数据失败: {error}")
    kline_data = None

# 使用扩展参数（特定交易所的额外参数）
result = trader.get_kline(
    account_id=0,
    symbol="BTC_USDT",
    interval="5m",
    limit=200,
    extra={"custom_param": "value"}  # 扩展参数
)

if "Ok" in result:
    kline_data = result["Ok"]
    print(f"使用扩展参数获取K线数据成功")
else:
    error = result.get("Err", "未知错误")
    print(f"使用扩展参数获取K线数据失败: {error}")
    kline_data = None

# 处理K线数据
if kline_data:
    candles = kline_data['candles']
    for candle in candles:
        status = "已完结" if candle['confirm'] else "未完结"

        # 处理可选字段
        trades_info = f", 成交笔数: {candle['trades']}" if candle.get('trades') else ""
        taker_buy_info = ""
        if candle.get('taker_buy_volume'):
            buy_ratio = candle['taker_buy_volume'] / candle['volume'] * 100 if candle['volume'] > 0 else 0
            taker_buy_info = f", 主动买入占比: {buy_ratio:.1f}%"

        print(f"时间: {candle['timestamp']}, 开盘: {candle['open']}, "
              f"最高: {candle['high']}, 最低: {candle['low']}, "
              f"收盘: {candle['close']}, 成交量: {candle['volume']}, "
              f"成交额: {candle['quote_volume']}{trades_info}{taker_buy_info}, 状态: {status}")

    # 检查最新K线是否已完结
    if candles:
        latest_candle = candles[-1]
        if latest_candle['confirm']:
            print("最新K线已完结，可以用于技术分析")
        else:
            print("最新K线未完结，数据可能还在变化")
else:
    print("无法处理K线数据，数据获取失败")

# 使用publish方法调用K线API
cmd = {
    "account_id": 1,
    "method": "Kline",
    "symbol": "BTC_USDT",
    "interval": "1m",
    "start_time": 1672531200000,
    "end_time": 1672617600000,
    "limit": 100,
    "extra": {},  # 扩展参数字典
    "sync": True
}
result = trader.publish(cmd)
print(f"K线数据: {result}")
print(f"返回的蜡烛图数量: {len(result['candles'])}")

7.5 账户设置与杠杆管理

📊 get_max_leverage(account_id, symbol, extra=None, generate=False)

功能: 获取交易对的最大可用杠杆倍数

参数:

• account_id: 整数，账户ID
• symbol: 字符串，交易对名称
• extra: 字典，可选，额外参数
• generate: 布尔值，可选，默认为False，设为True时只生成命令而不执行

返回值:

• 最大可用杠杆倍数数据，整数（如125表示最大125倍杠杆）

示例:

# 获取 BTC_USDT 的最大杠杆
result = trader.get_max_leverage(0, "BTC_USDT")

if "Ok" in result:
    max_lev = result["Ok"]
    print(f"BTC_USDT 最大可用杠杆: {max_lev}x")
else:
    print(f"获取最大杠杆失败: {result.get('Err', '未知错误')}")

📊 set_leverage(account_id, symbol, leverage, extra=None, generate=False)

功能: 设置交易对的杠杆倍数

参数:

• account_id: 整数，账户ID
• symbol: 字符串，交易对名称
• leverage: 整数，杠杆倍数
• extra: 字典，可选，额外参数
• generate: 布尔值，可选，默认为False，设为True时只生成命令而不执行

返回值:

• 设置杠杆倍数结果，成功时返回设置后的杠杆倍数

示例:

# 设置 BTC_USDT 的杠杆为 10 倍
result = trader.set_leverage(0, "BTC_USDT", 10)

if "Ok" in result:
    print(f"杠杆设置成功，当前杠杆: {result['Ok']}x")
else:
    print(f"设置杠杆失败: {result.get('Err', '未知错误')}")

📊 get_margin_mode(account_id, symbol, margin_coin, extra=None, generate=False)

功能: 获取交易对的保证金模式

参数:

• account_id: 整数，账户ID
• symbol: 字符串，交易对名称
• margin_coin: 字符串，保证金币种
• extra: 字典，可选，额外参数
• generate: 布尔值，可选，默认为False，设为True时只生成命令而不执行

返回值:

• 保证金模式字符串:
  • "Cross": 全仓模式
  • "Isolated": 逐仓模式

示例:

# 获取 BTC_USDT 的保证金模式
result = trader.get_margin_mode(0, "BTC_USDT", "USDT")

if "Ok" in result:
    mode = result["Ok"]
    mode_cn = "全仓" if mode == "Cross" else "逐仓"
    print(f"BTC_USDT 当前保证金模式: {mode_cn} ({mode})")
else:
    print(f"获取保证金模式失败: {result.get('Err', '未知错误')}")

📊 set_margin_mode(account_id, symbol, margin_coin, margin_mode, extra=None, generate=False)

功能: 设置交易对的保证金模式

参数:

• account_id: 整数，账户ID
• symbol: 字符串，交易对名称
• margin_coin: 字符串，保证金币种
• margin_mode: 字符串或对象，保证金模式，例如"Isolated"(逐仓)或"Cross"(全仓)
• extra: 字典，可选，额外参数
• generate: 布尔值，可选，默认为False，设为True时只生成命令而不执行

返回值:

• 设置保证金模式结果，成功时返回设置后的保证金模式字符串

示例:

# 设置 BTC_USDT 为逐仓模式
result = trader.set_margin_mode(0, "BTC_USDT", "USDT", "Isolated")

if "Ok" in result:
    print(f"保证金模式设置成功: {result['Ok']}")
else:
    print(f"设置保证金模式失败: {result.get('Err', '未知错误')}")

📊 is_dual_side(account_id, extra=None, generate=False)

功能: 查询账户是否使用双向持仓模式

参数:

• account_id: 整数，账户ID
• extra: 字典，可选，额外参数
• generate: 布尔值，可选，默认为False，设为True时只生成命令而不执行

返回值:

• 布尔值，true表示双向持仓模式（可同时持有多空仓位），false表示单向持仓模式

示例:

# 查询账户持仓模式
result = trader.is_dual_side(0)

if "Ok" in result:
    is_dual = result["Ok"]
    mode_cn = "双向持仓" if is_dual else "单向持仓"
    print(f"当前持仓模式: {mode_cn}")
else:
    print(f"查询持仓模式失败: {result.get('Err', '未知错误')}")

📊 set_dual_side(account_id, dual_side, extra=None, generate=False)

功能: 设置账户的持仓模式

参数:

• account_id: 整数，账户ID
• dual_side: 布尔值，是否使用双向持仓模式（true=双向持仓，false=单向持仓）
• extra: 字典，可选，额外参数
• generate: 布尔值，可选，默认为False，设为True时只生成命令而不执行

返回值:

• 设置持仓模式结果，成功时返回布尔值表示当前持仓模式

示例:

# 设置为双向持仓模式
result = trader.set_dual_side(0, True)

if "Ok" in result:
    print(f"持仓模式设置成功，当前为双向持仓: {result['Ok']}")
else:
    print(f"设置持仓模式失败: {result.get('Err', '未知错误')}")

注意: 修改持仓模式前请确保没有未平仓仓位，否则可能会设置失败

7.6 市值数据查询

📊 get_market_cap(account_id, coin=None, generate=False)

功能: 获取币种的市值数据

⚠️ 重要提示：此方法仅支持CoinMarketCap交易所调用

参数:

• account_id: 整数，账户ID
• coin: 字符串，可选，币种名称（如"BTC"、"ETH"等），不传则获取全部市值数据
• generate: 布尔值，可选，默认为False，设为True时只生成命令而不执行

返回值:

• 返回值为MarketCap结构体数组，每个元素代表一个币种的市值信息
• 若指定coin参数，返回数组长度为1的MarketCap对象；不指定coin则返回所有币种的MarketCap数组

MarketCap结构体字段说明：

字段名	类型	说明
symbol	String	币种符号
name	String	币种名称
total_volume_24h	f64	24小时总交易量
total_supply	f64	总供应量
max_supply	f64	最大供应量
circulating_supply	f64	流通供应量
market_cap	f64	市值
market_cap_rank	u32	市值排名
current_price	f64	当前价格
price_change_percentage_1h	f64	1小时涨跌幅（%）
price_change_percentage_24h	f64	24小时涨跌幅（%）
price_change_percentage_7d	f64	7天涨跌幅（%）
price_change_percentage_30d	f64	30天涨跌幅（%）
platform_info	Option<PlatformInfo>	平台信息（可选）
last_updated	Option<i64>	最后更新时间戳（毫秒）

PlatformInfo结构体字段说明：

字段名	类型	说明
name	String	父平台加密货币名称
slug	String	父平台加密货币的URL友好简称
token_address	String	父平台上的代币地址

Python字典格式示例：

# 单个币种市值数据示例
market_cap_data = {
    "symbol": "BTC",
    "name": "Bitcoin",
    "total_volume_24h": 1234567890.0,
    "total_supply": 21000000.0,
    "max_supply": 21000000.0,
    "circulating_supply": 19500000.0,
    "market_cap": 987654321000.0,
    "market_cap_rank": 1,
    "current_price": 50648.0,
    "price_change_percentage_1h": 0.5,
    "price_change_percentage_24h": -2.3,
    "price_change_percentage_7d": 5.7,
    "price_change_percentage_30d": 12.4,
    "platform_info": None,
    "last_updated": 1703123456789
}

# 多个币种市值数据示例（数组格式）
all_market_cap_data = [
    {
        "symbol": "BTC",
        "name": "Bitcoin",
        "total_volume_24h": 1234567890.0,
        "total_supply": 21000000.0,
        "max_supply": 21000000.0,
        "circulating_supply": 19500000.0,
        "market_cap": 987654321000.0,
        "market_cap_rank": 1,
        "current_price": 50648.0,
        "price_change_percentage_1h": 0.5,
        "price_change_percentage_24h": -2.3,
        "price_change_percentage_7d": 5.7,
        "price_change_percentage_30d": 12.4,
        "platform_info": None,
        "last_updated": 1703123456789
    },
    {
        "symbol": "ETH",
        "name": "Ethereum",
        "total_volume_24h": 987654321.0,
        "total_supply": 120000000.0,
        "max_supply": None,  # 某些币种可能没有最大供应量
        "circulating_supply": 119000000.0,
        "market_cap": 234567890000.0,
        "market_cap_rank": 2,
        "current_price": 1972.0,
        "price_change_percentage_1h": -0.8,
        "price_change_percentage_24h": 1.2,
        "price_change_percentage_7d": -3.1,
        "price_change_percentage_30d": 8.9,
        "platform_info": None,
        "last_updated": 1703123456789
    },
    {
        "symbol": "USDT",
        "name": "Tether",
        "total_volume_24h": 456789123.0,
        "total_supply": 100000000000.0,
        "max_supply": 100000000000.0,
        "circulating_supply": 95000000000.0,
        "market_cap": 95000000000.0,
        "market_cap_rank": 3,
        "current_price": 1.0,
        "price_change_percentage_1h": 0.0,
        "price_change_percentage_24h": 0.0,
        "price_change_percentage_7d": 0.0,
        "price_change_percentage_30d": 0.0,
        "platform_info": {
            "name": "Ethereum",
            "slug": "ethereum",
            "token_address": "0xdac17f958d2ee523a2206206994597c13d831ec7"
        },
        "last_updated": 1703123456789
    }
]

示例:

# 获取指定币种的市值数据
result = trader.get_market_cap(0, "BTC")

if "Ok" in result:
    market_cap_data = result["Ok"]
    print(f"BTC市值数据: {market_cap_data}")
else:
    error = result.get("Err", "未知错误")
    print(f"获取BTC市值数据失败: {error}")

# 获取全部币种的市值数据
result = trader.get_market_cap(0)

if "Ok" in result:
    all_market_cap_data = result["Ok"]
    print(f"获取到{len(all_market_cap_data)}个币种的市值数据")
    for coin_data in all_market_cap_data:
        print(f"币种: {coin_data['symbol']}, 名称: {coin_data['name']}, 市值: {coin_data['market_cap']}, 当前价格: {coin_data['current_price']}")
else:
    error = result.get("Err", "未知错误")
    print(f"获取全部市值数据失败: {error}")

# 使用publish方法调用
cmd = {
    "account_id": 0,
    "method": "MarketCap",
    "coin": "ETH",  # 可选，不传则获取全部
    "sync": True
}
result = trader.publish(cmd)
print(f"市值数据: {result}")

注意事项:

1. 交易所限制: 此方法仅支持CoinMarketCap交易所调用
2. 数据格式: 返回的数据为MarketCap结构体，包含币种符号、市值等信息
3. 可选参数: coin参数为可选，不传则返回所有币种的市值数据

7.7 运行时订阅管理

📊 subscribe(ws_id, channels, generate=False)

功能: 运行时动态订阅行情数据

参数:

• ws_id: 整数，subscribes() 方法中 SubscribeWs 类型订阅 的索引（从0开始）。只有 SubscribeWs 类型计入索引，SubscribeRest 和 SubscribeTimer 不计入。例如：

  def subscribes(self):
      return [
          {"account_id": 0, "sub": {"SubscribeWs": [...]}},    # ws_id=0
          {"sub": {"SubscribeTimer": {...}}},                   # 不计入 ws_id
          {"account_id": 0, "sub": {"SubscribeWs": [...]}},    # ws_id=1
          {"account_id": 0, "sub": {"SubscribeRest": {...}}}   # 不计入 ws_id
      ]
• channels: 列表，订阅频道配置，每个元素为一个订阅项，格式与subscribes()方法中的配置相同
• generate: 布尔值，可选，默认为False，设为True时只生成命令而不执行

返回值:

• 订阅请求结果，实际订阅结果通过on_subscribe回调返回

示例:

# 运行时订阅BBO数据
channels = [
    {"Bbo": ["BTC_USDT", "ETH_USDT"]}
]
result = trader.subscribe(ws_id=0, channels=channels)

# 运行时订阅深度数据
channels = [
    {"Depth": ["BTC_USDT"]}
]
result = trader.subscribe(ws_id=0, channels=channels)

# 运行时订阅成交数据
channels = [
    {"Trade": ["BTC_USDT", "ETH_USDT"]}
]
result = trader.subscribe(ws_id=0, channels=channels)

# 对应的回调函数处理：
def on_subscribe(self, ws_id, channels, result):
    """
    运行时订阅完成时触发的回调

    Args:
        ws_id: subscribes() 中 SubscribeWs 类型订阅的索引
        channels: 订阅的频道列表
        result: 订阅结果，格式为{"Ok": null} 或 {"Err": "错误信息"}
    """
    if "Ok" in result:
        print(f"订阅成功，ws_id: {ws_id}, channels: {channels}")
    else:
        error = result.get("Err", "未知错误")
        print(f"订阅失败: {error}")

📊 unsubscribe(ws_id, channels, generate=False)

功能: 运行时取消订阅行情数据

参数:

• ws_id: 整数，subscribes() 方法中 SubscribeWs 类型订阅 的索引（从0开始），只有 SubscribeWs 类型计入索引
• channels: 列表，取消订阅的频道配置
• generate: 布尔值，可选，默认为False，设为True时只生成命令而不执行

返回值:

• 取消订阅请求结果，实际结果通过on_unsubscribe回调返回

示例:

# 取消订阅BBO数据
channels = [
    {"Bbo": ["BTC_USDT", "ETH_USDT"]}
]
result = trader.unsubscribe(ws_id=0, channels=channels)

# 对应的回调函数处理：
def on_unsubscribe(self, ws_id, channels, result):
    """
    运行时取消订阅完成时触发的回调

    Args:
        ws_id: subscribes() 中 SubscribeWs 类型订阅的索引
        channels: 取消订阅的频道列表
        result: 取消订阅结果，格式为{"Ok": null} 或 {"Err": "错误信息"}
    """
    if "Ok" in result:
        print(f"取消订阅成功，ws_id: {ws_id}, channels: {channels}")
    else:
        error = result.get("Err", "未知错误")
        print(f"取消订阅失败: {error}")

注意事项:

1. 动态订阅: 这两个方法允许在策略运行过程中动态增减订阅的数据，无需重启策略
2. 回调处理: 订阅/取消订阅的结果通过on_subscribe和on_unsubscribe回调异步返回
3. 频道格式: channels参数格式与subscribes()方法中的SubscribeWs配置相同

7.8 资金划转与借贷

📊 transfer(account_id, transfer, extra=None, generate=False)

功能: 在账户内部或不同账户之间划转资金

参数:

• account_id: 整数，账户ID
• transfer: 字典或对象，划转信息，包含以下字段:
  • asset: 字符串，币种名称
  • amount: 浮点数，划转金额
  • from: 字符串，转出账户类型，支持的值:
    • "Spot": 现货钱包
    • "UsdtFuture": U本位合约钱包（默认）
    • "CoinFuture": 币本位合约钱包
    • "Margin": 杠杆全仓钱包
    • "IsolatedMargin": 杠杆逐仓钱包
  • to: 字符串，转入账户类型，支持的值同上
• extra: 字典，可选，额外参数
• generate: 布尔值，可选，默认为False，设为True时只生成命令而不执行

返回值:

• 成功时返回 None（划转成功无返回值）
• 失败时返回错误信息

示例:

# 从现货钱包转账到U本位合约钱包
transfer_data = {
    "asset": "USDT",
    "amount": 1000.0,
    "from": "Spot",
    "to": "UsdtFuture"
}
result = trader.transfer(0, transfer_data)

if "Ok" in result:
    success_data = result["Ok"]
    print(f"划转成功: {success_data}")
else:
    error = result.get("Err", "未知错误")
    print(f"划转失败: {error}")

# 从U本位合约钱包转账到杠杆全仓钱包
transfer_data = {
    "asset": "BTC",
    "amount": 0.1,
    "from": "UsdtFuture",
    "to": "Margin"
}
result = trader.transfer(0, transfer_data)

if "Ok" in result:
    success_data = result["Ok"]
    print(f"BTC划转成功: {success_data}")
else:
    error = result.get("Err", "未知错误")
    print(f"BTC划转失败: {error}")

📊 sub_transfer(account_id, sub_transfer, extra=None, generate=False)

功能: 主账户和子账户之间划转资金

参数:

• account_id: 整数，账户ID
• sub_transfer: 字典或对象，划转信息，包含以下字段:
  • cid: 字符串，可选，客户端自定义ID
  • asset: 字符串，币种名称
  • amount: 浮点数，划转金额
  • from: 字符串，转出账户类型，支持的值:
    • "Spot": 现货钱包
    • "UsdtFuture": U本位合约钱包（默认）
    • "CoinFuture": 币本位合约钱包
    • "Margin": 杠杆全仓钱包
    • "IsolatedMargin": 杠杆逐仓钱包
  • to: 字符串，转入账户类型，支持的值同上
  • from_account: 字符串，可选，转出账户ID，为空时默认为母账户。注意: 当交易所为Bitget时，母账户不能为空
  • to_account: 字符串，可选，转入账户ID，为空时默认为母账户。注意: 当交易所为Bitget时，母账户不能为空
  • direction: 字符串，划转方向，支持的值:
    • "MasterToSub": 母转子（默认）
    • "SubToMaster": 子转母
    • "SubToSub": 子转子
• extra: 字典，可选，额外参数
• generate: 布尔值，可选，默认为False，设为True时只生成命令而不执行

返回值:

• 成功时返回 None（划转成功无返回值）
• 失败时返回错误信息

示例:

# 母账户向子账户划转USDT
sub_transfer_data = {
    "cid": "transfer_001",
    "asset": "USDT",
    "amount": 500.0,
    "from": "UsdtFuture",
    "to": "UsdtFuture",
    "from_account": None,  # 母账户
    "to_account": "sub_account_123",  # 子账户ID
    "direction": "MasterToSub"
}
result = trader.sub_transfer(0, sub_transfer_data)

if "Ok" in result:
    success_data = result["Ok"]
    print(f"子账户划转成功: {success_data}")
else:
    error = result.get("Err", "未知错误")
    print(f"子账户划转失败: {error}")

# 子账户向母账户划转BTC
sub_transfer_data = {
    "asset": "BTC",
    "amount": 0.05,
    "from": "Spot",
    "to": "Spot",
    "from_account": "sub_account_456",
    "to_account": None,  # 母账户
    "direction": "SubToMaster"
}
result = trader.sub_transfer(0, sub_transfer_data)

if "Ok" in result:
    success_data = result["Ok"]
    print(f"BTC子转母成功: {success_data}")
else:
    error = result.get("Err", "未知错误")
    print(f"BTC子转母失败: {error}")

# 子账户之间划转（需要指定两个子账户）
sub_transfer_data = {
    "asset": "ETH",
    "amount": 1.0,
    "from": "UsdtFuture",
    "to": "UsdtFuture",
    "from_account": "sub_account_123",
    "to_account": "sub_account_456",
    "direction": "SubToSub"
}
result = trader.sub_transfer(0, sub_transfer_data)

if "Ok" in result:
    success_data = result["Ok"]
    print(f"ETH子转子成功: {success_data}")
else:
    error = result.get("Err", "未知错误")
    print(f"ETH子转子失败: {error}")

# 使用publish方法调用
cmd = {
    "account_id": 0,
    "method": "Transfer",
    "transfer": {
        "asset": "USDT",
        "amount": 1000.0,
        "from": "Spot",
        "to": "UsdtFuture"
    },
    "sync": True
}
result = trader.publish(cmd)

# 子账户划转的publish方法调用
cmd = {
    "account_id": 0,
    "method": "SubTransfer",
    "sub_transfer": {
        "cid": "transfer_002",
        "asset": "USDT",
        "amount": 500.0,
        "from": "UsdtFuture",
        "to": "UsdtFuture",
        "from_account": None,
        "to_account": "sub_account_123",
        "direction": "MasterToSub"
    },
    "sync": True
}
result = trader.publish(cmd)

钱包类型说明:

钱包类型	说明	适用场景
Spot	现货钱包	现货交易、充值提现
UsdtFuture	U本位合约钱包	USDT保证金的永续合约交易
CoinFuture	币本位合约钱包	币本位保证金的合约交易
Margin	杠杆全仓钱包	杠杆交易（全仓模式）
IsolatedMargin	杠杆逐仓钱包	杠杆交易（逐仓模式）

划转方向说明:

方向	说明	使用场景
MasterToSub	母转子	母账户向子账户划转资金
SubToMaster	子转母	子账户向母账户划转资金
SubToSub	子转子	子账户之间直接划转资金

注意事项:

1. Bitget交易所特殊要求: 当使用Bitget交易所时，from_account和to_account字段中的母账户不能为空，需要明确指定母账户ID
2. 账户ID格式: 不同交易所的账户ID格式可能不同，请参考具体交易所的API文档
3. 权限要求: 子账户划转功能需要相应的API权限，确保API密钥具有子账户管理权限
4. 资金安全: 划转操作不可逆，请仔细核对划转参数，特别是账户ID和金额

📊 get_deposit_address(account_id, ccy, chain=None, amount=None, extra=None, generate=False)

功能: 获取指定币种的充值地址

参数:

• account_id: 整数，账户ID
• ccy: 字符串，币种名称，如"USDT"、"BTC"等
• chain: 字符串，可选，链类型，支持的值:
  • "Erc20": 以太坊链（默认）
  • "Trc20": 波场链
  • "Bep20": 币安智能链
  • "Sol": Solana链
  • "Polygon": Polygon链
  • "ArbitrumOne": Arbitrum链
  • "Optimism": Optimism链
  • "Ton": TON链
  • "AVAXC": Avalanche链
• amount: 浮点数，可选，预估充值金额（部分交易所需要）
• extra: 字典，可选，额外参数
• generate: 布尔值，可选，默认为False，设为True时只生成命令而不执行

返回值:

• 充值地址信息字典，包含:
  • asset: 字符串，币种名称
  • address: 字符串，充值地址
  • chain: 字符串或None，链类型
  • tag: 字符串或None，地址标签（某些币种如EOS、XRP需要）
  • url: 字符串或None，充值二维码URL（可选）

示例:

# 获取USDT的ERC20充值地址
result = trader.get_deposit_address(
    account_id=0,
    ccy="USDT",
    chain="Erc20"
)

if "Ok" in result:
    deposit_info = result["Ok"]
    print(f"USDT ERC20充值地址: {deposit_info['address']}")
    print(f"币种: {deposit_info['asset']}")
    print(f"链类型: {deposit_info['chain']}")
else:
    error = result.get("Err", "未知错误")
    print(f"获取USDT ERC20充值地址失败: {error}")

# 获取USDT的TRC20充值地址
result = trader.get_deposit_address(
    account_id=0,
    ccy="USDT",
    chain="Trc20"
)

if "Ok" in result:
    deposit_info_trc = result["Ok"]
    print(f"USDT TRC20充值地址: {deposit_info_trc['address']}")
else:
    error = result.get("Err", "未知错误")
    print(f"获取USDT TRC20充值地址失败: {error}")

# 获取BTC充值地址（不指定链，使用默认）
result = trader.get_deposit_address(
    account_id=0,
    ccy="BTC"
)

if "Ok" in result:
    btc_deposit = result["Ok"]
    print(f"BTC充值地址: {btc_deposit['address']}")
else:
    error = result.get("Err", "未知错误")
    print(f"获取BTC充值地址失败: {error}")

# 获取需要标签的币种充值地址（如EOS）
result = trader.get_deposit_address(
    account_id=0,
    ccy="EOS"
)

if "Ok" in result:
    eos_deposit = result["Ok"]
    print(f"EOS充值地址: {eos_deposit['address']}")
    if eos_deposit.get('tag'):
        print(f"EOS充值标签: {eos_deposit['tag']}")
else:
    error = result.get("Err", "未知错误")
    print(f"获取EOS充值地址失败: {error}")

# 使用publish方法调用
cmd = {
    "account_id": 0,
    "method": "GetDepositAddress",
    "ccy": "USDT",
    "chain": "Trc20",
    "sync": True
}
result = trader.publish(cmd)
print(f"充值地址信息: {result}")

📊 withdrawal(account_id, withdrawal, extra=None, generate=False)

功能: 提币到外部地址或内部转账

参数:

• account_id: 整数，账户ID

• withdrawal: 字典，提币信息，包含以下字段:

  • cid: 字符串，可选，客户端自定义ID

  • asset: 字符串，币种名称

  • amt: 浮点数，提币数量

  • addr: 字典，提币地址信息，支持两种类型:

    链上提币 (OnChain):

    • OnChain: 字典，包含:
      • chain: 字符串，区块链网络，支持的值:
        • "Erc20": 以太坊链
        • "Trc20": 波场链
        • "Bep20": 币安智能链
        • "Sol": Solana链
        • "Polygon": Polygon链
        • "ArbitrumOne": Arbitrum链
        • "Optimism": Optimism链
        • "Ton": TON链
        • "AVAXC": Avalanche链
      • address: 字符串，目标钱包地址
      • tag: 字符串或None，地址标签（EOS、XRP等币种需要）

    内部转账 (InternalTransfer):

    • InternalTransfer: 字符串，支持三种格式:
      • {"Email": "user@example.com"}: 邮箱转账
      • {"Phone": ["+86", "13800138000"]}: 手机号转账（区号+手机号）
      • {"Uid": "12345678"}: 用户ID转账

• extra: 字典，可选，额外参数

• generate: 布尔值，可选，默认为False，设为True时只生成命令而不执行

返回值:

• 成功时返回 None（提币请求已提交）
• 失败时返回错误信息

示例:

# 链上提币 - USDT通过TRC20网络提币
withdrawal_data = {
    "cid": "withdraw_001",
    "asset": "USDT",
    "amt": 100.0,
    "addr": {
        "OnChain": {
            "chain": "Trc20",
            "address": "TKzxdSv2FZKQrEqkKVgp5DcwEXBEKMg2Ax",
            "tag": None
        }
    }
}
result = trader.withdrawal(0, withdrawal_data)

if "Ok" in result:
    success_data = result["Ok"]
    print(f"USDT提币成功: {success_data}")
else:
    error = result.get("Err", "未知错误")
    print(f"USDT提币失败: {error}")

# 链上提币 - BTC提币
btc_withdrawal = {
    "cid": "withdraw_btc_001",
    "asset": "BTC",
    "amt": 0.01,
    "addr": {
        "OnChain": {
            "chain": "Erc20",  # BTC通常不需要指定链
            "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
            "tag": None
        }
    }
}
result = trader.withdrawal(0, btc_withdrawal)

if "Ok" in result:
    success_data = result["Ok"]
    print(f"BTC提币成功: {success_data}")
else:
    error = result.get("Err", "未知错误")
    print(f"BTC提币失败: {error}")

# 链上提币 - EOS提币（需要tag）
eos_withdrawal = {
    "asset": "EOS",
    "amt": 10.0,
    "addr": {
        "OnChain": {
            "chain": "Erc20",
            "address": "eosaccount123",
            "tag": "1234567890"  # EOS需要memo标签
        }
    }
}
result = trader.withdrawal(0, eos_withdrawal)

if "Ok" in result:
    success_data = result["Ok"]
    print(f"EOS提币成功: {success_data}")
else:
    error = result.get("Err", "未知错误")
    print(f"EOS提币失败: {error}")

# 内部转账 - 通过邮箱转账
internal_transfer_email = {
    "cid": "internal_001",
    "asset": "USDT",
    "amt": 50.0,
    "addr": {
        "InternalTransfer": {
            "Email": "recipient@example.com"
        }
    }
}
result = trader.withdrawal(0, internal_transfer_email)

if "Ok" in result:
    success_data = result["Ok"]
    print(f"邮箱内部转账成功: {success_data}")
else:
    error = result.get("Err", "未知错误")
    print(f"邮箱内部转账失败: {error}")

# 内部转账 - 通过手机号转账
internal_transfer_phone = {
    "asset": "BTC",
    "amt": 0.005,
    "addr": {
        "InternalTransfer": {
            "Phone": ["+86", "13800138000"]  # [区号, 手机号]
        }
    }
}
result = trader.withdrawal(0, internal_transfer_phone)

if "Ok" in result:
    success_data = result["Ok"]
    print(f"手机号内部转账成功: {success_data}")
else:
    error = result.get("Err", "未知错误")
    print(f"手机号内部转账失败: {error}")

# 内部转账 - 通过用户ID转账
internal_transfer_uid = {
    "asset": "ETH",
    "amt": 0.1,
    "addr": {
        "InternalTransfer": {
            "Uid": "12345678"
        }
    }
}
result = trader.withdrawal(0, internal_transfer_uid)

if "Ok" in result:
    success_data = result["Ok"]
    print(f"用户ID内部转账成功: {success_data}")
else:
    error = result.get("Err", "未知错误")
    print(f"用户ID内部转账失败: {error}")

# 使用publish方法调用
cmd = {
    "account_id": 0,
    "method": "Withdrawal",
    "withdrawal": {
        "cid": "withdraw_publish_001",
        "asset": "USDT",
        "amt": 100.0,
        "addr": {
            "OnChain": {
                "chain": "Trc20",
                "address": "TKzxdSv2FZKQrEqkKVgp5DcwEXBEKMg2Ax",
                "tag": None
            }
        }
    },
    "sync": True
}
result = trader.publish(cmd)
print(f"提币结果: {result}")

重要提醒:

1. 手续费: 链上提币会产生网络手续费，请确保账户余额充足
2. 最小提币量: 每个币种都有最小提币数量限制，请查询交易所规则
3. 地址验证: 提币前请仔细核对目标地址，错误地址可能导致资金永久丢失
4. 网络确认: 不同链的确认时间不同，TRC20通常较快，ERC20在网络拥堵时可能较慢
5. 标签要求: EOS、XRP、XMR等币种需要正确的标签(tag/memo)，否则可能丢失
6. API权限: 提币功能需要账户开启提币权限，并且API密钥需要具备提币权限
7. 风控限制: 大额提币可能触发风控审核，需要额外验证

链类型选择建议:

币种	推荐链类型	特点
USDT	Bep20	手续费低，确认快
USDT	Erc20	兼容性好，但手续费较高
USDT	Trc20	手续费适中，速度快
ETH	Erc20	原生链
BNB	Bep20	币安生态

📊 borrow(account_id, coin, amount, extra=None, generate=False)

功能: 借入资金

参数:

• account_id: 整数，账户ID
• coin: 字符串，币种
• amount: 浮点数，借入金额
• extra: 字典，可选，额外参数
• generate: 布尔值，可选，默认为False，设为True时只生成命令而不执行

返回值:

• 成功时返回 None（借入成功无返回值）
• 失败时返回错误信息

📊 repay(account_id, coin, amount, extra=None, generate=False)

功能: 偿还借入的资金

参数:

• account_id: 整数，账户ID
• coin: 字符串，币种
• amount: 浮点数，偿还金额
• extra: 字典，可选，额外参数
• generate: 布尔值，可选，默认为False，设为True时只生成命令而不执行

返回值:

• 成功时返回 None（偿还成功无返回值）
• 失败时返回错误信息

📊 get_borrowed(account_id, coin=None, extra=None, generate=False)

功能: 查询已借入的资金

参数:

• account_id: 整数，账户ID
• coin: 字符串，可选，币种，不指定则查询所有币种
• extra: 字典，可选，额外参数
• generate: 布尔值，可选，默认为False，设为True时只生成命令而不执行

返回值:

• 已借入资金数据列表，每个元素为字典，包含:
  • coin: 字符串，币种名称
  • amount: 浮点数，已借入金额

📊 get_borrow_rate(account_id, coin=None, extra=None, generate=False)

功能: 查询借贷利率

参数:

• account_id: 整数，账户ID
• coin: 字符串，可选，币种，不指定则查询所有币种
• extra: 字典，可选，额外参数
• generate: 布尔值，可选，默认为False，设为True时只生成命令而不执行

返回值:

• 借贷利率数据列表，每个元素为字典，包含:
  • ccy: 字符串，币种名称
  • rate: 浮点数，借贷利率

📊 get_borrow_limit(account_id, coin, is_vip=None, extra=None, generate=False)

功能: 查询借贷限额

参数:

• account_id: 整数，账户ID
• coin: 字符串，币种
• is_vip: 布尔值，可选，是否为VIP用户
• extra: 字典，可选，额外参数
• generate: 布尔值，可选，默认为False，设为True时只生成命令而不执行

返回值:

• 借贷限额数据字典，包含:
  • debt: 浮点数，当前负债
  • interest: 浮点数，当前计息
  • coin: 字符串，借贷币种
  • rate: 浮点数，日利率
  • borrow_limit: 浮点数，可借贷限额
  • vip_detail: 字典或None，尊享用户详情（可选），包含:
    • pos_loan: 浮点数，当前账户负债占用
    • available_loan: 浮点数，当前账户剩余可用
    • used_loan: 浮点数，当前账户已借额度

示例:

# 查询USDT的借贷限额
result = trader.get_borrow_limit(
    account_id=0,
    coin="USDT"
)

if "Ok" in result:
    borrow_limit = result["Ok"]
    print(f"USDT借贷限额: {borrow_limit}")
    print(f"当前负债: {borrow_limit['debt']}")
    print(f"可借贷限额: {borrow_limit['borrow_limit']}")
    print(f"日利率: {borrow_limit['rate']:.6f}")
else:
    error = result.get("Err", "未知错误")
    print(f"查询USDT借贷限额失败: {error}")

# VIP用户查询借贷限额
result = trader.get_borrow_limit(
    account_id=0,
    coin="BTC",
    is_vip=True
)

if "Ok" in result:
    borrow_limit_vip = result["Ok"]
    print(f"VIP用户BTC借贷限额: {borrow_limit_vip}")

    # 检查VIP详情
    if borrow_limit_vip.get('vip_detail'):
        vip_info = borrow_limit_vip['vip_detail']
        print(f"VIP可用额度: {vip_info['available_loan']}")
        print(f"VIP已用额度: {vip_info['used_loan']}")
else:
    error = result.get("Err", "未知错误")
    print(f"查询VIP用户BTC借贷限额失败: {error}")

# 使用publish方法调用
cmd = {
    "account_id": 1,
    "method": "GetBorrowLimit",
    "coin": "USDT",
    "is_vip": False,
    "sync": True
}
result = trader.publish(cmd)

7.9 账户信息

📊 get_account_info(account_id, extra=None, generate=False)

功能: 获取账户详细信息

参数:

• account_id: 整数，账户ID
• extra: 字典，可选，额外参数
• generate: 布尔值，可选，默认为False，设为True时只生成命令而不执行

返回值:

• 账户详细信息字典（AccountInfo结构），包含:
  • total_mmr: 浮点数，总保证金率
  • total_equity: 浮点数，总权益
  • total_available: 浮点数，总可用余额

📊 get_account_mode(account_id, extra=None, generate=False)

功能: 获取账户模式

参数:

• account_id: 整数，账户ID
• extra: 字典，可选，额外参数
• generate: 布尔值，可选，默认为False，设为True时只生成命令而不执行

返回值:

• 账户模式字符串（AccountMode枚举），可选值:
  • "Classic": 经典账户模式
  • "SpotAndSwap": 现货和合约模式
  • "MultiCurrency": 跨币种保证金模式
  • "Portfolio": 组合保证金模式

📊 set_account_mode(account_id, account_mode, extra=None, generate=False)

功能: 设置账户模式

参数:

• account_id: 整数，账户ID
• account_mode: 字符串或对象，账户模式（同get_account_mode返回值）
• extra: 字典，可选，额外参数
• generate: 布尔值，可选，默认为False，设为True时只生成命令而不执行

返回值:

• 成功时返回 None（设置成功无返回值）
• 失败时返回错误信息

📊 get_user_id(account_id, extra=None, generate=False)

功能: 获取用户ID

参数:

• account_id: 整数，账户ID
• extra: 字典，可选，额外参数
• generate: 布尔值，可选，默认为False，设为True时只生成命令而不执行

返回值:

• 用户ID字符串

---

7.10 交易所特殊说明

🔧 Bitget交易所特殊要求

Bitget交易所在使用某些接口时需要特别注意以下要求：

📝 修改订单接口 (amend_order)

当使用Bitget交易所时，修改订单接口需要在extra参数中传递new_cid字段来设置新的订单cid。注意此方法会返回传入的订单的id，因为交易所返回的id是空，并且经查询，订单id没变。

使用示例:

result = trader.amend_order(
    account_id=0,
    order={
        "symbol": "BTC_USDT",
        "order_id": "123456789",
        "price": 50000.0
    },
    extra={"new_cid": "new_order_cid_001"}
)

📡 WebSocket订阅版本配置

当使用Bitget交易所时，可以在config.toml配置文件的params字段中设置version="v1"来订阅v1版本的WebSocket depth和bbo数据。

配置文件示例:

[[exchanges]]
exchange = "BitgetSwap"
is_colo = false
is_testnet = false
is_unified = false
key = "your_api_key"
passphrase = "your_passphrase"
rebate_rate = 0
secret = "your_secret"
# 可选：为该交易所单独配置代理
proxy = "http://127.0.0.1:7890"
# params用于指定非标参数
#     如 cookie: 网页cookie           bitget swap、coinex swap支持
#         code:   一般配合cookie使用   bitget swap、coinex swap支持
#         org_id: 机构id               bitget swap、spot、margin和coinex swap支持
#         version: 版本    bitget支持，设置为"v1"可订阅v1版本的depth和bbo
params = {version = "v1"}

说明:

• 默认情况下，Bitget交易所使用v2版本的WebSocket API
• 通过设置version = "v1"可以切换到v1版本
• v1版本主要影响depth（深度数据）和bbo（最佳买卖价）的订阅
• 其他WebSocket频道（如订单、持仓等）不受版本设置影响

🔧 其他交易所特殊要求

随着支持的交易所增加，可能会有更多交易所的特殊要求。请关注文档更新，或参考各交易所的官方API文档。

---