Skip to main content
REST API for querying user rewards, Flashpoints, and leaderboard data.

​
Base URL

https://rewards.flashnet.xyz/v1
All endpoints are prefixed with /v1.

​
Rewards

​
Get Rewards Leaderboard

Returns list of users sorted by USDB balance with their rewards info. 
GET /v1/rewards/?limit=100&offset=0
Parameters:
  • limit - Max results (default 100, max 500)
  • offset - Pagination offset
Response: 
{
  "rewards": [
    {
      "pubkey": "02abc...def",
      "usdbBalance": {
        "raw": "10000000000",
        "display": "10000"
      },
      "volumeUtcToday": {
        "swapSats": 5000000,
        "swapCount": 12
      },
      "rewardsBracket": 3,
      "rewardsPercent": 5.0,
      "estimatedSatsToday": 1370
    }
  ],
  "meta": {
    "total": 830,
    "limit": 100,
    "offset": 0
  }
}

​
Get User Summary

Returns current USDB balance, today’s volume, rewards bracket, and projected rewards. 
GET /v1/rewards/:pubkey
Response: 
{
  "pubkey": "02abc...def",
  "usdbBalance": {
    "raw": "10000000000",
    "display": "10000"
  },
  "volumeUtcToday": {
    "swapSats": 5000000,
    "swapCount": 12
  },
  "rewardsBracket": 3,
  "rewardsPercent": 5.0,
  "estimatedSatsToday": 1370
}
Excluded addresses (LP pools, burn addresses) return a 400 status with { "reason": "This address is excluded and does not earn rewards" }. Rewards Brackets:
BracketVolume ThresholdRewards
0$03.5%
1$5004.0%
2$2,5004.5%
3$5,0005.0%
4$10,0005.5%
5$25,0006.0%

​
Get Payout History

Returns paginated list of rewards payouts for a user. 
GET /v1/rewards/:pubkey/payouts?limit=30&offset=0
Parameters:
  • limit - Max results (default 30)
  • offset - Pagination offset
Response: 
{
  "pubkey": "02abc...def",
  "payouts": [
    {
      "day": "2026-02-09",
      "usdbBalance": {
        "raw": 10000000000,
        "display": 10000
      },
      "volume": {
        "swapSats": 5000000
      },
      "rewardsBracket": 3,
      "annualRewardsBps": 500,
      "payoutSats": 1370,
      "status": "paid",
      "txId": "abc123...",
      "createdAt": "2026-02-09T00:05:00Z",
      "paidAt": "2026-02-10T00:05:00Z"
    }
  ],
  "pagination": { "total": 45, "limit": 30, "offset": 0 }
}

​
Flashpoints

​
Get Points Leaderboard

Returns list of users sorted by current Flashpoints with their point balances and volume. 
GET /v1/points/?limit=100&offset=0
Parameters:
  • limit - Max results (default 100, max 500)
  • offset - Pagination offset
Response: 
{
  "points": [
    {
      "pubkey": "02abc...def",
      "currentPoints": 1250000,
      "lifetimePoints": 1500000,
      "rank": 1,
      "projectedDailyPoints": 1236,
      "volumeUtcToday": {
        "swapSats": 5000000,
        "liquiditySats": 0
      }
    }
  ],
  "meta": {
    "total": 830,
    "limit": 100,
    "offset": 0
  }
}

​
Get User Points

Returns Flashpoints balance, rank, and projected daily earnings. 
GET /v1/points/:pubkey
Response: 
{
  "pubkey": "02abc...def",
  "currentPoints": 1250000,
  "lifetimePoints": 1500000,
  "rank": 42,
  "projectedDailyPoints": 1236,
  "volumeUtcToday": {
    "swapSats": 5000000,
    "liquiditySats": 0
  }
}

​
Get Points History

Returns paginated list of point earning events. 
GET /v1/points/:pubkey/history?limit=30&offset=0
Parameters:
  • limit - Max results (default 30)
  • offset - Pagination offset
Response: 
{
  "pubkey": "02abc...def",
  "events": [
    {
      "type": "daily_award",
      "points": 1236,
      "day": "2026-02-09",
      "metadata": {},
      "createdAt": "2026-02-10T00:05:00Z"
    }
  ],
  "pagination": { "total": 45, "limit": 30, "offset": 0 }
}

​
Stats

​
Get Global Stats

Returns system-wide statistics. 
GET /v1/stats
Response: 
{
  "usdb": {
    "totalHolders": 830,
    "totalBalanceRaw": 2500000000000,
    "totalBalanceUsdb": 2500000.00
  },
  "volume24h": {
    "activeTraders": 145,
    "totalVolumeSats": 850000000,
    "totalSwaps": 2340
  },
  "payouts": {
    "pendingCount": 12,
    "pendingSats": 140000,
    "totalPaidSats": 5000000
  },
  "processor": {
    "lastPointsDay": "2026-02-09",
    "lastPayoutDay": "2026-02-09"
  },
  "updatedAt": "2026-02-10T12:34:56Z"
}

​
Health Check

GET /v1/stats/health
Response: 
{
  "status": "healthy",
  "lastPayoutDay": "2026-02-09",
  "lastPointsDay": "2026-02-09"
}
Returns "status": "degraded" if either payout or points processing is behind.

​
Error Handling

Errors return a consistent format: 
{
  "error": "VALIDATION_ERROR",
  "message": "Invalid pubkey format"
}
Common error codes:
  • 400 - Bad request (validation errors, excluded addresses)
  • 404 - Not found
  • 500 - Internal server error