Recurring Incentives
Create and manage reward programs
Recurring incentives are reward programs that evaluate user activity on a recurring schedule and distribute rewards accordingly.
create_recurring_incentive
Create a recurring incentive (reward program) for the active project.
Requires: authentication, active project
Core Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Display name |
description | string | No | Description |
type | "leaderboard" | "rebate" | "raffle" | "direct" | Yes | Reward distribution type |
emissionType | "TOKENS" | "SOL" | Yes | Type of reward |
totalFundAmount | number | Yes | Total reward pool per epoch |
startDate | string | Yes | ISO 8601 start date |
confirmed | boolean | No | Set to true to execute. Omit to preview. |
Schedule
| Parameter | Type | Description |
|---|---|---|
evalDurationDays | number | Duration of each epoch in days (1, 7, 30, etc.) |
interval | "DAILY" | "WEEKLY" | "MONTHLY" | Shorthand for evalDurationDays |
maxIterations | number | Maximum epochs to run. Omit for unlimited. |
Provide either evalDurationDays or interval, not both.
Token Configuration
| Parameter | Type | Description |
|---|---|---|
tokenAddress | string | SPL token mint address (required if emissionType is "TOKENS") |
tokenDecimals | number | Token decimal places (required if emissionType is "TOKENS") |
Query & Formula
| Parameter | Type | Description |
|---|---|---|
sqlQuery | string | SQL query from generate_incentive_query |
customEventId | string | Custom event ID (mutually exclusive with instructionId) |
instructionId | string | IDL instruction ID (mutually exclusive with customEventId) |
customFormula | string | Reward formula. See Formulas. |
maxPerParticipant | number | Maximum reward per user per epoch |
Type-Specific Parameters
Rebate:
| Parameter | Type | Description |
|---|---|---|
rebatePercentage | number | Rebate percentage (e.g. 5 for 5%) |
Raffle:
| Parameter | Type | Description |
|---|---|---|
raffleBuckets | array | Prize tiers: [{ amount: number, count: number }] |
raffleWeighting | "WEIGHTED_BY_METRIC" | "EQUAL_CHANCES" | How tickets are assigned. Default: WEIGHTED_BY_METRIC (metric value = ticket count) |
Direct:
| Parameter | Type | Description |
|---|---|---|
allocations | array | string | Wallet allocations: array of { address, amount } or CSV string |
list_recurring_incentives
List all recurring incentives for the active project.
Requires: authentication, active project
No parameters.
get_recurring_incentive
Get full details of a specific recurring incentive — configuration, distribution settings, current epoch status, and query info.
Requires: authentication, active project
| Parameter | Type | Required | Description |
|---|---|---|---|
recurringOfferId | string | Yes | The recurring incentive ID |
get_recurring_incentive_analytics
Get performance analytics for a recurring incentive — participation counts, rewards distributed, and epoch-by-epoch history.
Requires: authentication, active project
| Parameter | Type | Required | Description |
|---|---|---|---|
recurringOfferId | string | Yes | The recurring incentive ID |