Points System Overview
Sparky Points reward trading activity. Points accrue within an Epoch; at the end of a Season (a range of epochs) a token pool is split among users by weighted points.
All paths below are relative to https://api-avax.<sparky-domain>/api/v1 (one deployment per chain — see Base URLs).
All points endpoints return Sparky's ApiResponse envelope:
{ "success": true, "data": { ... }, "error": null, "timestamp": 1776330222 }
On failure success is false and error is { "code", "message" }; note these handlers return the envelope with HTTP 200 even on error, so check success rather than the status code.
Epoch & season structure
Season (start_epoch .. end_epoch)
├── Epoch n
├── Epoch n+1
└── ...
Epoch and season boundaries are database configuration, not code constants — read GET /epochs and GET /points/seasons.
Point types
| Type | Code | Source | Config keys (per epoch) |
|---|---|---|---|
| Trading Points | trading | Every fill: volume / 1000 × rate(tier, maker/taker), capped daily and weekly | tp_t*_maker/taker, tp_daily_cap (5000), tp_weekly_cap (25000) |
| PnL Points | pnl | Realised PnL on close, decayed for fast flips | pp_amount_rate (2.5), pp_return_cap (0.20), pp_daily_cap (20000) |
| Holding Points | holding | Per-minute accrual on open position value | hp_rate_per_min (0.00003), hp_daily_cap (40000) |
| Referral Points | referral | When a referee reaches rp_trigger_min_volume ($1,000) within rp_trigger_days (7) of binding: referrer and referee each get rp_*_amount (10), daily cap 100 | |
| Staking Points | staking | Reserved; no staking product is live |
Values in parentheses are the schema defaults of points_config; operators can change them per epoch.
Tier system (Trading Points rate)
The Trading Points rate depends on the user's VIP fee tier, not on epoch volume:
| Points tier | VIP level | Maker rate | Taker rate |
|---|---|---|---|
| T1 | VIP0 | 1.2 TP / $1,000 | 0.8 TP / $1,000 |
| T2 | VIP1–VIP2 | 1.5 TP / $1,000 | 1.0 TP / $1,000 |
| T3 | VIP3–VIP5 | 2.0 TP / $1,000 | 1.3 TP / $1,000 |
Rates are the epoch defaults; GET /points/tier returns the live values and POST /points/simulate applies them to a hypothetical trade.
Earn Level
Total points in the epoch determine the Earn Level and its distribution weight:
| Level | Points | 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 |
Live configuration: GET /points/earn-level-config. The Earn Level also sets the user's daily quota on Earn products — see GET /points/earn-quota.
Token distribution
weighted_points = total_points × earn_level_weight
share_pct = weighted_points / Σ weighted_points (per pool)
token_amount = pool_tokens × share_pct
Each season has a user_pool_tokens and an mm_pool_tokens pool. After the season snapshot, per-user rows appear in GET /points/distribution/:season_id and can be claimed with an EIP-712 signature from POST /points/claim/:distribution_id before claim_deadline.
Endpoints
Public
| Method | Endpoint | Description |
|---|---|---|
| GET | /epochs | List epochs |
| GET | /points/seasons | List seasons |
| GET | /points/earn-level-config | Earn Level table |
| GET | /points/leaderboard | Epoch leaderboard |
| GET | /points/leaderboard/daily | Daily increment leaderboard |
Protected (JWT)
| Method | Endpoint | Description |
|---|---|---|
| GET | /points, /points/balance, /points/summary | User points summary |
| GET | /points/history | Points events |
| GET | /points/tier | Tier info |
| GET | /points/earn-quota | Earn Level quota |
| POST | /points/simulate | Simulate points for a trade |
| GET | /points/distribution/:season_id | Own distribution rows |
| POST | /points/claim/:distribution_id | Claim signature |
Real-time updates are pushed on the points WebSocket channel (User data).