Referral Status

Returns the user's dual referral status — both as a referrer and as a referee.

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

Response

{
  "as_referrer": {
    "has_code": true,
    "code": "4DDDC2D4",
    "code_created_at": 1772010604000,
    "total_referrals": 3,
    "referees": [
      {
        "address": "0xabc...",
        "bound_at": 1770000000000
      }
    ]
  },
  "as_referee": {
    "is_bound": false,
    "referrer_address": null,
    "referrer_code": null,
    "bound_at": null
  }
}

Response Fields

as_referrer

Field	Type	Description
has_code	bool	Whether the user has created a referral code
code	string | null	Referral code (8-character uppercase hex)
code_created_at	int64 | null	Code creation timestamp (milliseconds)
total_referrals	int64	Total number of referred users
referees	array	List of referred users (up to 50 most recent, newest first)
referees[].address	string | null	Referee's wallet address (null if the referee's session had no wallet address)
referees[].bound_at	int64	Binding timestamp (milliseconds)

as_referee

Field	Type	Description
is_bound	bool	Whether the user is bound to a referrer
referrer_address	string | null	Referrer's wallet address
referrer_code	string | null	The referral code the user is bound to
bound_at	int64 | null	Binding timestamp (milliseconds)

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
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"

resp = requests.get(
    f"{BASE_URL}/v1/referral/status",
    headers={"Authorization": f"Bearer {JWT_TOKEN}"},
)
data = resp.json()

# As referrer
ref = data["as_referrer"]
if ref["has_code"]:
    print(f"Referral code: {ref['code']}, Total referrals: {ref['total_referrals']}")
    for r in ref["referees"]:
        print(f"  Referee: {r['address']}")

# As referee
referee = data["as_referee"]
if referee["is_bound"]:
    print(f"Bound to: {referee['referrer_code']} ({referee['referrer_address']})")