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)参数
| 参数名 | 类型 | 必选 | 默认值 | 说明 |
|---|---|---|---|---|
| symbol | string | 否 | "" | 交易品种。• 现货格式: BTC_USDT• 永续合约: BTC_USDT.swap• 期权合约: BTC_USDT.BTC-240108-40000-C• 不传则使用当前设置的交易对 |
| since | number | 否 | 0 | 起始时间戳(毫秒)。只返回该时间之后的订单 |
| limit | number | 否 | 100 | 查询订单数量,最多返回指定条数 |
返回值
返回订单数组(list),每个元素为订单对象(dict),失败返回空列表 []。
Order 订单结构
| 字段 | 类型 | 说明 |
|---|---|---|
| Id | str | 订单ID,格式: "交易对,订单号" (如: "BTC-USDT,1547130415509278720") |
| Symbol | str | 标准交易对格式 (如: "BTC_USDT", "BTC_USDT.swap") |
| Price | float | 下单价格(注意市价单可能为0或-1) |
| Amount | float | 下单数量(注意市价单可能为金额而非币数) |
| DealAmount | float | 成交数量 |
| AvgPrice | float | 成交均价(部分交易所不提供则为0) |
| Status | str | 订单状态: "pending"/"closed"/"canceled"/"unknown" |
| Type | str | 订单类型: "buy"/"sell" |
| Time | number | 订单创建时间(毫秒级时间戳) |
| Offset | number | 合约开平仓方向: 0=开仓, 1=平仓, 2=平买, 3=平卖 |
| ContractType | str | 合约代码(现货订单为空字符串) |
| Info | str | 交易所原始订单数据(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注意事项
-
订单状态过滤:只返回已完成(closed)、已取消(canceled)或已拒绝(unknown)的订单,不包括挂单中的订单。
-
时间参数精度:
since参数为毫秒级时间戳。注意 Gate.io 现货使用秒级时间戳(自动转换)。 -
交易所限制:
- Gate.io 合约:不支持
since时间过滤参数,该参数会被忽略 - 各交易所对查询数量有不同限制,建议使用
limit参数控制
- Gate.io 合约:不支持
-
订单ID格式:返回的订单ID统一为
"交易对,交易所订单号"格式,方便识别。 -
市价单注意:市价单的
Price可能为0或-1,Amount可能代表金额而非数量。 -
默认行为:
symbol为空时使用当前设置的交易对since为0时不进行时间过滤limit默认为100
-
合约字段:
- 现货订单:
Offset=0,ContractType="" - 合约订单:
Offset表示开平仓方向,ContractType为合约代码
- 现货订单:
相关 API
- GetOrder - 查询指定订单
- GetOrders - 查询当前挂单
- Buy / Sell - 下单交易
- CancelOrder - 取消订单