Points Balance

Returns the authenticated user's points summary for a given epoch.

GET /v1/points
Authorization: Bearer <token>

Aliases: GET /v1/points/balance, GET /v1/points/summary

Errors: 401 with a plain-text body (missing bearer token / invalid session) when the session token is missing or invalid.

Query Parameters

Parameter	Type	Required	Description
epoch	integer	No	Epoch number; defaults to the current active epoch

Response

{
  "user_address": "0xAbCd...1234",
  "epoch_number": 3,
  "epoch_status": "active",
  "trading_points": "1250.50",
  "pnl_points": "0.00",
  "holding_points": "0.00",
  "referral_points": "0.00",
  "referral_code": "AXBLADE2026",
  "staking_points": "0.00",
  "total_points": "1250.50",
  "tier": "T1",
  "tier_multiplier": "1.0",
  "earn_level": 1,
  "earn_level_weight": 8,
  "earn_level_points_to_next": "8749.50",
  "rank": null,
  "trading_volume": "2500000.00",
  "trade_count": 47,
  "referral_count": 0,
  "updated_at": "2026-04-15T12:30:00Z"
}

New users with no activity return all point fields as "0.00" and rank as null.

Only trading_points / trading_volume / trade_count have a writer today; pnl_points, holding_points, referral_points and staking_points are always "0.00" (see Overview). rank is currently always null and referral_count always 0 — neither is computed yet.

Response Fields

Field	Type	Description
user_address	string	Bound wallet address; falls back to the session's Canton party ID when no wallet address is bound
epoch_number	int	Epoch the data belongs to
epoch_status	string	Epoch status (pending / active / ended / settled); "active" is returned (with zero balances) if the requested epoch does not exist
trading_points	Decimal	Trading Points (TP) accumulated this epoch
pnl_points	Decimal	PnL Points (PP) accumulated this epoch
holding_points	Decimal	Holding Points (HP) accumulated this epoch
referral_points	Decimal	Referral Points (RP) accumulated this epoch
referral_code	string | null	User's referral code; null if not created
staking_points	Decimal	Staking Points (SP) accumulated this epoch
total_points	Decimal	Sum of all point types
tier	string	Current tier: T1 / T2 / T3, derived from this epoch's trading_volume (below $5M → T1, from $5M → T2, from $100M → T3)
tier_multiplier	string	Tier rate multiplier (e.g., "1.5")
earn_level	int	Current Earn Level (0–5)
earn_level_weight	int	Distribution weight for current level
earn_level_points_to_next	Decimal	Points needed to reach next Earn Level; "0.00" at L5
rank	int | null	Epoch leaderboard rank; currently always null (not computed)
trading_volume	Decimal	Total trade volume this epoch (USD)
trade_count	int	Number of trades this epoch
referral_count	int	Number of referees; currently always 0 (not computed)
updated_at	string	Last update timestamp (ISO 8601); the request time when the user has no balance row yet

Code Examples

Python

import requests

BASE_URL = "https://api.rocky.exchange"
SESSION_TOKEN = "your_session_token"  # from POST /v1/wallet/verify

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

print(f"Total points: {data['total_points']} (Epoch {data['epoch_number']})")
print(f"Tier: {data['tier']} (×{data['tier_multiplier']}), Earn Level: L{data['earn_level']}")
print(f"Rank: {data['rank']}")