Merkl Developer Portal logo
get

/v4/campaigns/

Search for campaigns matching the criteria provided through query parameters.

Query parameters

pagenumber | stringdefault: 0

0-indexed page number

itemsnumber | stringdefault: 20

Number of items returned by page

idstring

Filter by internal campaign ID (Campaign.id, numeric hash, e.g. 13896840291241714382). NOT the on-chain campaignId (hex hash) — use the campaignId query for that. Comma-separated list supported. See ID types.

creatorTagstring

Filter campaigns created by a user who has a specific tag

creatorAddressstring
creatorAddressesstring[]
creatorIdstring

Filter campaigns created by a user who is registered as a merkl creator

chainIdnumber | string

Filter by compute chain.
You can get the list of all supported chains by calling GET /v4/chains

searchstring

Search amongst multiple values (token, protocols, tags, campaigns)

distributionChainIdsnumber | string[]

Filter by distribution chain.
You can get the list of all supported chains by calling GET /v4/chains

typestring

Filter by type of campaign

typesstring[]

Filter by type of campaign using an array. The type entry has priority.

subTypenumber

Silo, Radiant, Morpho, Dolomite, Compound, Ajna and Euler campaigns have a subtype attribute you can filter on

campaignIdstring

Filter by on-chain campaign ID (Campaign.campaignId, 32-byte hex hash, e.g. 0x93cf385c2a446a7596820601caf25e63bfc4939efa9a89a6f21563b58ee54eb1). The same on-chain campaignId can exist on several chains; one resource per chain is returned. NOT the internal Campaign.id (numeric hash) — use the id query for that. See ID types.

campaignIdsstring[]

Filter by multiple on-chain campaign IDs (32-byte hex hashes). The campaignId entry has priority over this one. NOT internal Campaign.id values. See ID types.

mainParameterstring

Filter by mainParameter (a.k.a. opportunity identifier) — the value used to group campaigns into one opportunity. Can be a pool/vault/market address (e.g. 0x35Cbe854...) or an arbitrary on-chain hash. NOT a campaign or opportunity ID. See ID types.

tokenSymbolstring

Filter by reward token symbol (e.g. USDC for campaigns rewarding in USDC)

tokenAddressstring

Filter results by the reward token address. Use in combination with chainId for accuracy

testbooleandefault: false

Return campaigns rewarding in test tokens

tokenTypesenum[]

Filter by token type. Use POINT to include point campaigns and PRETGE to include preTGE campaigns. By default every token is returned.

TOKENPRETGEPOINT
pointboolean

Return campaigns rewarding in points

opportunityIdstring

Filter by internal opportunity ID (Opportunity.id, numeric hash, e.g. 7673870997270712040). Lookup at GET /v4/opportunities. NOT a campaign ID. See ID types.

opportunityIdsstring[]

Filter by multiple internal opportunity IDs. The opportunityId entry has priority over this one. See ID types.

statusstring

Comma-separated list of statuses to filter by. Legal values: LIVE, PAST, SOON. When omitted, returns all campaigns regardless of status.

startTimestampstring

Returns campaigns starting *after* the given unix timestamp

endTimestampstring

Returns campaigns ending *after* the given unix timestamp

withOpportunityboolean

Include opportunity data. Will slow down the request. Default: false

distributionTypesenum[]
FIX_REWARDMAX_REWARDDUTCH_AUCTIONTOTAL_APR
createdAfterDate | string (date-time) | string (date) | number | null
createdBeforeDate | string (date-time) | string (date) | number | null
excludeSubCampaignsbooleandefault: false

Exclude subcampaigns from the results. Default: false

onlySubCampaignsbooleandefault: false

Get Only Subcampaigns. Default: false

rootCampaignIdstring

Filter by root internal campaign ID (Campaign.id, numeric hash). Returns only subcampaigns sharing this root. See ID types.

parentCampaignIdstring

Filter by parent internal campaign ID (Campaign.id, numeric hash). Returns only subcampaigns sharing this parent. See ID types.

mainProtocolIdstring

Filter by protocol slug (e.g. aave, morpho). NOT a numeric ID. List slugs at GET /v4/protocols.

pauseComputestring

Filter by compute-pause reason. Returns only campaigns whose pauseCompute matches this exact reason (e.g. paused_high_amount).

showPrivateboolean

When true, include private campaigns the caller (JWT or API key owner) is authorized to see, decoded. When false (default), only public campaigns are returned. Bypasses CDN cache.

listOwnerstring

Address that owns the campaign lists referenced by campaignLists. Required when campaignLists is set.

campaignListsstring

Comma-separated list names owned by listOwner (stored in the global campaign-lists config). Returns campaigns whose ID is in *any* of the given lists (union). List names are case-insensitive. Lists are shareable — anyone can query any owner's lists. Example: baseapp,renew.

Responses

