Skip to main content
REST API for querying user rewards, configuring reward endorsements, reading Flashpoints data, and checking system stats.

​
Base URL

https://rewards.flashnet.xyz
All endpoints are prefixed with /v1. Swagger docs are available at /docs.

​
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:
BracketvolumeUtcToday.swapSats ThresholdRewards
0>= 03.5%
1>= 5000004.0%
2>= 25000004.5%
3>= 50000005.0%
4>= 100000005.5%
5>= 250000006.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,
      "rewardsPayoutSats": 1020,
      "endorsementsPayoutSats": 350,
      "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 }
}
payoutSats is the sum of rewardsPayoutSats and endorsementsPayoutSats.

​
Endorsements

Endorsements let a pubkey direct part of its future daily rewards payout to one or more recipient pubkeys.

​
Canonical YAML Templates (for Signing)

Create and update both use action: upsert. The API creates a new record or updates the existing (endorser, to) pair. Create endorsement template: 
kind: rewards_endorsement
version: 1
action: upsert
endorser: "<endorser_pubkey_hex_66_chars>"
to: "<recipient_pubkey_hex_66_chars>"
ratioBps: <1_to_10000>
timestampNonce: "<uuidv7>"
Update endorsement template: 
kind: rewards_endorsement
version: 1
action: upsert
endorser: "<endorser_pubkey_hex_66_chars>"
to: "<existing_recipient_pubkey_hex_66_chars>"
ratioBps: <new_ratio_1_to_10000>
timestampNonce: "<uuidv7>"
Delete endorsement template: 
kind: rewards_endorsement
version: 1
action: delete
endorser: "<endorser_pubkey_hex_66_chars>"
to: "<recipient_pubkey_hex_66_chars>"
timestampNonce: "<uuidv7>"
The client signs the SHA-256 hash of the YAML payload with the endorser private key and sends that signature as hex.

​
Get Endorsements

GET /v1/rewards/:pubkey/endorsements
Response: 
{
  "endorser": "02abc...def",
  "endorsements": [
    {
      "to": "03fed...cba",
      "ratioBps": 3000
    },
    {
      "to": "02012...999",
      "ratioBps": 2000
    }
  ]
}

​
Create or Update Endorsement

Creates or updates one endorsement rule for to under the endorser. 
POST /v1/rewards/:pubkey/endorsements
Request body: 
{
  "endorser": "02abc...def",
  "to": "03fed...cba",
  "ratioBps": 3000,
  "timestampNonce": "01958d67-2d1a-7a8a-bf8a-5b0a947f8f11",
  "signature": "30440220..."
}
Signing payload (canonical YAML): 
kind: rewards_endorsement
version: 1
action: upsert
endorser: "02abc...def"
to: "03fed...cba"
ratioBps: 3000
timestampNonce: "01958d67-2d1a-7a8a-bf8a-5b0a947f8f11"
The API verifies the signature against the endorser pubkey using secp256k1 over the SHA-256 hash of this YAML payload. Response: 
{
  "endorser": "02abc...def",
  "endorsements": [
    {
      "to": "03fed...cba",
      "ratioBps": 3000
    }
  ]
}

​
Delete Endorsement

Deletes one endorsement mapping for the endorser. 
DELETE /v1/rewards/:pubkey/endorsements/:toPubkey
Request body: 
{
  "timestampNonce": "01958d67-41c1-7dd4-8aa3-ef3575a84ab5",
  "signature": "30450221..."
}
Signing payload (canonical YAML): 
kind: rewards_endorsement
version: 1
action: delete
endorser: "02abc...def"
to: "03fed...cba"
timestampNonce: "01958d67-41c1-7dd4-8aa3-ef3575a84ab5"
Response: 
{
  "ok": true
}

​
Endorsement Rules and Validation

  • pubkey, endorser, and to must be 66-char compressed pubkey hex strings.
  • endorser in body must match :pubkey in the route.
  • ratioBps must be between 1 and 10000.
  • Sum of all active endorsement ratios for an endorser cannot exceed 10000.
  • Endorser cannot endorse to the same pubkey.
  • timestampNonce must be UUIDv7 and within a 5-minute window.
  • Each nonce can only be used once (replay protected).
Common 400 errors:
  • { "error": "Body endorser must match route pubkey" }
  • { "error": "Cannot endorse to the same pubkey. Use rewards payee reassignment instead." }
  • { "error": "Total endorsement ratio cannot exceed 10000 bps" }
  • { "error": "Nonce has already been used" }
  • { "error": "Signature verification failed" }

​
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

Validation errors usually return: 
{
  "error": "Invalid pubkey format. Expected 66 character hex string."
}
Excluded pubkeys on GET /v1/rewards/:pubkey return: 
{
  "reason": "This address is excluded and does not earn rewards"
}
Server-side errors may return: 
{
  "error": "INTERNAL_SERVER_ERROR",
  "message": "..."
}
Common status codes:
  • 400 - Bad request (validation errors, excluded addresses)
  • 404 - Not found
  • 500 - Internal server error