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

> Use endorsements to direct a share of USDB daily rewards to other pubkeys

Rewards delegation is implemented as **endorsements** in the Rewards API.

An endorser signs a request that assigns part of future daily reward payouts to one or more recipient pubkeys.

## High-Level YAML Example

**Create delegation (upsert):**

```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 delegation (delete):**

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

* Split only the endorser's daily reward payout.
* Allocate payout shares in basis points (`ratioBps`).
* Keep any unallocated share with the endorser.
* Stay active until updated or deleted.
* Credit recipients in the same daily payout cycle.

If a recipient also earns their own rewards, payout history combines both values:

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

## Example

If an endorser configures:

* Recipient A: `3000` bps (30%)
* Recipient B: `2000` bps (20%)

And the endorser's payout for the day is `10000` sats:

* Recipient A receives `3000` sats as endorsements payout.
* Recipient B receives `2000` sats as endorsements payout.
* Endorser keeps `5000` sats as rewards payout.

## Security Model

Every create/update/delete request requires:

* A `timestampNonce` in UUIDv7 format.
* A secp256k1 signature by the endorser pubkey.
* The signature is over the SHA-256 hash of a canonical YAML payload.

Additional protections and constraints:

* Nonce timestamp must be within 5 minutes.
* Nonces are single-use (replay protection).
* You cannot endorse to yourself.
* Sum of all active ratios for one endorser cannot exceed `10000` bps.

## 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](/rewards/integrators/api#endorsements).