Rewards API - Flashnet

The Rewards API lets your app display USDB balances, reward estimates, payout history, and Flashpoints. It also supports signed endorsements that direct a share of a holder’s future rewards to other pubkeys.

Base URL

https://rewards.flashnet.xyz

All endpoints use the /v1 prefix. Swagger documentation is available at /docs.

Rewards

Get Rewards Leaderboard

Returns users sorted by USDB balance, with each user’s reward tier and estimated payout.

GET /v1/rewards/?limit=100&offset=0

Parameters:

limit - Maximum results (default 100, maximum 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 a user’s current USDB balance, today’s volume, reward bracket, and estimated rewards for the day.

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:

Bracket	`volumeUtcToday.swapSats` Threshold	Rewards
0	`>= 0`	3.5%
1	`>= 500000`	4.0%
2	`>= 2500000`	4.5%
3	`>= 5000000`	5.0%
4	`>= 10000000`	5.5%
5	`>= 25000000`	6.0%

Get Payout History

Returns a user’s payout history, including their own rewards and any delegated rewards received. Use limit and offset to page through the results.

GET /v1/rewards/:pubkey/payouts?limit=30&offset=0

Parameters:

limit - Maximum 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

An endorsement assigns part of a holder’s future daily reward payout to a recipient pubkey. The holder signs each change. See Rewards Delegation for an example of how payouts are split.

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>"

Sign the SHA-256 hash of the canonical YAML payload with the endorser’s private key, then send the signature as a hex string.

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 an endorsement for the to pubkey or updates its existing allocation.

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

Removes the endorsement for :toPubkey from the endorser’s future payouts.

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-character compressed pubkey hex strings.
The body endorser must match :pubkey in the route.
ratioBps must be between 1 and 10000.
The sum of an endorser’s active endorsement ratios cannot exceed 10000.
The endorser cannot endorse their own pubkey.
timestampNonce must be UUIDv7 and within a 5-minute window.
Each nonce can be used only once, preventing request replay.

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 users sorted by current Flashpoints, with their point balances and volume.

GET /v1/points/?limit=100&offset=0

Parameters:

limit - Maximum results (default 100, maximum 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 a user’s current and lifetime Flashpoints, rank, and projected points for the day.

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 a user’s point-earning events. Use limit and offset to page through the history.

GET /v1/points/:pubkey/history?limit=30&offset=0

Parameters:

limit - Maximum 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 USDB holder totals, trading activity, payout totals, and the last days processed for rewards and points.

GET /v1/stats

Response:

{
  "usdb": {
    "totalHolders": 830,
    "totalBalanceRaw": 2500000000000,
    "totalBalanceUsdb": 2500000.0
  },
  "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"
}

The status is "degraded" if either payout or points processing is behind.

Error Handling

Validation errors usually include an error field:

{
  "error": "Invalid pubkey format. Expected 66 character hex string."
}

For excluded pubkeys, GET /v1/rewards/:pubkey returns a reason field:

{
  "reason": "This address is excluded and does not earn rewards"
}

Server errors may include an error code and message:

{
  "error": "INTERNAL_SERVER_ERROR",
  "message": "..."
}

Common status codes:

400 - Bad request (validation errors, excluded addresses)
404 - Not found
500 - Internal server error

​Base URL

​Rewards

​Get Rewards Leaderboard

​Get User Summary

​Get Payout History

​Endorsements

​Canonical YAML Templates (for Signing)

​Get Endorsements

​Create or Update Endorsement

​Delete Endorsement

​Endorsement Rules and Validation

​Flashpoints

​Get Points Leaderboard

​Get User Points

​Get Points History

​Stats

​Get Global Stats

​Health Check

​Error Handling

Base URL

Rewards

Get Rewards Leaderboard

Get User Summary

Get Payout History

Endorsements

Canonical YAML Templates (for Signing)

Get Endorsements

Create or Update Endorsement

Delete Endorsement

Endorsement Rules and Validation

Flashpoints

Get Points Leaderboard

Get User Points

Get Points History

Stats

Get Global Stats

Health Check

Error Handling