> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flashnet.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Rewards Sharing

> Share your daily rewards

Rewards delegation lets you send a share of your future daily USDB rewards to other pubkeys. The Rewards API calls each allocation an endorsement.

You sign a request to set the recipient and their share. The endorsement stays active until you update or delete it, and any unallocated share remains yours. Delegation splits your reward payout without transferring your USDB balance.

## Request Examples

Create or update a delegation:

```yaml theme={null}
kind: rewards_endorsement
version: 1
action: upsert
endorser: "02abc123...compressed_pubkey_hex"
to: "03def456...compressed_pubkey_hex"
ratioBps: 2500
timestampNonce: "01958d67-2d1a-7a8a-bf8a-5b0a947f8f11"
```

Revoke a delegation:

```yaml theme={null}
kind: rewards_endorsement
version: 1
action: delete
endorser: "02abc123...compressed_pubkey_hex"
to: "03def456...compressed_pubkey_hex"
timestampNonce: "01958d67-41c1-7dd4-8aa3-ef3575a84ab5"
```

## What Endorsements Do

Each endorsement allocates a share of your daily reward payout in basis points (`ratioBps`), where `2500` means 25%. Recipients are credited in the same daily payout cycle.

Payout history distinguishes a recipient's own rewards from delegated rewards:

* `rewardsPayoutSats` for their own rewards.
* `endorsementsPayoutSats` for delegated rewards received.
* `payoutSats` as the total.

## Example

Suppose your daily payout is `10000` sats and you allocate `3000` bps (30%) to recipient A and `2000` bps (20%) to recipient B. A receives `3000` sats, B receives `2000` sats, and you keep `5000` sats.

## Self-Endorsements

Set `to` to your own pubkey to keep a share explicitly:

```yaml theme={null}
kind: rewards_endorsement
version: 1
action: upsert
endorser: "02abc123...compressed_pubkey_hex"
to: "02abc123...compressed_pubkey_hex"
ratioBps: 10000
timestampNonce: "01958d67-5a20-7c3e-9b1d-2f6e8a4c7d10"
```

A self-endorsement counts toward the `10000` bps limit like any other endorsement. An unallocated share already pays out to you, so a self-endorsement records that share without changing your payout. To move part of a self-endorsement to another recipient, lower the self-endorsement first, then create the new one: the API checks the limit on every request.

## Security Model

Every create, update, or delete request requires a UUIDv7 `timestampNonce` and a secp256k1 signature from the endorser. The signature covers the SHA-256 hash of the canonical YAML payload.

The API enforces these constraints:

* Nonce timestamp must be within 5 minutes.
* Nonces are single-use (replay protection).
* Sum of all active ratios for one endorser cannot exceed `10000` bps, including a self-endorsement.
* Pubkeys are case-insensitive. The signature covers the payload exactly as you send it, and the API stores and returns pubkeys in lowercase hex.

## Endpoints

* `GET /v1/rewards/:pubkey/endorsements`
* `POST /v1/rewards/:pubkey/endorsements`
* `DELETE /v1/rewards/:pubkey/endorsements/:toPubkey`

For full request/response examples, see [Rewards API](https://docs.flashnet.xyz/rewards/integrators/api.md#endorsements).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.