Skip to main content
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): 
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): 
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.