> ## Documentation Index > Fetch the complete documentation index at: https://yieldxyz.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Incentive Campaigns > Layer a time-boxed reward budget on top of a yield, with hourly accrual and eligibility rules you configure. An incentive campaign adds a reward budget on top of an existing yield for a fixed window. While it's active, the yield's reward rate on the Yield API includes both its native rate and the campaign's incentive rate, and eligible depositors accrue a share of the budget over time. ## How a campaign runs A campaign accrues on an hourly cadence for its whole duration, independent of when it pays out: 1. **Accrual.** Each hour, the campaign evaluates every depositor's indexed balance against its qualification rule and adds a pro-rata share of that hour's emission to each qualifying user's running total. 2. **Settlement.** On the configured payout cadence, users with an unpaid balance are collected, batched, and paid out through the campaign's Safe multi-sig. Accrual and settlement are independent: a delayed payout doesn't stop accrual, and a missed hour is picked up on the next pass. ### Reward modes | Mode | Behavior | | - | - | | `normal` | Rewards are any ERC-20 token, paid to the user's wallet at each payout. | | `compound` | The reward token is the yield's vault share token, so payouts add directly to the user's vault position instead of landing as a separate balance. Requires the reward token to differ from the yield's input token. | ## Configuration A campaign is created against a specific `yieldId` and must be pinned to that yield's `LIVE` allocator fee configuration (its vault) before it can go live; the pin is optional on a draft. Fields you set: | Field | Controls | | - | - | | `rewardToken` | The token distributed as rewards | | `rewardMode` | `normal` or `compound` | | `totalBudget` | Total reward token amount for the campaign | | `startTime` / `endTime` | The accrual window | | `apyCeiling` | Optional cap on the campaign's implied APY, as a decimal rate (`0.125` = 12.5%) | | `payoutFrequency` | `six_hourly`, `daily`, `weekly`, or `end_of_campaign` | | `budgetSpendStrategy` | `allow_underspend` (fixed hourly rate; unspent budget returns to the Safe) or `spend_full_budget` (recomputes the hourly rate from remaining budget and time, so underspend redistributes forward) | | `qualificationConfig` | The eligibility rule, see below | | `blacklistBudgetHandling` | `reserve` (an excluded user's accrued share stays reserved) or `redistribute` (it spreads across remaining eligible users) | | `safeAddress` | The Safe multi-sig the campaign pays out from | Campaigns aren't configured through a dashboard screen. You submit a create, update, or end request to yield.xyz, which reviews and accepts or rejects it; drafts can be edited before going live. Going live, and changing budget, APY ceiling, end time, payout address or qualification on a live campaign, goes through that review. ## Lifecycle | State | Meaning | | - | - | | `draft` | Configured but not accruing | | `active` | Accruing on its hourly schedule | | `paused` | Accrual stopped; can be resumed | | `ended` | Terminated; no further accrual | A campaign moves between these states through explicit actions: pause, resume (optionally backfilling the paused window), acknowledge-pause, and end. ## Eligibility and qualification The only qualification rule currently supported is `min_token_amount`: a user's qualifying balance must meet a configured `threshold` to accrue that hour. An optional `maxIncentivizedTvlToken` caps how much of a large balance accrues rewards; the excess still earns the yield's native rate, just not the campaign incentive. Independent of qualification, any address can be flagged ineligible for payout. A flagged address stops accruing and is excluded from settlement, while its already-accrued balance and history are preserved; the flag is reversible. This is the mechanism for excluding a specific address (for example, a compliance concern or a detected gaming pattern) without pausing the whole campaign. ## Discovery Integrators surface active campaigns two ways: * **On the yield itself.** A yield with an active campaign returns a reward-rate breakdown on the Yield API (`GET /v1/yields` and `POST /v1/yields/balances`): the response's `rewardRate.components` includes a `campaign_incentive` entry alongside the yield's native rate, so a frontend can show users where the combined rate comes from. `POST /v1/yields/balances` reflects each user's actual accrued and eligible amount; `/v1/yields` reflects the campaign's rate assuming full qualification. * **`GET /v1/yields/{yieldId}/campaigns`.** Lists campaigns for a specific yield, filterable by `status` (defaults to `active`), each with its budget state (`totalBudget`, `distributedBudget`, `remainingBudget`), `apyCeiling`, `qualificationConfig`, `payoutFrequency`, `rewardToken`, and accrual window. ## Reporting Campaign data is also readable with an Admin API key for finance and audit use: campaigns, accruals, payout runs and per-user balance state. This access is read-only; campaigns are not configured through it. See [Programmatic access](/documentation/advanced-setup/programmatic-access). ## Next steps How reward rates and their components surface on a yield. Track per-user positions and accrued reward balances. The vault layer a campaign's fee configuration is pinned to. Admin API keys, including read-only campaign reporting. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.