queryReferrals
Retrieve paginated list of friend referral invitations for your Bybit account. Use cursor parameter to navigate through all records.
Instructions
Query invited users (referrals) for the authenticated account. Use master or sub-account's API key.
Important notes (from official Bybit V5 documentation):
Returns a list of users invited through friend referral program
Supports cursor-based pagination for efficient data retrieval
Only returns Friend referral (scene=2) invitation records
Results are sorted by invitation ID in descending order (newest first)
Maximum page size is 100 records per request
Default page size is 20 records if not specified or invalid
Process Flow:
Extract UID from BGW metadata (authentication context)
Validate UID (must be > 0)
Set default page size (20) if not provided or out of range [1-100]
Parse cursor (must be valid int64 string or empty)
Call domain layer QueryReferrals with scene=Friend (2)
Convert domain results to proto response
Set nextCursor if more pages available
Return records with pagination info
Pagination Mechanism:
Cursor-based pagination: Use
nextCursorfrom response to fetch next pageInitial request: Don't provide cursor parameter (or empty string)
Subsequent requests: Use
nextCursorvalue from previous responseWhen
nextCursoris empty in response, there are no more pagesSystem fetches (size + 1) records internally to determine if next page exists
Status Values:
0: Common/Active (AVAILABLE) - referral relationship is active1: Closed/Inactive (UNAVAILABLE) - referral relationship is closedIf status parameter not provided, returns all statuses
Response Data:
Each record includes invitation ID, invitee UID, status, and timestamps
invitee_uid(user_id): The UID of the invited usercreated_at/updated_at: Unix timestamps in seconds
Business Rules:
Only shows Friend referral invitations (scene=2, constant biz.Friend)
Must be authenticated with valid API key
UID extracted from BGW metadata (ParseBGWParameter)
Invalid or missing UID (uid <= 0) returns permission denied error
Cursor must be valid integer string (parseable as int64) or empty
Page size auto-adjusted: if <= 0 or > 100, defaults to 20
Use Cases:
Query all users invited by the authenticated account
Check referral invitation status
Track referral program performance
Export referral data for analysis
Monitor active vs closed referral relationships
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cursor | No | ||
| size | No | ||
| status | No |