Finding campaigns

Query the campaigns endpoint for campaign rules, budgets, and configuration

While the opportunities endpoint provides high-level metrics about what's being incentivized, the campaigns endpoint offers detailed campaign rules (duration, budget, campaign type, customization options, etc.). Use this endpoint to display in-depth campaign information to your users.

For a complete list of available filters, see the campaigns endpoint documentation.

Recommended filters:

By Creator Address - Find all campaigns created by a specific address:

https://api.merkl.xyz/v4/campaigns?creatorAddress={address}

Example: https://api.merkl.xyz/v4/campaigns?creatorAddress=0xdef1FA4CEfe67365ba046a7C630D6B885298E210

By Token Symbol - Find all campaigns distributing a specific reward token:

https://api.merkl.xyz/v4/campaigns?tokenSymbol={symbol}

Example for campaigns distributing $PYTH: https://api.merkl.xyz/v4/campaigns?tokenSymbol=PYTH

Excluding sub-campaigns - Find all campaigns except sub-campaigns created by parent campaigns due to reward forwarding

https://api.merkl.xyz/v4/campaigns?excludeSubCampaigns=true

What are sub-campaigns?

Sub-campaigns are automatically created through reward forwarding when Merkl's engine detects that rewards should be distributed to end users rather than intermediate contracts.

Example: When incentivizing a Curve pool, if the engine detects that one of the LP token holders is actually a Curve gauge contract, it will automatically create a sub-campaign to properly distribute rewards to the users who staked in that gauge, rather than to the gauge contract itself.

How to identify sub-campaigns:

Check the campaignId field in the API response:

  • Root campaign: campaignId starts with 0x (e.g., 0xabc123...)
  • Sub-campaign: campaignId is a numeric value (e.g., 123456789)

Best practice: When querying campaign rewards, always use the root campaign ID. The root campaign's rewards data automatically includes all rewards from its sub-campaigns, giving you a complete picture of the total distribution.

Retrieving both campaign and opportunity data

The campaigns endpoint provides campaign-specific information but not upstream opportunity data. Similarly, querying for an opportunity doesn't include downstream campaign details. To retrieve all information in a single request:

Search campaigns with related opportunities - Use /v4/campaigns with withOpportunity=true:

https://api.merkl.xyz/v4/campaigns?withOpportunity=true

Search opportunities with related campaigns - Use /v4/opportunities with campaigns=true:

https://api.merkl.xyz/v4/opportunities?campaigns=true

Learn more about how TVLs, APRs, and daily rewards are computed and why they may differ between the campaign and opportunity levels.

About campaign IDs

Merkl uses two distinct identifier types for campaigns:

  • campaignId (format: 0x...): The onchain identifier of a campaign. Note that this is not unique across chains: multiple campaigns on different chains may share the same campaignId. You can find this in the opportunities page by selecting an opportunity, viewing campaign details, and navigating to the "Advanced" tab.
  • id (format: numeric, e.g., 13972358188887408622): The unique database identifier used for most API routes. You can retrieve this by querying the campaigns endpoint with a campaignId. You may also find a campaign's database ID under the advanced tab of a campaign on the Merkl app.

API V4