Season Distribution

Returns all token distribution records for a given season — every user, both pools. The result is not filtered to the caller.

GET /v1/points/distribution/:season_id

No authentication required.

Errors: 400 with the plain-text body invalid season_id when the path parameter is not a UUID. An unknown (but well-formed) season_id returns [].

Path Parameters

Parameter	Type	Description
season_id	UUID	Season ID (obtained from GET /v1/points/seasons)

Response

Returns an array of every record for the season, sorted by token_amount descending. A user may have up to two records — one for the user pool and one for the mm (market maker) pool. Returns [] if the season snapshot has not been taken yet — and, because the snapshot/distribution engine is not implemented (see Overview), currently always [].

[
  {
    "id": "f1e2d3c4-...",
    "season_id": "a1b2c3d4-...",
    "user_address": "0xabcd...1234",
    "pool_type": "user",
    "weighted_points": "48500.00",
    "share_pct": "0.000023000000",
    "token_amount": "805.00",
    "claim_status": "pending",
    "claim_deadline": "2026-03-05T00:00:00Z",
    "claim_nonce": 1,
    "claimed_at": null,
    "claim_tx_hash": null,
    "created_at": "2026-02-03T00:00:00Z"
  }
]

Records are sorted by token_amount descending (not by pool_type).

Response Fields

Field	Type	Description
id	string	Distribution record UUID — used in the claim endpoint
season_id	string	Season UUID
user_address	string | null	User's wallet address
pool_type	string	user (regular pool, default) or mm (market maker pool)
weighted_points	Decimal	User's points × Earn Level weight (2 decimals)
share_pct	Decimal	Share of pool (12-decimal precision)
token_amount	Decimal	Token amount allocated (human-readable, not wei; 2 decimals)
claim_status	string	Stored claim status; defaults to pending. claimed / expired are the intended follow-on values but are not enforced by a DB constraint
claim_deadline	string | null	Claim deadline (ISO 8601); null if unset. No fixed 30-day window is pinned in code
claim_nonce	int	Nonce intended for the EIP-712 claim signature (default 0)
claimed_at	string | null	Timestamp when claimed on-chain
claim_tx_hash	string | null	On-chain claim transaction hash
created_at	string	Record creation time (ISO 8601)

Distribution Formula

Intended formula — not implemented yet:

weighted_points = raw_total_points × earn_level_weight
share_pct       = user_weighted_points / Σ(all_users_weighted_points)
token_amount    = season_pool_tokens × share_pct

Code Examples

Python

import requests

BASE_URL = "https://api.rocky.exchange"
SEASON_ID = "a1b2c3d4-..."

resp = requests.get(f"{BASE_URL}/v1/points/distribution/{SEASON_ID}")
records = resp.json()

for rec in records:
    print(f"{rec['user_address']} pool: {rec['pool_type']}, Tokens: {rec['token_amount']}, Status: {rec['claim_status']}")
    if rec["claim_status"] == "pending":
        print(f"  Claim by: {rec['claim_deadline']}, distribution_id: {rec['id']}")