Rewards API
Endpoints for the CROPS rewards program - eligibility/onboarding, earning summary, leaderboard, and admin stage management.
Base paths: /rewards (user + onboarding) and /admin/rewards (admin only). See the Rewards feature page for how the program works.
User Endpoints
Authenticated unless marked Public. Wallet ownership is validated against the JWT.
Get My Rewards Summary
GET /rewards/me
Returns the wallet's CROPS total, current stage and rank, a category breakdown, and earned badges.
| Query Param | Type | Required | Description |
|---|---|---|---|
walletAddress | string | Yes | Wallet to summarize |
Get Eligibility
GET /rewards/eligibility
Returns the wallet's eligibility flags (emailVerified, captchaPassed, minBalanceVerified, walletAgeVerified) and overall eligible state.
| Query Param | Type | Required | Description |
|---|---|---|---|
walletAddress | string | Yes | Wallet to check |
Run On-Chain Check
POST /rewards/onchain-check
Re-runs the minimum-balance and wallet-age checks on demand and updates the corresponding eligibility flags.
| Field | Type | Required | Description |
|---|---|---|---|
walletAddress | string | Yes | Wallet to check |
Share Code
POST /rewards/share-code
Records a public referral-code share - awards the social bonus and the Voice badge.
| Field | Type | Required | Description |
|---|---|---|---|
walletAddress | string | Yes | Wallet sharing the code |
Get Award History
GET /rewards/history
Paginated list of individual CROPS awards for a wallet.
| Query Param | Type | Required | Description |
|---|---|---|---|
walletAddress | string | Yes | Wallet to query |
stageId | number | No | Filter by stage |
limit | number | No | Page size |
offset | number | No | Page offset |
Get Leaderboard
GET /rewards/leaderboard
Public. Anonymized CROPS leaderboard. Entries show a stable pseudonym, never the wallet address.
| Query Param | Type | Required | Description |
|---|---|---|---|
mode | string | No | current (active stage) or all (lifetime). |
limit | number | No | Page size (1-200, default 50) |
offset | number | No | Page offset (default 0) |
walletAddress | string | No | If provided, the response also includes your own rank and pseudonym |
Response (abridged):
{
"items": [
{ "rank": 1, "pseudonym": "elegant-sword-quick-planet", "totalPoints": 124500 }
],
"me": { "rank": 47, "pseudonym": "brave-river-cool-leaf", "totalPoints": 12500 }
}
Get Weekly Risers
GET /rewards/weekly-risers
Public. Users who climbed the most current-stage ranks over the last 7 days.
| Query Param | Type | Required | Description |
|---|---|---|---|
limit | number | No | Max entries (max 50, default 10) |
Get Stages
GET /rewards/stages
Public. Lists all reward stages and their configuration (order, window, pool allocation, multipliers).
Onboarding Endpoints
All public (used before a wallet is eligible).
Start Email Verification
POST /rewards/email/start
Sends a 6-digit OTP to the email. Rate-limited to one send per minute per wallet.
| Field | Type | Required | Description |
|---|---|---|---|
walletAddress | string | Yes | Wallet linking the email |
email | string | Yes | Email to verify |
Verify Email
POST /rewards/email/verify
Verifies the OTP and flips emailVerified. Code expires in 10 minutes; max 5 attempts.
| Field | Type | Required | Description |
|---|---|---|---|
walletAddress | string | Yes | Wallet |
code | string | Yes | 6-digit OTP |
Verify CAPTCHA
POST /rewards/captcha/verify
Validates a CAPTCHA token (Turnstile / hCaptcha / reCAPTCHA v3) and flips captchaPassed.
| Field | Type | Required | Description |
|---|---|---|---|
walletAddress | string | Yes | Wallet |
token | string | Yes | CAPTCHA token from the widget |
Admin Endpoints
Base path /admin/rewards. Require an admin token.
| Method | Path | Purpose |
|---|---|---|
| GET | /admin/rewards/stages | List all stages |
| POST | /admin/rewards/stages | Create a stage (name, order, startAt, endAt, poolAllocation, baseEarnRate, stageMultiplier, config) |
| PATCH | /admin/rewards/stages/:id | Update a stage |
| DELETE | /admin/rewards/stages/:id | Delete a stage (blocked if it has awards) |
| GET | /admin/rewards/eligibility/:userId | Fetch a user's eligibility state |
| PATCH | /admin/rewards/eligibility/:userId/flag | Manually set a flag (flag, value) |
| PATCH | /admin/rewards/eligibility/:userId/sybil | Mark/clear sybil flag (flagged, optional reason) |
| PATCH | /admin/rewards/eligibility/:userId/override | Force eligible/block/auto (override: true/false/null) |