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.

Next steps

Yield metadata

How reward rates and their components surface on a yield.

Balances and positions

Track per-user positions and accrued reward balances.

Vaults and OAVs

The vault layer a campaign’s fee configuration is pinned to.

Programmatic access

Admin API keys, including read-only campaign reporting.