Formulas
Custom reward formulas for controlling how rewards are calculated
The customFormula parameter on create_recurring_incentive controls how each user's reward is calculated from their query result.
Variables
| Variable | Description |
|---|---|
N or VALUE | The user's query result value (e.g. trade volume, event count) |
RANK | User's rank in the leaderboard (1 = highest value) |
INDEX | Zero-based position (RANK - 1) |
TOTAL_PARTICIPANTS | Total number of qualifying users in this epoch |
TOTAL_REWARD_POOL | The totalFundAmount for this epoch |
Functions
| Function | Description |
|---|---|
sqrt(x) | Square root |
pow(x, y) | Exponentiation |
abs(x) | Absolute value |
floor(x) | Round down |
ceil(x) | Round up |
round(x) | Round to nearest |
min(x, y) | Minimum |
max(x, y) | Maximum |
log(x) | Natural logarithm |
exp(x) | Exponential |
Examples
| Intent | Formula |
|---|---|
| Proportional to value (default) | N |
| Equal share for all participants | TOTAL_REWARD_POOL / TOTAL_PARTICIPANTS |
| Square root scaling (reduces whale advantage) | sqrt(N) |
| Top 3 get fixed amounts | RANK <= 3 ? (4 - RANK) * 100 : 0 |
| Capped at 50 per user | min(N, 50) |
| Logarithmic scaling | log(N + 1) |
| Bonus for top 10% | RANK <= ceil(TOTAL_PARTICIPANTS * 0.1) ? N * 2 : N |
Formulas produce direct payout amounts — each user receives exactly what the formula evaluates to, subject to the reward pool cap.
How it works:
- Users are processed in SQL query result order (highest value first for MCP-generated queries)
RANKis assigned by position (1 = first row in results)- Each user gets their formula result if the pool has enough remaining
- When remaining pool is less than the formula result, the user receives only what's left
- Once the pool is exhausted, remaining users receive nothing
- Negative formula results are converted to 0
Practical implications:
N(default leaderboard): each user gets their raw metric value — if the top user's value exceeds the pool, they consume it allTOTAL_REWARD_POOL / TOTAL_PARTICIPANTS: equal split for everyoneRANK <= 3 ? (4 - RANK) * 100 : 0: fixed prizes by rank (300, 200, 100), capped by poolTOTAL_REWARD_POOL / pow(RANK, 0.5): diminishing returns, but total may exceed pool so lower ranks get reduced amounts