Skip to main content
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:
Revoke a delegation:

​
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:
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.