查询绑定用户合约成交明细

类型: GET

描述: /v4/broker/trade/futures-trades

API 经纪商查询绑定到本经纪商的用户的合约逐笔成交明细，包含成交额和为经纪商产生的返佣。

所有请求均需 API Key 签名，签名方式见签名生成。

• 调用方须为审核通过的 API 经纪商主账户。独立经纪商子账户的成交查询暂未开放，调用将返回 BROKER_SUB_TRADE_002。
• 不传 startTime / endTime 时默认查询最近 7 天；起止时间间隔最大 90 天。
• 游标分页：fromId 传上一页最后一条的 fillId，direction 控制翻页方向；根据 hasNext / hasPrev 判断是否还有数据。
• fillId、orderId、ts、volume、fee、rebateAmount 等字段均以字符串返回，避免精度丢失。

请求参数

名称	类型	是否必填	默认值	描述	取值范围
uid	long	否	无	绑定用户 UID；不传则查本经纪商全部绑定用户	须为绑定到本经纪商的用户
symbol	string	否	无	交易对，不传查全部；不区分大小写	如 btc_usdt
contractType	int	否	无	合约类型，仅用于筛选，不在响应中返回	1=永续，2~8=交割
orderId	long	否	无	订单号，按单笔订单筛选成交	-
startTime	long	否	7 天前	开始时间（毫秒时间戳）	-
endTime	long	否	当前时间	结束时间（毫秒时间戳）	与 startTime 间隔不超过 90 天
fromId	string	否	无	游标：传上一页最后一条的 fillId 原值	-
direction	string	否	NEXT	翻页方向，不区分大小写	NEXT / PREV
limit	int	否	20	每页条数	1 ~ 100

请求示例

Request

curl -s 'https://api.xt.com/v4/broker/trade/futures-trades?uid=10000001&symbol=btc_usdt&contractType=1&limit=20' \
  -H 'validate-algorithms: HmacSHA256' \
  -H 'validate-appkey: {accessKey}' \
  -H 'validate-recvwindow: 60000' \
  -H 'validate-timestamp: {timestamp}' \
  -H 'validate-signature: {signature}'

响应示例

Response

{
  "rc": 0,
  "mc": "SUCCESS",
  "ma": [],
  "result": {
    "hasPrev": false,
    "hasNext": true,
    "items": [
      {
        "fillId": "7312998452300000001",    // 成交明细 ID，作为下一页 fromId
        "orderId": "6900000000000001",      // 订单 ID
        "uid": "10000001",                  // 绑定用户 UID
        "ts": "1792650669330",              // 成交时间（毫秒）
        "bizType": "futures",               // 业务线：合约
        "symbol": "BTC_USDT",               // 交易对
        "tradeScope": "taker",              // 流动性角色：taker / maker
        "volume": "122.001",                // 成交额（折合 USDT）
        "feeCoin": "USDT",                  // 手续费币种
        "fee": "0.0732",                    // 手续费
        "rebateAmount": "0.0366"            // 本笔为调用方产生的返佣（USDT）
      }
    ]
  }
}

响应字段

名称	类型	描述
hasPrev / hasNext	boolean	是否还有上一页 / 下一页
items	array	成交明细列表
└ fillId	string	成交明细 ID，作为下一页 fromId
└ orderId	string	订单 ID
└ uid	string	绑定用户 UID
└ ts	string	成交时间（毫秒）
└ bizType	string	业务线：futures
└ symbol	string	交易对
└ tradeScope	string	流动性角色：taker / maker
└ volume	string	成交额（折合 USDT）
└ feeCoin	string	手续费币种
└ fee	string	手续费
└ rebateAmount	string	本笔为调用方产生的返佣（USDT）

消息码（mc）

mc	描述
SUCCESS	成功（rc=0）
AUTH_001	缺少 validate-appkey 等签名请求头
AUTH_101	API Key 不存在或已删除
AUTH_102	API Key 未激活
AUTH_103	签名错误，请检查签名明文拼接
AUTH_104	请求 IP 不在 API Key 绑定的 IP 列表中
AUTH_105	请求已过期：本机与服务器时间偏差超过 recvWindow
COSMOS_1056	结束时间不能早于开始时间
COSMOS_1057	查询时间跨度不能超过 90 天（指 startTime 与 endTime 的间隔）
BROKER_SUB_TRADE_001	无权查看该用户的成交明细（uid 未绑定到本经纪商）
BROKER_SUB_TRADE_002	独立经纪商子账户成交查询暂未开放
参数格式错误: {参数名}	入参类型或格式不合法（如 orderId 不是数字、direction 取值非法）