Get Affiliate Team Direct User Range

API Description

This API queries the list of direct customer users invited by the current partner at the first invitation level.

The response includes each user's registration time, inviter, trading volume, trading fee, rebate, deposit status, first trade marker, first withdrawal marker, and related deposit/withdrawal indicators.

The API also returns full-level team summary metrics, including total team users, team users within the query time range, and team trading volume. The detailed list only contains direct customer users invited by the current partner. It does not include users under downstream partners.

Precautions

1. startTime and endTime use the yyyy-MM-dd HH:mm:ss format and filter by user registration time.
2. If startTime is not provided, it defaults to the first day of the current month at 00:00:00.
3. If endTime is not provided, it defaults to the last day of the current month at 23:59:59.
4. If endTime is later than the current server time, the server truncates the query end time to the current time.
5. The earliest supported startTime is 30 days before the current time. A single query can cover at most 30 days.
6. Every UID in partnerUids, and the UID resolved from referralCode, must belong to the current partner's valid downline.
7. partnerUids supports at most 100 UIDs.
8. pageSize defaults to 100 and cannot exceed 1000.
9. Results are sorted stably by register_time desc, uid desc.

Authentication

This is a private interface and requires authentication. For details on using the RESTful API, refer to Introduction > Authentication & Signature.

Request Method

POST

Endpoint

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

Frequency Limit

The frequency limit for this interface is 5 requests/s per IP and user ID. In addition to this per-interface limit, a global rate limit is also enforced.

For detailed information on Global rate limits and API Rate Limiting Policy, please refer to the "Frequency Limit" section at click here

Request Parameters

Parameter	Mandatory	Type	Description
startTime	false	String	Start time, formatted as yyyy-MM-dd HH:mm:ss, filtered by user registration time.
endTime	false	String	End time, formatted as yyyy-MM-dd HH:mm:ss, filtered by user registration time.
pageNo	false	Integer	Current page number. Default: 1.
pageSize	false	Integer	Number of records per page. Default: 100. Maximum: 1000.
uid	false	Long	Specify a downline user UID. The main-site DTO supports this field; the current channel-side query is based on the direct customer list and team scope.
referralCode	false	String	Referral code. Resolved to the inviter UID and validated to belong to the current partner's valid downline.
type	false	String	Trade type: 0 Futures, 1 Spot, 2 ETF, 3 Futures API.
partnerUids	false	List<Long>	Limit the query to a set of partner UIDs. Each UID must belong to the current partner's valid downline. Maximum: 100.

Response Parameters

Parameter	Type	Description
code	String	Response status code.
msg	String	Response message.
data.total	Long	Total records matching the first-level direct customer scope. Downstream partner UIDs are excluded.
data.totalUsers	Long	Total users across all downline levels, including the current partner. Not limited by startTime / endTime.
data.totalUsersInTeam	Long	Total users across all downline levels within the registration time range. Summary only.
data.totalTradingVolumeInTeam	String	Total trading volume across all downline UIDs within the trade date range. Summary only.
data.list	Array	Detailed list of first-level direct customer users.
data.list[].uid	Long	Direct customer user UID.
data.list[].registerTime	String	Registration time, formatted as yyyy-MM-dd HH:mm:ss.
data.list[].referralCode	String	Inviter UID as a string.
data.list[].deposit	String	Whether the user has deposited: Y / N.
data.list[].tradeVolume	BigDecimal	Total trading volume across all business lines within the query date range, in USDT.
data.list[].tradingFee	BigDecimal	Total trading fees across all business lines within the query date range, in USDT.
data.list[].rebate	BigDecimal	Rebate within the query trade type and date range.
data.list[].totalDepositAmount	BigDecimal	User's cumulative deposit amount.
data.list[].totalDepositGreaterThanHundred	String	Whether cumulative deposit exceeds 100: Y / N.
data.list[].firstDepositGreaterThan3Hundred	String	Whether the first deposit exceeds 300: Y / N.
data.list[].firstWithdrawLessThan2Hundred	String	Whether the first withdrawal is less than 200: Y / N.
data.list[].firstWithdrawDate	String	First withdrawal date, formatted as yyyy-MM-dd.
data.list[].firstTradeDate	String	First trade date, formatted as yyyy-MM-dd.
data.list[].contractBalance	String	Masked futures balance. Empty or - when no Redis data is available.

Request Example

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)  # function FuturesRestfulPrivate() is defined in section (Introduction > Authentication & Code Snippet > Futures > RESTful Private Interface)

Response Example

{
  "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": "-"
      }
    ]
  }
}