Merkl Developer Portal

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

By Campaign List - Find all campaigns tagged in one of your custom campaign lists:

https://api.merkl.xyz/v4/campaigns?campaignLists={name}&listOwner={owner}

Sub-campaigns are created by reward forwarding, for example to pay users staked in a gauge instead of the gauge contract. A root campaign's campaignId starts with 0x; a sub-campaign's is numeric. To query rewards, use the root campaign ID: its rewards include all its sub-campaigns.

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

A campaign has an onchain campaignId (0x…, not unique across chains) and an internal numeric id (unique, used by most routes). Both appear in the Advanced tab of a campaign in the Merkl app. See ID types for which endpoint expects which.

API V4

Tagging campaigns with lists

Campaign lists let you group arbitrary campaigns under a name you own (e.g. featured, partners-q2, mainnet-launch), then filter the /v4/campaigns endpoint by that tag. Lists are scoped to your API key owner, so two integrators can each maintain a list called featured without collision.

Prerequisites

Generate an API key from the Merkl Developer Portal.
Include it as X-API-Key on every request to the list endpoints (see Auth & rate limits).

The {owner} path parameter must be the same address that was used to create the API key. Requests where {owner} doesn't match the address tied to your X-API-Key will be rejected. This is what scopes a list (e.g. featured) to you and prevents other integrators from writing to it.

Campaign list ID

Lists store campaigns by their internal numeric id, as returned by /v4/campaigns.

Add a campaign to a list

If the list doesn't exist yet, it's created automatically on the first add.

curl -X POST https://api.merkl.xyz/v4/campaign-lists/{owner}/{name}/add \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "campaignIds": [
      "5821552044504491915"
    ]
  }'

Remove a campaign from a list

Same body shape as the add endpoint.

curl -X POST https://api.merkl.xyz/v4/campaign-lists/{owner}/{name}/remove \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "campaignIds": [
      "5821552044504491915"
    ]
  }'

List your lists

https://api.merkl.xyz/v4/campaign-lists/{owner}

Get the campaigns inside a list

https://api.merkl.xyz/v4/campaign-lists/{owner}/{name}

Filter campaigns by list

Once a list is populated, pass its name and owner to /v4/campaigns to retrieve only the tagged campaigns. Both parameters are required: campaignLists selects the list name, listOwner scopes it to the address that owns the list.

https://api.merkl.xyz/v4/campaigns?campaignLists={name}&listOwner={owner}&items=100

Example:

https://api.merkl.xyz/v4/campaigns?campaignLists=base-incentives&listOwner=0xEb853F14daDb92752151a087F29ad2690eCb35A4&items=100

Finding campaigns