获取团队用户区间数据

API说明

此接口用于查询当前代理商一级直接邀请的直客用户列表，并返回注册时间、邀请人、交易量、手续费、返佣、入金与首次交易/提现标记。

该接口同时返回全层级团队汇总指标，包括团队总人数、查询时间范围内团队用户数和团队交易量。明细列表仅包含当前代理商一级直接邀请的直客用户，不包含下级代理伞下用户明细。

注意事项

1. startTime 和 endTime 使用 yyyy-MM-dd HH:mm:ss 格式，按用户注册时间过滤。
2. 不传 startTime 时默认当前月第一天 00:00:00。
3. 不传 endTime 时默认当前月最后一天 23:59:59。
4. 如果 endTime 晚于当前时间，服务端按当前时间截断查询。
5. 查询开始时间最大支持当前时间往前 30 天，单次查询跨度最大 30 天。
6. partnerUids 和 referralCode 解析出的 UID 都必须属于当前代理商有效伞下。
7. partnerUids 最多 100 个。
8. pageSize 默认值为 100，最大值为 1000。
9. 结果按 register_time desc, uid desc 稳定排序。

认证

这是一个私有接口，需要认证。有关 RESTful API 的使用方式，请参考 公共 > 认证和代码示例 > 合约 > RESTful 私有接口。

请求方法

POST

接口地址

/api/v3/patener/openapi/v1/partner/team/users/range

频率限制

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

请求参数

参数	必填	类型	描述
startTime	false	String	开始时间，格式 yyyy-MM-dd HH:mm:ss，按用户注册时间过滤。
endTime	false	String	结束时间，格式 yyyy-MM-dd HH:mm:ss，按用户注册时间过滤。
pageNo	false	Integer	当前页码，默认 1。
pageSize	false	Integer	每页数量，默认 100，最大 1000。
uid	false	Long	指定伞下用户 UID；主站 DTO 支持该字段，当前渠道侧查询以直客列表和团队范围为准。
referralCode	false	String	邀请码；会解析为邀请人 UID，并校验邀请人属于当前代理商有效伞下。
type	false	String	交易类型：0 合约、1 现货、2 ETF、3 合约 API。
partnerUids	false	List<Long>	限定查询的代理 UID 集合；每个 UID 必须属于当前代理商有效伞下，最大 100 个。

响应参数

参数	类型	描述
code	String	返回状态码。
msg	String	返回信息。
data.total	Long	满足一级直接邀请直客口径的总记录数；下级代理 UID 会被排除。
data.totalUsers	Long	全层级伞下团队总人数，包含当前代理商自己，不受 startTime / endTime 限制。
data.totalUsersInTeam	Long	查询注册时间范围内全层级伞下用户总数，仅返回汇总。
data.totalTradingVolumeInTeam	String	查询交易日期范围内全层级伞下 UID 的总交易量，仅返回汇总。
data.list	Array	一级直接邀请直客明细列表。
data.list[].uid	Long	直客用户 UID。
data.list[].registerTime	String	注册时间，格式 yyyy-MM-dd HH:mm:ss。
data.list[].referralCode	String	邀请人 UID 字符串。
data.list[].deposit	String	是否有入金，Y / N。
data.list[].tradeVolume	BigDecimal	查询日期范围内的全业务线交易量，USDT 口径。
data.list[].tradingFee	BigDecimal	查询日期范围内的全业务线手续费，USDT 口径。
data.list[].rebate	BigDecimal	查询交易类型和日期范围内的返佣。
data.list[].totalDepositAmount	BigDecimal	用户累计入金金额。
data.list[].totalDepositGreaterThanHundred	String	累计入金是否大于 100，Y / N。
data.list[].firstDepositGreaterThan3Hundred	String	首次入金是否大于 300，Y / N。
data.list[].firstWithdrawLessThan2Hundred	String	首次提现是否小于 200，Y / N。
data.list[].firstWithdrawDate	String	首次提现日期，格式 yyyy-MM-dd。
data.list[].firstTradeDate	String	首次交易日期，格式 yyyy-MM-dd。
data.list[].contractBalance	String	合约余额脱敏值；无 Redis 数据时为空或 -。

请求示例

params = {
    "pageNo": 1,
    "pageSize": 100,
    "startTime": "2026-06-01 00:00:00",
    "endTime": "2026-06-30 23:59:59",
    "type": "0"
}

api_url = "/api/v3/patener/openapi/v1/partner/team/users/range"

method = "POST"
response_code, response_data = FuturesRestfulPrivate(params, api_url, method, sec_key, api_key)  # 函数 FuturesRestfulPrivate() 定义在章节（公共 > 认证和代码示例 > 合约 > RESTful 私有接口）

响应示例

{
  "code": "200",
  "msg": "success",
  "data": {
    "total": 9,
    "totalUsers": 183,
    "totalUsersInTeam": 10,
    "totalTradingVolumeInTeam": "1547.4752655",
    "list": [
      {
        "uid": 123392240,
        "registerTime": "2026-06-16 15:42:11",
        "referralCode": "1116350",
        "deposit": "N",
        "tradeVolume": 0,
        "tradingFee": 0,
        "rebate": 0,
        "totalDepositAmount": 0,
        "totalDepositGreaterThanHundred": "N",
        "firstDepositGreaterThan3Hundred": "N",
        "firstWithdrawLessThan2Hundred": "N",
        "firstWithdrawDate": "",
        "firstTradeDate": "",
        "contractBalance": "-"
      }
    ]
  }
}