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

​
Base URL

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

​
Rewards

​
Get User Summary

Returns current balance, token holdings, TWAB, 24h volume, rewards bracket, and projected rewards. 
GET /v1/rewards/:pubkey
Response: 
{
  "pubkey": "02abc...def",
  "balance": {
    "raw": 10000000000,
    "usdb": 10000.00,
    "lastChangeAt": null
  },
  "tokenHoldings": {
    "usdbValueSats": 100000000,
    "otherTokensValueSats": 25000000,
    "tokens": [
      {
        "identifier": "usdb-token-id",
        "symbol": "USDB",
        "balanceRaw": 10000000000,
        "valueSats": 100000000,
        "isUsdb": true
      }
    ]
  },
  "twab": {
    "today": {
      "raw": 9500000000,
      "usdb": 9500.00
    },
    "startBalance": null,
    "source": "hourly_avg"
  },
  "volume24h": {
    "sats": 5000000,
    "swapCount": 12
  },
  "rewardsBracket": 3,
  "rewardsPercent": 5.0,
  "satsPerDay": 1370,
  "updatedAt": "2025-12-30T12:34:56Z"
}
Excluded addresses (LP pools, burn addresses) return an excluded: true flag with zeroed values. 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": "2025-12-29",
      "twab": { "raw": 10000000000, "usdb": 10000.00 },
      "volumeSats": 5000000,
      "rewardsBracket": 3,
      "annualRewardsBps": 500,
      "payoutSats": 1370,
      "status": "paid",
      "txId": "abc123...",
      "createdAt": "2025-12-29T00:05:00Z",
      "paidAt": "2025-12-30T00:05:00Z"
    }
  ],
  "pagination": { "total": 45, "limit": 30, "offset": 0 }
}

​
Get Pending Payouts

Returns pending payouts awaiting processing. 
GET /v1/rewards/pending-payouts?limit=100
Response: 
{
  "payouts": [
    {
      "id": 1234,
      "pubkey": "02abc...def",
      "day": "2025-12-29",
      "amountSats": 1370,
      "createdAt": "2025-12-29T00:05:00Z"
    }
  ],
  "count": 12
}

​
Flashpoints

​
Get User Points

Returns Flashpoints balance, rank, projected daily earnings, and weight breakdown. 
GET /v1/points/:pubkey
Response: 
{
  "pubkey": "02abc...def",
  "currentPoints": 1250000,
  "lifetimePoints": 1500000,
  "rank": 42,
  "projectedDaily": 1236,
  "weight": 1236.5,
  "shareOfPool": 0.01236,
  "breakdown": {
    "usdb": {
      "valueSats": 100000000,
      "weight": 625.0
    },
    "otherTokens": {
      "valueSats": 25000000,
      "weight": 158.1
    },
    "volume": {
      "sats": 5000000,
      "weight": 453.4
    }
  },
  "config": {
    "dailyPool": 100000,
    "usdbMultiplier": 1.25,
    "volumeMultiplier": 1.5
  },
  "updatedAt": "2025-12-30T12:34:56Z"
}

​
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,
      "multiplier": 1.0,
      "day": "2025-12-29",
      "metadata": {},
      "createdAt": "2025-12-30T00:05:00Z"
    }
  ],
  "pagination": { "total": 45, "limit": 30, "offset": 0 }
}

​
Leaderboard

​
Get Leaderboard

Returns ranked users by balance, volume, or points. 
GET /v1/leaderboard?limit=100&sortBy=balance
Parameters:
  • limit - Max results (default 100, max 500)
  • sortBy - balance, volume, or points
Response: 
{
  "leaderboard": [
    {
      "rank": 1,
      "pubkey": "02abc...def",
      "balance": { "raw": 150000000000, "usdb": 150000.00 },
      "volume24h": { "sats": 25000000, "swapCount": 42 },
      "rewardsBracket": 5,
      "rewardsPercent": 6.0,
      "satsPerDay": 24657,
      "points": 4500000
    }
  ],
  "meta": { "total": 830, "limit": 100, "sortBy": "balance" },
  "updatedAt": "2025-12-30T12:34:56Z"
}

​
Get User Rank

Returns a specific user’s position across all leaderboard categories. 
GET /v1/leaderboard/rank/:pubkey
Response: 
{
  "pubkey": "02abc...def",
  "found": true,
  "balance": {
    "raw": 10000000000,
    "usdb": 10000.00,
    "rank": 42,
    "percentile": 95.0
  },
  "volume24h": { "sats": 5000000, "swapCount": 12, "rank": 28 },
  "points": 1250000,
  "pointsRank": 35,
  "rewardsBracket": 3,
  "rewardsPercent": 5.0,
  "satsPerDay": 1370,
  "totalUsers": 830
}
Returns { "pubkey": "...", "found": false, "ranks": null } if the user has no activity.

​
Delegation

Delegation allows wallets to direct a percentage of their rewards to another pubkey. Requires signature verification using Spark’s signMessageWithIdentityKey.

​
Get Delegation Status

Returns active delegation for a wallet, if any. 
GET /v1/delegation/:pubkey
Response (active delegation): 
{
  "active": true,
  "delegatePubkey": "03def...abc",
  "percentage": 50,
  "createdAt": "2025-12-29T12:00:00Z"
}
Response (no delegation): 
{
  "active": false
}

​
Create Delegation

Creates or updates a delegation. Replaces any existing active delegation. 
POST /v1/delegation
Request: 
{
  "delegatorPubkey": "02abc...def",
  "delegatePubkey": "03def...abc",
  "percentage": 50,
  "signature": "3045022100...",
  "message": "flashnet:delegate:v1:03def...abc:50:1735567200000"
}
Message format: flashnet:delegate:v1:{delegatePubkey}:{percentage}:{nonce} The nonce is a Unix timestamp in milliseconds. Must be within 5 minutes of server time. Response: 
{
  "success": true,
  "delegationId": 123
}
Errors:
  • 400 - Invalid pubkey format, invalid message format, percentage mismatch, nonce expired, self-delegation, or excluded address
  • 401 - Invalid signature

​
Revoke Delegation

Revokes an active delegation. 
POST /v1/delegation/revoke
Request: 
{
  "delegatorPubkey": "02abc...def",
  "signature": "3045022100...",
  "message": "flashnet:revoke:v1:1735567200000"
}
Message format: flashnet:revoke:v1:{nonce} Response: 
{
  "success": true,
  "delegationId": 123
}
Errors:
  • 400 - Invalid pubkey format, invalid message format, or nonce expired
  • 401 - Invalid signature
  • 404 - No active delegation found

​
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": {
    "lastEligibilityRefreshAt": "2025-12-30T12:00:00Z",
    "lastPointsAwardAt": "2025-12-30T00:05:00Z",
    "lastPayoutDay": "2025-12-29"
  },
  "updatedAt": "2025-12-30T12:34:56Z"
}

​
Health Check

GET /v1/stats/health
Response: 
{
  "status": "healthy",
  "lastEligibilityRefreshAt": "2025-12-30T12:00:00Z",
  "lastPayoutDay": "2025-12-29"
}
Returns "status": "degraded" if eligibility refresh is older than 2 hours or payout 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)
  • 401 - Unauthorized (invalid signature)
  • 404 - Not found
  • 500 - Internal server error