Referral Logs

Paginated query of the current user's referral operation history.

GET /v1/referral/logs
Authorization: Bearer <token>

Query Parameters

Parameter	Type	Default	Description
page	int	1	Page number; values below 1 are clamped to 1
page_size	int	20	Items per page; clamped to the range 1–100

There is no action filter — all of the user's log entries are returned, newest first. Unknown query parameters are ignored; a non-integer page/page_size returns 400.

Action Values

Value	target_address	referral_code	amount	Description
create_code	null	the new code	null	Created a referral code
bind	referrer's address	the code bound	null	Bound to a referral code
unbind	previous referrer's address	the code unbound	null	Unbound from a referral code
commission_accrued	null	null	commission (USDT)	Commission credited to the referrer's pending balance for a referee fill
claim	null	null	claimed amount (USDT)	Claimed off-chain earnings

There is no rebind action (rebinding is not supported).

Response

{
  "logs": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "action": "create_code",
      "target_address": null,
      "referral_code": "4DDDC2D4",
      "amount": null,
      "old_value": null,
      "new_value": null,
      "created_at": 1772010604000
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "action": "bind",
      "target_address": "0xabc...",
      "referral_code": "4DDDC2D4",
      "amount": null,
      "old_value": null,
      "new_value": null,
      "created_at": 1772020000000
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440002",
      "action": "claim",
      "target_address": null,
      "referral_code": null,
      "amount": "45.00",
      "old_value": null,
      "new_value": null,
      "created_at": 1772100000000
    }
  ],
  "total": 3,
  "page": 1,
  "page_size": 20
}

Response Fields

Field	Type	Description
logs	array	List of log entries
logs[].id	string	Unique log ID (UUID)
logs[].action	string	Action type
logs[].target_address	string | null	Related address (the referrer's address for bind/unbind)
logs[].referral_code	string | null	Related referral code
logs[].amount	string | null	Amount involved (USDT, decimal string rounded to 2 dp) — set for claim and commission_accrued
logs[].old_value	null	Reserved; always null currently
logs[].new_value	null	Reserved; always null currently
logs[].created_at	int64	Timestamp (milliseconds)
total	int64	Total number of matching records
page	int	Current page number
page_size	int	Items per page (after clamping)

Error Codes

Error format. Referral endpoints return errors as a plain-text body (text/plain) containing the message shown in the Message column, not a JSON object. A missing or invalid Authorization: Bearer session token returns 401 with missing bearer token / invalid session.

HTTP	Message	Description
400	(query rejection text)	page or page_size is not an integer
401	missing bearer token / invalid session	Missing, expired or revoked session token
500	(database error text)	Server error

Code Examples

Python

import requests

BASE_URL = "https://api.rocky.exchange"
JWT_TOKEN = "your_jwt_token"

# Query referral logs with pagination
resp = requests.get(
    f"{BASE_URL}/v1/referral/logs",
    headers={"Authorization": f"Bearer {JWT_TOKEN}"},
    params={"page": 1, "page_size": 20},
)
data = resp.json()

print(f"Total: {data['total']} (Page {data['page']}/{(data['total'] - 1) // data['page_size'] + 1})")
for log in data["logs"]:
    print(f"  [{log['action']}] code={log['referral_code']} addr={log['target_address']} at={log['created_at']}")