200
Response for status 200
Schema
object[]
idstringUnique campaign id
computeChainIdnumberChain ID where campaign data is computed
distributionChainIdnumberChain ID where rewards are distributed
campaignIdstringA hash of the campaign, unique per chain. Can be used to identify campaigns across chains
typestringCampaign type identifier
subTypenumber | nullCampaign subtype for protocols like Silo, Radiant, Morpho, Dolomite, Compound, Ajna and Euler
amountstringAmount of reward token units being distributed by the campaign
startTimestampstring | number | string | bigintUnix timestamp when the campaign starts
endTimestampstring | number | string | bigintUnix timestamp when the campaign ends
creatorAddressstringEthereum address of the campaign creator
aprnumberAnnual Percentage Rate for this campaign
dailyRewardsnumberTotal daily rewards distributed in USD
creatorobjectCampaign creator information
addressstring
required
Creator's Ethereum address
tagsstring[]Tag associated with the creator
creatorIdstring | null
paramsanyCampaign-specific parameters
descriptionstringCampaign description
chainobjectChain
idinteger
required
Chain Id
namestring
required
Legible name of the chain
iconstring
required
URL to the icon of the chain
liveCampaignsnumber
required
Number of campaigns currently live on this chain
endOfDisputePeriodnumber
required
explorersobject[]
typeenumETHERSCANBLOCKSCOUTSOLSCAN
urlstring
chainIdnumber
lastClaimsOnchainFetchTimestampstring | null
required
Timestamp of the last claims onchain fetch
rewardTokenIdstringInternal ID of the reward token
rewardTokenobjectToken
idstring
required
Unique identifier for the token
namestring | null
required
Full name of the token
chainIdinteger
required
Chain Id
addressstring
required
Address
decimalsnumber
required
Number of decimals for the token
symbolstring
required
Symbol of the token
iconstring
required
URL to the token icon image
verifiedboolean
required
Whether the token is verified
isNativeboolean
required
Whether this is a native blockchain token
isTestboolean
required
Whether this is a test token
typeenum
required
Type of the token (TOKEN, PRETGE, POINT)TOKENPRETGEPOINT
pricenumber | nullCurrent price of the token in USD
updatedAtnumber | nullUnix timestamp of last price update
priceSourcestring | nullSource of the price information
displaySymbolstringCustom display symbol override
underlyingTokenIdstringIf this token is a wrapper, the ID of the underlying token
priceAlertDismissedAtnumber
priceAlertCountnumber
opportunityIdstringID of the associated opportunity
distributionChainobjectChain
idinteger
required
Chain Id
namestring
required
Legible name of the chain
iconstring
required
URL to the icon of the chain
liveCampaignsnumber
required
Number of campaigns currently live on this chain
endOfDisputePeriodnumber
required
explorersobject[]
typeenumETHERSCANBLOCKSCOUTSOLSCAN
urlstring
chainIdnumber
lastClaimsOnchainFetchTimestampstring | null
required
Timestamp of the last claims onchain fetch
distributionTypeenumType of reward distribution mechanismDUTCH_AUCTIONFIX_REWARD_VALUE_PER_LIQUIDITY_VALUEFIX_REWARD_AMOUNT_PER_LIQUIDITY_VALUEFIX_REWARD_VALUE_PER_LIQUIDITY_AMOUNTFIX_REWARD_AMOUNT_PER_LIQUIDITY_AMOUNTMAX_REWARD_VALUE_PER_LIQUIDITY_VALUEMAX_REWARD_AMOUNT_PER_LIQUIDITY_VALUEMAX_REWARD_VALUE_PER_LIQUIDITY_AMOUNTMAX_REWARD_AMOUNT_PER_LIQUIDITY_AMOUNTAAVE_NET_APRERC4626_APRERC4626_SPREAD_CAPPEDAAVE_V4_NET_APRDEEL_DISTRIBUTIONSOFR_SPREAD_RATCHETERC4626_TARGET_APR_WITH_MERKLTARGET_APR_WITH_MERKLNET_APRBORROW_SUBSIDYNET_APR_WITH_MERKLYIELD_BASIS_PIDCOMPOSED
campaignStatusobject
campaignIdstring
required
computedUntilstring | number | string
required
processingStartedstring | number | string
required
statusstring
required
preComputeProcessingStartedstring | number | string
required
preComputeStatusstring
required
delaynumber | string
errorstring
detailsany
createdAtstring (date)ISO date when the campaign was created
rootCampaignIdstring | nullID of the root campaign for hierarchical campaigns
parentCampaignIdstring | nullID of the parent campaign for sub-campaigns
childCampaignIdsstring[]List of child campaign IDs
dailyRewardsBreakdownobject[]Daily breakdown of rewards
campaignIdstring
valuenumber
maxValuenumber
timestampbigint | string
tokenobjectToken
idstring
required
Unique identifier for the token
namestring | null
required
Full name of the token
chainIdinteger
required
Chain Id
addressstring
required
Address
decimalsnumber
required
Number of decimals for the token
symbolstring
required
Symbol of the token
iconstring
required
URL to the token icon image
verifiedboolean
required
Whether the token is verified
isNativeboolean
required
Whether this is a native blockchain token
isTestboolean
required
Whether this is a test token
typeenum
required
Type of the token (TOKEN, PRETGE, POINT)TOKENPRETGEPOINT
pricenumber | nullCurrent price of the token in USD
updatedAtnumber | nullUnix timestamp of last price update
priceSourcestring | nullSource of the price information
displaySymbolstringCustom display symbol override
underlyingTokenIdstringIf this token is a wrapper, the ID of the underlying token
priceAlertDismissedAtnumber
priceAlertCountnumber
amountbigint | string
distributionTypeenumDUTCH_AUCTIONFIX_REWARD_VALUE_PER_LIQUIDITY_VALUEFIX_REWARD_AMOUNT_PER_LIQUIDITY_VALUEFIX_REWARD_VALUE_PER_LIQUIDITY_AMOUNTFIX_REWARD_AMOUNT_PER_LIQUIDITY_AMOUNTMAX_REWARD_VALUE_PER_LIQUIDITY_VALUEMAX_REWARD_AMOUNT_PER_LIQUIDITY_VALUEMAX_REWARD_VALUE_PER_LIQUIDITY_AMOUNTMAX_REWARD_AMOUNT_PER_LIQUIDITY_AMOUNTAAVE_NET_APRERC4626_APRERC4626_SPREAD_CAPPEDAAVE_V4_NET_APRDEEL_DISTRIBUTIONSOFR_SPREAD_RATCHETERC4626_TARGET_APR_WITH_MERKLTARGET_APR_WITH_MERKLNET_APRBORROW_SUBSIDYNET_APR_WITH_MERKLYIELD_BASIS_PIDCOMPOSED
onChainCampaignIdstring
pauseComputestring | nullISO timestamp when computation was paused
pausePrecomputestring | nullReason for pausing precomputation, or null if not paused
hasOverridesbooleanWhether this campaign has previous config overrides
isPrivatebooleanIndicates if the campaign is private
hiddenbooleanWhether the campaign is hidden from non-test API results
hideLeaderboardbooleanWhether leaderboard, ranks and reward breakdowns are hidden for this campaign
campaignEncodingHashstringHash of the campaign configuration encoding
Example
[
  {
    "id": "string",
    "computeChainId": 0,
    "distributionChainId": 0,
    "campaignId": "string",
    "type": "string",
    "subType": 0,
    "amount": "string",
    "startTimestamp": "string",
    "endTimestamp": "string",
    "creatorAddress": "string",
    "apr": 0,
    "dailyRewards": 0,
    "creator": {
      "address": "string",
      "tags": [
        "string"
      ],
      "creatorId": "string"
    },
    "params": null,
    "description": "string",
    "chain": {
      "id": 0,
      "name": "string",
      "icon": "string",
      "liveCampaigns": 0,
      "endOfDisputePeriod": 0,
      "explorers": [
        {
          "type": null,
          "url": null,
          "chainId": null
        }
      ],
      "lastClaimsOnchainFetchTimestamp": "string"
    },
    "rewardTokenId": "string",
    "rewardToken": {
      "id": "string",
      "name": "string",
      "chainId": 0,
      "address": "string",
      "decimals": 0,
      "symbol": "string",
      "icon": "string",
      "verified": false,
      "isNative": false,
      "isTest": false,
      "type": "TOKEN",
      "price": 0,
      "updatedAt": 0,
      "priceSource": "string",
      "displaySymbol": "string",
      "underlyingTokenId": "string",
      "priceAlertDismissedAt": 0,
      "priceAlertCount": 0
    },
    "opportunityId": "string",
    "distributionChain": {
      "id": 0,
      "name": "string",
      "icon": "string",
      "liveCampaigns": 0,
      "endOfDisputePeriod": 0,
      "explorers": [
        {
          "type": null,
          "url": null,
          "chainId": null
        }
      ],
      "lastClaimsOnchainFetchTimestamp": "string"
    },
    "distributionType": "DUTCH_AUCTION",
    "campaignStatus": {
      "campaignId": "string",
      "computedUntil": "string",
      "processingStarted": "string",
      "status": "string",
      "preComputeProcessingStarted": "string",
      "preComputeStatus": "string",
      "delay": 0,
      "error": "string",
      "details": null
    },
    "createdAt": "date",
    "rootCampaignId": "string",
    "parentCampaignId": "string",
    "childCampaignIds": [
      "string"
    ],
    "dailyRewardsBreakdown": [
      {
        "campaignId": "string",
        "value": 0,
        "maxValue": 0,
        "timestamp": null,
        "token": {
          "id": null,
          "name": null,
          "chainId": null,
          "address": null,
          "decimals": null,
          "symbol": null,
          "icon": null,
          "verified": null,
          "isNative": null,
          "isTest": null,
          "type": null,
          "price": null,
          "updatedAt": null,
          "priceSource": null,
          "displaySymbol": null,
          "underlyingTokenId": null,
          "priceAlertDismissedAt": null,
          "priceAlertCount": null
        },
        "amount": null,
        "distributionType": null,
        "onChainCampaignId": "string"
      }
    ],
    "pauseCompute": "string",
    "pausePrecompute": "string",
    "hasOverrides": false,
    "isPrivate": false,
    "hidden": false,
    "hideLeaderboard": false,
    "campaignEncodingHash": "string"
  }
]