获取历史订单（7天）

API说明

此接口提供过去七天的历史订单记录。用户可以使用页码、页面大小、订单类型和交易合约等参数筛选结果。响应提供了全面的订单详情，包括状态、保证金、杠杆率和订单规模。

注意：历史订单数据只能通过 RESTful API 获取。

注意事项

如果未指定参数，此接口默认将返回过去七天内最近10个历史订单记录。
此接口仅返回已执行（即已进入交易）的订单。

认证

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

请求方法

GET

接口地址

/v1/perpum/orders/history

频率限制

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

请求参数

参数	必填	类型	描述
page	false	Integer	当前页码
pageSize	false	Integer	每页结果数。注意：如果未指定，接口将返回过去七天内最近10个订单的信息。
originType	false	String	初始订单类型：plan/planTrigger/execute execute：市价单 plan：用于不同计划订单，包括限价单、触发限价单、带SL/TP的限价单、带SL/TP的触发限价单、触发市价单、带SL/TP的触发市价单 planTrigger：计划触发订单
instrument	false	String	注意：USDT 合约只需传入基础货币名称，如 `BTCUSDT` 传 `BTC` 即可；USDC 合约请传完整交易对，如 `BTC_USDC`。此参数不区分大小写。注意：对于以数字开头的交易品种（例如1000PEPE），大写和小写格式都有效。

响应参数

参数	类型	描述
userId	Long	合约账户用户ID
baseSize	BigDecimal	基础货币订单规模
completeUsdt	BigDecimal	USDT / USDC 交易金额
createdDate	Long	订单创建的时间戳
currentPiece	BigDecimal	当前持有的合约数量
direction	String	交易方向：做多(long)/做空(short)
entrustUsdt	BigDecimal	USDT / USDC 订单规模
havShortfall	Boolean	表示用户是否有清算风险
hedgeId	Long	关联对冲ID
indexPrice	BigDecimal	指数价格/最新价格
instrument	String	交易品种的基础货币，例如BTC或ETH
leverage	BigDecimal	持仓杠杆率
liquidateBy	String	开仓和平仓事件类型：Manual
margin	BigDecimal	持仓使用的保证金
openId	Long	持仓ID
orderId	Long	ID（用户可忽略）
orderPrice	BigDecimal	用户设置的订单价格。注意：市价单情况下忽略
orderStatus	String	订单状态：unFinish：未成交part：部分成交Finish：完全成交Cancel：已取消
originalType	String	原始订单类型
posType	String	持仓类型：plan/planTrigger/execute
positionModel	Integer	持仓模式：0：逐仓，1：全仓
quantity	BigDecimal	基于quantityUnit 指定订单数量：当 quantityUnit = 0 时，数量以计价货币计量（例如，BTC-USDT 中的 USDT / BTC-USDC 中的USDC）；当 quantityUnit = 1 时，数量以合约张数计量；当 quantityUnit = 2 时，数量以基础货币计量（例如，BTC-USDT 中的 BTC）。
quantityUnit	Integer	用于指定订单数量的计量单位： 0：以计价货币计价（例如，BTC-USDT 合约中的 USDT / BTC-USDC 合约中的USDC）； 1：以合约张数计价； 2：以基础货币计价（例如，BTC-USDT 合约中的 BTC）。
status	String	状态：open/close
totalPiece	String	合约总数量
updatedDate	Date	最新交易更新的时间戳
thirdOrderId	String	自定义订单ID
tradePiece	Integer	要交易的合约
stepMarginVersion	Integer	（用户可忽略）
id	Long	订单ID
cancelPiece	Integer	取消的合约数量
contractType	Integer	合约类型：1：U本位永续合约
source	String	来源：web/api
avgPrice	String	平均成交价格
triggerPrice	String	永续合约计划订单的触发价格
triggerType	Integer	指定触发价格满足时的订单类型：0：限价单，1：市价单
thirdOrderId	String	用户分配的自定义订单ID

请求示例

以下Python代码展示了如何获取过去七天的历史订单记录。

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

params = {
    "page" : 1,
    "pageSize" : 12,
    "originType" : "execute",
    "instrument" : "BTC",
    }
api_url = "/v1/perpum/orders/history"
method = "GET"
response_code, response_data = FuturesRestfulPrivate(params, api_url, method, sec_key, api_key)   # function FuturesRestfulPrivate() is defined in section (Introduction > Authentication & Code Snippet > Futures > RESTful Private Interface)

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

响应示例

以下是上述Python请求返回的示例响应。该响应包含过去七天内最多12个订单。为简洁起见，下面仅显示一个订单：

{'code': 0,
 'data': {'nextId': 0,
  'prevId': 0,
  'rows': [{'avgPrice': '86070',
    'baseSize': '0',
    'cancelPiece': 0,
    'completeUsdt': '86.07',
    'contractType': 1,
    'createdDate': 1740915577000,
    'currentPiece': '1',
    'direction': 'short',
    'entrustUsdt': '86.07',
    'havShortfall': False,
    'hedgeId': 20811504068180998,
    'id': '33308753751538235',
    'indexPrice': '86077.2',
    'instrument': 'BTC',
    'leverage': '1',
    'liquidateBy': 'manual',
    'margin': '13.8267076',
    'openId': 2435521222632111503,
    'orderId': 2882616995,
    'orderPrice': '0',
    'orderStatus': 'finish',
    'originalType': 'execute',
    'posType': 'execute',
    'positionModel': 0,
    'quantity': '100',
    'quantityUnit': 0,
    'source': 'api',
    'status': 'open',
    'stepMarginVersion': 0,
    'thirdOrderId': 'historyoforder',
    'totalPiece': '1',
    'tradePiece': 1,
    'triggerPrice': '84400',
    'triggerType': 0,
    'updatedDate': 1740915577000,
    'userId': 1162061},.........{....}],
  'total': 114},
 'msg': ''}

API说明​

注意事项​

认证​

请求方法​

接口地址​

频率限制​

请求参数​

响应参数​

请求示例​

响应示例​