Customization Options

Personalize reward distribution to make your campaign unique

Customization options shape who earns and how much: eligibility filters, access controls, boosts, privacy, referrals, raffles, and more. The most common ones are in Merkl Studio. For anything else, contact us.

This page explains what each option does. The developer docs have the technical details: Key-value stores for every option backed by a store, and Campaign options for the others. The schema explorer lists every option.

Eligibility

Blacklisting

Exclude specific addresses from rewards: exploiters, sanctioned wallets, team addresses, or contracts you do not want to incentivize.

Whitelisting

Restrict rewards to a set of addresses: users, forwarders, or both. Among whitelisted addresses, rewards stay proportional to each one's share.

For example, on a Uniswap V3 pool with three liquidity managers, you can whitelist two managers and one direct user. Only liquidity through those two managers and the user's own position earns rewards.

Dynamic lists

To change a whitelist or blacklist often (large allowlists, ongoing KYC, exploit response), keep it in a key-value store instead of the campaign configuration. You update the list with your API key, with no onchain transaction. Changes apply within about two hours.

Protocol lists

Reward forwarding can route rewards across many downstream protocols. You can restrict it to (or exclude) specific protocols instead of listing addresses.

Access Control

Gate eligibility on onchain conditions or events. You can combine several in one campaign.

• View functions: almost any condition exposed by a view function. Common examples:
  • Token snapshot: hold a minimum amount of a token at a snapshot block.
  • OFAC compliance: exclude sanctioned addresses with a registry such as the Chainalysis Sanctions Oracle.
  • World ID: only humans verified with World ID.
  • Health factor: on lending protocols such as Aave, only addresses with active borrows.
• Onchain events: build the eligible set from indexed events. For example, reward only users of a smart-wallet stack by indexing its account creation events.
• Duration-gated holding: hold a minimum amount of a token for a minimum duration. For example, with 500 stUSD for 30 days, 600 stUSD for 44 days qualifies, but 400 stUSD for 60 days and 800 stUSD for 12 days do not.

Privacy

Hide a campaign's configuration and rules from public view: confidential airdrops, private payments, or deals with undisclosed terms. See Private Campaigns.

Leaderboard Visibility

Hide a campaign's leaderboard, ranks, and per-address breakdowns, while the campaign itself, its APR, and its rules stay public. Recipients still see and claim their own rewards.

Boosts

Token / NFT boost

Boost rewards for users who hold a specific token or NFT, like Curve's vote-escrow model but with no 2.5× cap:

$$B = b \times \frac{R \times v}{V \times r} + 1$$

• B: boost multiplier applied to the user's rewards.
• b: boost factor chosen by the campaign creator.
• R / r: total / user rewards per epoch.
• V / v: total supply / user holdings of the boost token or NFT.

For example, set the multiplier to 1.1 for a 10% boost.

Dynamic boosts

For boosts based on data Merkl cannot see (offchain scores, KYC tiers, partner lists), give Merkl a boost value per address. The engine reads it on every computation and multiplies, adds, or replaces each user's score. Two ways:

• Key-value store (recommended): push address → boost entries with your API key. Several campaigns can share one store.
• API boost: expose an endpoint that the engine calls with the eligible addresses. This also lets you run a whitelist or blacklist that changes over time.

Parameters: boost hook and API boost.

Advanced Logic

Bridge liquidity tracking

Reward only users who bridged liquidity from another chain before they participate, so only new cross-chain liquidity earns. Jumper is supported today. Other bridges on request.

Referral program

Run a referral program offchain: push invitee → referrer pairs to a key-value store, with no referral codes onchain and no redeployment. Each invitee has one referrer; a referrer can have many invitees. Changes apply within about two hours, from the next computation.

Set the boost types in Merkl Studio when you create the campaign (parameters: referral hook). The examples below use one scenario: Alice referred Bob and Carol. Base rewards: Alice 100, Bob 50, Carol 30.

Referrer boosts

• score: no bonus. Alice earns 100.
• proportional: the referrer earns value% of their invitees' rewards, only if the referrer participates. At 10%, Alice earns 100 + 8 = 108. With no position, she gets nothing.
• flatBoostNonParticipating: the same, but the referrer does not need to participate. Use it for affiliate programs. At 10%, Alice gets 8 even with no position.

Invitee boosts

• score: no bonus. Bob earns 50.
• proportional: value% of their own rewards, capped at value% of their referrer's rewards. At 20%, Bob earns 50 + min(10, 20) = 60. A referrer with no position gives no boost.
• flatBoostNonParticipating: value% of their own rewards, always. At 20%, Bob earns 60, even if Alice has no position.
• community: value% of the combined rewards of everyone the same referrer invited. At 20%, Bob and Carol each get 20% × 80 = 16.

Forwarding store

Redirect rewards from one address to another, for example from a vault to its real beneficiaries, with a forwarding store that you manage. Unlike the automatic reward forwarding for integrated protocols, you control every entry. Unlike the global user forwarding, it only applies to the campaigns that use it. Setup: forwarding hook.

Precedence

When several redirections apply to the same reward, Merkl applies the first match:

1. Address remapping (per campaign, set by Merkl on request): see Address Remapping.
2. Creator forwarding store (per campaign, per address).
3. User global forwarding (all campaigns, set by the user for their own address).
4. The original earner.

On the same source address, the creator entry wins over the user entry. A remapped address is only redirected further if forwarding is enabled for the remapped address.

Raffle

Instead of proportional rewards, draw winners:

• Frequency: daily, weekly, or any cadence.
• Winners: one grand prize, or any number per draw.
• Odds: equal for all participants, or weighted by campaign score.
• Parallel raffles: several draws at once, each with its own rules.

Draws are reproducible: anyone can recompute the winners from a public block hash. See Raffle.

For dynamic campaigns, a common trick is to first run the same campaign without the raffle and with a small budget. Its recipients become the raffle participants.