Rewards API - Flashnet

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:

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

USDB

Integrators

Documentation Index

​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