获取交易详情（3天）

API说明

此接口允许查询过去三天的全面交易详情摘要，包括订单状态、持仓详情、费用、盈亏、杠杆、保证金等关键交易指标。

注意：交易详情数据只能通过 RESTful API 获取。

注意事项

如果某个订单已成交，请求参数"originalType"可能会产生误导，因为即使请求指定类型（plan或execute），接口返回的响应是相同的。用户不应仅依赖此参数来确定订单性质，应验证额外的订单详情（订单状态、持仓ID、订单ID）以确保准确性。
响应参数"total"也可能产生误导，因为在已成交订单的情况下，即使指定了特定类型，execute和plan订单都会被包含在内。建议不要仅依赖此参数。
未成交订单不会在此接口中显示。但是，如果未成交订单被取消，取消将通过此接口反映出来。

认证

这是一个私有接口，需要认证。有关使用RESTful API的详细信息，请参考简介 > 认证和代码示例 > 合约 > RESTful私有接口。

请求方法

GET

接口地址

/v1/perpum/orders/deals

频率限制

该接口的调用频率限制为：每个 IP 和用户 ID 每秒最多请求10次。
此外，该接口还受到全局频率限制的约束。
有关"全局速率限制"和"API限频策略"的详细信息，请参阅“频率限制”部分，跳转

请求参数

参数	必填	类型	描述
page	false	Integer	当前页码
pageSize	false	Integer	每页响应数量
originType	false	String	初始订单类型：execute：市价单plan：用于不同计划订单，包括限价单、触发限价单、带SL/TP的限价单、带SL/TP的触发限价单、触发市价单、带SL/TP的触发市价单planTrigger：计划触发订单
instrument	true	String	交易品种的基础货币（例如，BTC或btc）。此参数不区分大小写。注意：对于以数字开头的交易品种（例如1000PEPE），大写和小写格式都有效。
positionModel	false	Integer	持仓持仓模式：0：逐仓，1：全仓

响应参数

参数	类型	描述
closePrice	BigDecimal	持仓平仓价格
userId	Long	合约账户用户ID
closedPiece	BigDecimal	已平仓合约
createdDate	Long	订单创建的时间戳
currentPiece	BigDecimal	当前合约数量
direction	String	交易方向：做多(long)/做空(short)
fee	BigDecimal	费用
feeRate	BigDecimal	手续费率
fundingSettle	BigDecimal	资金费率结算金额
hedgeId	Long	对冲ID
indexPrice	BigDecimal	指数价格/最新价格
instrument	String	交易品种的基础货币，例如BTC或ETH
leverage	BigDecimal	持仓杠杆率
liquidateBy	String	平仓或开仓事件类型
margin	BigDecimal	为此持仓分配的保证金
netProfit	BigDecimal	净利润
openId	Long	持仓ID
openPrice	BigDecimal	订单实际成交的开仓价格
orderId	Long	订单ID
orderPrice	BigDecimal	用户指定的订单价格
orderStatus	String	订单状态：unFinish：未成交，part：部分成交，Finish：完全成交，Cancel：已取消
originalType	String	原始订单类型
positionMargin	BigDecimal	持仓保证金
positionModel	Integer	持仓持仓模式：0：逐仓，1：全仓
quantity	BigDecimal	基于quantityUnit 指定订单数量：当 quantityUnit = 0 时，数量以计价货币计量（例如，BTC-USDT 中的 USDT）；当 quantityUnit = 1 时，数量以合约张数计量；当 quantityUnit = 2 时，数量以基础货币计量（例如，BTC-USDT 中的 BTC）。
quantityUnit	Integer	用于指定订单数量的计量单位： 0：以计价货币计价（例如，BTC-USDT 合约中的 USDT）； 1：以合约张数计价； 2：以基础货币计价（例如，BTC-USDT 合约中的 BTC）。
settlementId	Long	交易品种手ID
status	String	交易状态：open：活跃持仓，close：已平仓持仓，cancel：已取消订单
takerMaker	Integer	标识交易是吃单还是挂单交易：1-吃单，2-挂单
totalPiece	BigDecimal	合约总数量
updatedDate	Long	最新交易更新的时间戳
thirdOrderId	String	用户分配的自定义订单ID
id	Long	ID
contractType	Integer	合约类型：1：永续合约
baseSize	Integer	合约规模
isProfession	Integer	（用户可忽略）
processStatus	Integer	匹配服务器处理状态：0：等待，1：处理中，2：成功，3：失败
source	String	来源：web/api
total	Integer	交易总数

请求示例

以下Python代码展示了如何获取过去三天BTC的交易详情。

注意：完整代码示例请参考简介 > 认证和代码示例 > 合约 > RESTful私有接口。

params = {
    "instrument" : "btc",
    "positionModel" : 0,
    "originType" : "plan",
    "page" : 1,
    # "pageSize" : 1,
    }
 
api_url = "/v1/perpum/orders/deals"
request_url = f'{base_url}{api_url}'
 
method = "GET"
response_code, response_data = FuturesRestfulPrivate(params, api_url, method, sec_key, api_key)    # the function FuturesRestfulPrivate() is defined in section (Introduction > Authentication & Code Snippet > Futures > RESTful Private Interface)

注意：完整Java代码示例请参考简介 > 认证和代码示例 > 合约 > RESTful私有接口。

响应示例

以下是上述Python请求返回的示例响应。实际响应包含73个交易历史。为简洁起见，以下仅显示一个交易历史：

{'code': 0,
 'data': {'nextId': 0,
  'prevId': 0,
  'rows': [{'baseSize': 0.001,
 'closePrice': 0,
 'closedPiece': 0,
 'contractType': 1,
 'createdDate': 1741325037000,
 'currentPiece': 0,
 'direction': 'long',
 'fee': '0',
 'feeRate': '0',
 'fundingFee': '0',
 'fundingSettle': 0,
 'id': 20865618454160389,
 'instrument': 'BTC',
 'isProfession': 0,
 'leverage': 1,
 'liquidateBy': 'moveStopProfitAndLoss',
 'margin': 87.90975,
 'netProfit': 0,
 'openId': 2435521222632288678,
 'openPrice': 87909.75,
 'orderId': 20865172723909637,
 'orderPrice': 0,
 'orderStatus': 'cancel',
 'originalType': 'moveStopProfitLoss',
 'positionMargin': 0.0,
 'positionModel': 0,
 'processStatus': 1,
 'quantity': 1,
 'quantityUnit': 1,
 'source': 'api',
 'status': 'close',
 'takerMaker': 1,
 'thirdOrderId': '07-9-16',
 'totalPiece': 1,
 'triggerPrice': 0,
 'triggerType': 1,
 'updatedDate': 1741328437000,
 'userId': 1162061}......],
  'total': 73},
 'msg': ''}

API说明​

注意事项​

认证​

请求方法​

接口地址​

频率限制​

请求参数​

响应参数​

请求示例​

响应示例​