Overview
Rewards lets you run incentive programs for your participants. You report activity, such as wallet balances, settlements or any metric you define, and Rewards calculates what each participant earns under the rules you choose. Every amount comes with an explanation of how it was reached, and a period's rewards can be exported for your own payment run.
To start, see Getting started. The API reference lists each endpoint with its request and response schemas. Program enrollment isn't in it yet; see Participants and enrollment.
How rewards work
Programs and periods
A program pays rewards in one asset, its reward asset, over monthly periods.
- Periods follow calendar months, or start on a set day of the month that you choose when you create the program. The start day can't change once the program has started.
- A program runs from its start date until you end it. Its first and last periods are shortened to those dates.
- All dates and times are UTC.
- Rewards for a period are estimates while it runs, and update as activity arrives.
Budgets
Budgets track spending: a budget for one program, and an organization budget across all your programs in one asset. You can see how much of each budget rewards use and when it goes over. Budgets are for tracking only: rewards are always paid in full. Test programs, and programs paying a different asset, don't count toward the organization budget.
Participants
A participant exists once in your organization, identified by your own ID for them. Create the participant first, then enroll them in each program they take part in.
KYB status, tags and wallet addresses belong to the participant and apply in every program they're enrolled in. A KYB change updates their rewards. Enrollment date and eligibility are set per program.
Activity
Activity is what you report about your participants: daily wallet balances, and any other measure you track, such as settlement volume or number of settlements. Sending the same row again replaces it, so activity can be corrected.
Wallet addresses are linked to a participant automatically, by the first activity row that names them. An address belongs to one participant across all of your programs.
Rules
Rules decide what earns a reward. They live in your rule library, shared by every program, and are added to programs.
- Building a rule. A rule has four parts: what it measures (a daily balance, a total, a count, an average, or a status such as KYB approved), the condition for paying, the payout, and any limits, such as a cap per period or once per participant.
-
Adding a rule to a program. Each rule gets a key in the program, such as
kyb_bonus, shown on reward lines and in exports. It can't change after the rule is added. - Versions. Changing a rule's definition saves a new version; earlier versions never change. A change to only its name or description keeps the same version.
- When changes apply. Adding, upgrading or removing a rule takes effect from the program's next period (or its first period, if it hasn't started). The current period keeps the rules it is being calculated with.
Preview. Before adding a rule, you can preview what it would have paid in a period.
Default rules. Your library starts with two rules you can use as they are or adapt:
| Rule | What it pays |
|---|---|
| Onboarding bonus | 25 once, in the first period a participant is enrolled and KYB-approved |
| USDPT holdings | 3.5% a year on each wallet's daily USDPT balance |
How a reward is calculated
Rewards are calculated per participant and period, and recalculated whenever something that affects them changes, such as new activity, a KYB change or a rule change.
- Each rule measures the participant's activity in the period, checks its condition and calculates its payout.
- Limits apply: a rule that already paid a participant once pays nothing more, and a cap per period scales the rule's amount down to the cap.
Each result is a reward line, one per rule, or one per wallet for balance rules. Every line carries an explanation showing the measured value, whether the condition was met, the payout and which limits applied.
A period's rewards can be exported as CSV for your payment run.