Earn Level Quota

Returns the authenticated user's current Earn Level status and estimated season token share.

GET /v1/points/earn-quota
Authorization: Bearer <token>

This endpoint takes no query parameters; it always evaluates the current active epoch (an epoch query parameter is ignored).

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

Response

{
  "earn_level": 2,
  "earn_level_weight": 12,
  "total_points": "15000.00",
  "points_to_next_level": "35000.00",
  "next_level": 3,
  "next_level_weight": 25,
  "estimated_share_pct": "0.000000",
  "season_pool_tokens": 35000000
}

estimated_share_pct is currently always "0.000000" — share estimation depends on the season snapshot engine, which is not implemented.

Response Fields

Field	Type	Description
earn_level	int	Current Earn Level (0–5)
earn_level_weight	int	Distribution weight for current level
total_points	Decimal	Total points accumulated in the current active epoch
points_to_next_level	Decimal	Points needed to reach the next level; "0.00" at L5
next_level	int	Next Earn Level number; at L5 it equals earn_level (5), never null
next_level_weight	int	Weight at next level; at L5 it equals earn_level_weight (120), never null
estimated_share_pct	string	Estimated share of season token pool; currently always "0.000000"
season_pool_tokens	int	user_pool_tokens of the active season with the highest season_no; 0 if no season is active

Earn Level Weights

Level	Points Range	Weight
L0	0 – 999	4
L1	1,000 – 9,999	8
L2	10,000 – 49,999	12
L3	50,000 – 199,999	25
L4	200,000 – 499,999	60
L5	500,000+	120

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/earn-quota",
    headers={"Authorization": f"Bearer {SESSION_TOKEN}"},
)
data = resp.json()

est_tokens = float(data["estimated_share_pct"]) * data["season_pool_tokens"]
print(f"Earn Level: L{data['earn_level']} (weight={data['earn_level_weight']})")
print(f"Estimated tokens: {est_tokens:,.0f}")