Pharos
Trade

GetHistoryOrders - 查询历史订单

查询已完成或已取消的历史订单列表。支持按交易对、时间范围和数量进行过滤。

语法

python
# 查询默认交易对的最近100条历史订单
orders = exchange.GetHistoryOrders()

# 查询指定交易对的历史订单
orders = exchange.GetHistoryOrders("BTC_USDT")

# 查询指定时间后的历史订单
orders = exchange.GetHistoryOrders("BTC_USDT", since_timestamp)

# 查询指定数量的历史订单
orders = exchange.GetHistoryOrders("BTC_USDT", 0, 50)

参数

参数名类型必选默认值说明
symbolstring""交易品种。• 现货格式: BTC_USDT• 永续合约: BTC_USDT.swap• 期权合约: BTC_USDT.BTC-240108-40000-C• 不传则使用当前设置的交易对
sincenumber0起始时间戳(毫秒)。只返回该时间之后的订单
limitnumber100查询订单数量,最多返回指定条数

返回值

返回订单数组(list),每个元素为订单对象(dict),失败返回空列表 []

Order 订单结构

字段类型说明
Idstr订单ID,格式: "交易对,订单号" (如: "BTC-USDT,1547130415509278720")
Symbolstr标准交易对格式 (如: "BTC_USDT", "BTC_USDT.swap")
Pricefloat下单价格(注意市价单可能为0或-1)
Amountfloat下单数量(注意市价单可能为金额而非币数)
DealAmountfloat成交数量
AvgPricefloat成交均价(部分交易所不提供则为0)
Statusstr订单状态: "pending"/"closed"/"canceled"/"unknown"
Typestr订单类型: "buy"/"sell"
Timenumber订单创建时间(毫秒级时间戳)
Offsetnumber合约开平仓方向: 0=开仓, 1=平仓, 2=平买, 3=平卖
ContractTypestr合约代码(现货订单为空字符串)
Infostr交易所原始订单数据(JSON字符串),用于调试

示例

示例1: 查询默认交易对历史订单

python
# 查询当前交易对的最近100条历史订单
orders = exchange.GetHistoryOrders()

Log(f"历史订单数量: {len(orders)}")

for order in orders:
    Log(f"{order['Symbol']} {order['Type']} - {order['Status']}")
    Log(f"  价格: {order['Price']}, 数量: {order['Amount']}")
    Log(f"  成交: {order['DealAmount']}, 均价: {order['AvgPrice']}")

示例2: 查询指定交易对的历史订单

python
# 查询 ETH_USDT 的历史订单
eth_orders = exchange.GetHistoryOrders("ETH_USDT")

Log(f"ETH 历史订单数量: {len(eth_orders)}")

# 查询 BTC 永续合约的历史订单
btc_futures_orders = exchange.GetHistoryOrders("BTC_USDT.swap")

Log(f"BTC 合约历史订单数量: {len(btc_futures_orders)}")

示例3: 查询最近24小时的历史订单

python
import time

# 获取24小时前的时间戳(毫秒)
since = int((time.time() - 24 * 60 * 60) * 1000)

# 查询24小时内的历史订单
orders = exchange.GetHistoryOrders("BTC_USDT", since)

Log(f"最近24小时订单数量: {len(orders)}")

for order in orders:
    order_time = time.strftime('%Y-%m-%d %H:%M:%S', 
                               time.localtime(order['Time'] / 1000))
    Log(f"[{order_time}] {order['Type']} {order['Amount']} @ {order['Price']}")

示例4: 查询最近50条历史订单

python
# 只查询最近50条订单
orders = exchange.GetHistoryOrders("BTC_USDT", 0, 50)

Log(f"查询到 {len(orders)} 条订单")

示例5: 统计历史成交量

python
# 查询指定交易对的历史订单
orders = exchange.GetHistoryOrders("BTC_USDT")

# 统计成交情况
total_buy = 0
total_sell = 0
completed_orders = 0

for order in orders:
    if order["Status"] == "closed":  # 只统计完全成交的
        completed_orders += 1
        if order["Type"] == "buy":  # 买单
            total_buy += order["DealAmount"]
        else:  # 卖单
            total_sell += order["DealAmount"]

Log(f"完成订单数量: {completed_orders}")
Log(f"历史买入总量: {total_buy}")
Log(f"历史卖出总量: {total_sell}")
Log(f"净持仓变化: {total_buy - total_sell}")

示例6: 分析订单成交情况

python
orders = exchange.GetHistoryOrders("BTC_USDT", 0, 100)

total = len(orders)
completed = sum(1 for o in orders if o["Status"] == "closed")
canceled = sum(1 for o in orders if o["Status"] == "canceled")
partial = sum(1 for o in orders if o["Status"] == "canceled" and o["DealAmount"] > 0)

Log(f"订单总数: {total}")
Log(f"完全成交: {completed} ({completed/total*100:.1f}%)")
Log(f"已取消: {canceled} ({canceled/total*100:.1f}%)")
Log(f"部分成交后取消: {partial}")

示例7: 查找特定订单

python
# 根据订单ID查找
target_id = "BTC-USDT,1547130415509278720"
orders = exchange.GetHistoryOrders("BTC_USDT")

for order in orders:
    if order["Id"] == target_id:
        Log(f"找到订单: {order}")
        break

注意事项

  1. 订单状态过滤:只返回已完成(closed)、已取消(canceled)或已拒绝(unknown)的订单,不包括挂单中的订单。

  2. 时间参数精度since 参数为毫秒级时间戳。注意 Gate.io 现货使用秒级时间戳(自动转换)。

  3. 交易所限制

    • Gate.io 合约:不支持 since 时间过滤参数,该参数会被忽略
    • 各交易所对查询数量有不同限制,建议使用 limit 参数控制
  4. 订单ID格式:返回的订单ID统一为 "交易对,交易所订单号" 格式,方便识别。

  5. 市价单注意:市价单的 Price 可能为0或-1,Amount 可能代表金额而非数量。

  6. 默认行为

    • symbol 为空时使用当前设置的交易对
    • since 为0时不进行时间过滤
    • limit 默认为100
  7. 合约字段

    • 现货订单:Offset=0, ContractType=""
    • 合约订单:Offset 表示开平仓方向,ContractType 为合约代码

相关 API