Create multiple campaigns
Everything you need to know to create multiple campaigns in batch on Merkl
While Merkl Studio is ideal for creating single campaigns, Merkl also provides tooling for campaign creators who need to create multiple campaigns at once.
This guide covers all available methods, from the visual Batch Studio interface to programmatic API approaches.
All methods involve working with campaign configurations - whether you're using Studio, API templates, or building configurations from scratch.
Global Settings
When creating multiple campaigns in a batch, certain parameters are shared across all campaigns:
Fixed Parameters (cannot be modified per campaign):
Reward Token: The token used for rewards across all campaigns
Reward Chain: The chain where rewards will be distributed
Campaign Manager: The address managing the campaigns
Customizable Parameters (can be modified per campaign):
Campaign Dates: Start and end timestamps can be customized individually for each campaign
These global settings apply to all methods described below, whether using Batch Studio or the API.
Best Practices
Before diving into the specific methods, here are some general best practices for creating multiple campaigns:
Keep batches under ~20 campaigns to avoid transaction size issues on most chains
When reusing configurations from existing campaigns, pay attention to blacklists that may be inherited. Review and update them as needed for your new campaigns
Method 1: Using Batch Studio (Recommended) ⭐
Access: https://studio.merkl.xyz/batch
The Batch Studio provides an interface for creating multiple campaigns at once.
Global Settings (orange zone on the interface) correspond to the Global Settings described above. The reward token, reward chain, and campaign manager are fixed at the batch level and cannot be modified per campaign. Campaign dates can be customized individually for each campaign.
Workflow
1. Add Campaigns (green zone on the interface)
Use protocol templates (e.g., "Aave Borrow", "Uniswap V3") from the search bar, search by campaign ID or creator address, or import a JSON file with pre-configured campaigns.
Protocol templates: Search by protocol name (e.g., "Aave", "Uniswap") to see all available campaign types for that protocol. Each template contains a complete base configuration with core parameters pre-filled. When you select a template, a popup appears asking you to fill in the required fields, including reward distribution method and protocol-specific fields such as pool address (for DEX pools), market address (for lending protocols), or token weights (for CLAMM).
Campaign ID or Creator Address: Search by existing campaign ID or creator address to import a complete campaign configuration. Use Edit settings (blue zone on the interface) to customize any parameters, including campaign dates per campaign within your batch.
Import JSON: Import a JSON file with pre-configured campaigns.
2. Configure & Customize
In the blue zone on the interface, define the number of tokens to distribute for each campaign. Click Edit settings for advanced configuration on any campaign, notably to modify campaign dates per campaign if you want different timeframes within your batch.
3. Review & Launch
Click Review Batch to verify your configuration, then Launch Batch (EOA wallets) or Download Payload (Safe wallets). Once you have a payload, refer to Create a Campaign from a Multisig or Gnosis Safe for execution instructions.
Method 2: Using Campaign Configurations
This method is the programmatic equivalent of Batch Studio, using the Merkl API exclusively. It allows you to generate a campaign payload using full campaign configurations.
1. Retrieve Campaign Configurations
Use this endpoint to retrieve campaign configurations from existing campaigns.
2. Adjust Parameters
Modify the parameters in the configurations according to your needs. Refer to the campaign configuration documentation for details on available parameters.
3. Generate the Payload
Use this endpoint to generate your Safe-compatible transaction payload.
In the request body, provide your configurations as a JSON array:
Method 3: Override Parameters from Existing Campaigns
This method uses existing campaigns as a base. Instead of specifying complete campaign configurations (as in Method 2), you only need to override specific parameters from existing campaigns. Simply select existing campaigns that closely match your needs, modify the parameters you want to change, generate a payload, and execute it with a Safe.
Key difference from Method 2: You provide only the parameters you want to change (overrides) along with a DatabaseId of an existing campaign. All other parameters are inherited from the existing campaign, making this method more efficient when you're creating variations of existing campaigns.
1. Retrieve Campaign DatabaseId
Select existing campaigns that most closely match what you plan to launch. We strongly recommend matching both the campaign type and the distribution type to minimize the number of parameters you need to modify and reduce the chance of errors.
Next, find the DatabaseId of the campaign(s) you'll use as the base for your new campaigns:
Go to the Merkl app
Select an opportunity and open the "Advanced" tab
Copy the
DatabaseIdvalue
2. Prepare the Campaign Payload
Use this endpoint to generate your batch payload by providing your DatabaseId value(s) (from Step 1) along with the parameters you want to override for each campaign.
Request body structure:
Understanding Parameters
The endpoint uses two types of parameters:
1. Base Parameters (apply to all campaigns in the batch)
These parameters are set once at the top level and apply to all campaigns in the batch. They correspond to the Global Settings described above. If you need different values for some campaigns (e.g., different reward token), create a separate payload.
creatorAddress: The address creating the campaigns (fixed for all campaigns)rewardToken: The token used for rewards across all campaigns (fixed for all campaigns)distributionChainId: The chain ID where campaigns will run (fixed for all campaigns)startTimestamp: The start date of the campaigns (in Unix timestamp format) - can be customized per campaignendTimestamp: The end date of the campaigns (in Unix timestamp format) - can be customized per campaign
Once you've set these base parameters at the top level, you can override specific parameters for each campaign in campaignsParams below.
2. Per-Campaign Parameters (specific to each campaign)
These parameters go under campaignsParams and let you customize each campaign. The available fields correspond to the campaign-specific parameters in each campaign configuration.
You can view all available parameters for a specific campaign using this endpoint.
Example: Campaign ID 13756496363331257690 - https://api.merkl.xyz/v4/config/13756496363331257690
For simple use cases where you only want to change the campaign amount, you'll only need to modify the amount field.
Example
You want to generate a payload for the following campaigns:
2 Uniswap V3 campaigns (DatabaseId: 9427880006586247706)
1 Morpho (supply at the market level) campaign with a fixed rate of 5% APR (DatabaseId: 3011317640800818752)
1 Aave (supply side) campaign with a capped APR of 10% (DatabaseId: 711211603263558496)
When using the API endpoint, the body will look like this:
Method 4: Pre-Set Campaign Keys (Deprecated)
This method is deprecated. We recommend using Method 2 or Method 3 instead.
This method requires the Merkl team to pre-define campaigns in the backend. You then generate a payload by specifying the amount, dates, and chain for each pre-defined campaign.
Setup
To get started, provide:
The assets you'd like to incentivize
Any customization options you'd like to apply
We'll save these configurations and generate the corresponding keys needed to launch your campaigns in bulk, which we'll share via a GitHub Gist.
Once configured, you'll be able to create multiple campaigns at once, all sharing the same base parameters:
program: Provided by us—the internal ID of your incentive programcreator: The Safe address that will execute the campaign payloadrewardToken: In checksum formatdistributionChainId: The chain where rewards will be distributedstartTimestamp: Campaign start time (Unix timestamp)endTimestamp: Campaign end time (Unix timestamp)
Payload Generation
Generate your campaign payloads using this endpoint.
To use it:
Input the base parameters listed above.
In the request body, paste the JSON file with the keys and placeholder amounts we provided via GitHub Gist (see example below).
For each key:
Replace the placeholder amount with the number of tokens you want to allocate (in raw units).
Use the correct number of decimals (e.g.,
5000000000000000000for 5 tokens if the token has 18 decimals).If you do not plan to incentivize a specific key, remove it entirely from the JSON rather than setting the amount to
0.
Click Send. If the payload is successfully generated, you'll be able to download it. If there's an error, reach out to us and we'll help troubleshoot.
Download the generated payload.
Example
Let's say you're a chain and want to incentivize:
5 Uniswap pools
2 Euler vaults
You would send us the addresses of the pools and vaults you want to incentivize. Once received, we'll configure your setup and return the associated keys via a GitHub Gist.
The Gist will follow this format:
For example, it would look like this:
The values(100000000000000000000) are placeholder values. When creating your campaigns, you'll need to replace them with the actual amounts you want to allocate. All amounts must be entered in raw format using the correct token decimals.
Then proceed with the steps outlined in the Payload Generation section above.
If you need help or encounter issues, contact us on Discord.
Last updated