Merkl Developer Portal logo
get

/v4/opportunities/

Retrieve Multiple Opportunities

This endpoint enables you to search for opportunities by providing specific criteria through query parameters.

Request Examples

List opportunities by protocol name
curl "https://api.merkl.xyz/v4/opportunities?name=Euler"

Returns all opportunities associated with the Euler protocol, including aggregate metrics.

Filter by tag
curl "https://api.merkl.xyz/v4/opportunities?tags=zksync"

Returns opportunities tagged with "zksync" across all supported protocols.

Query parameters

pagenumber | stringdefault: 0

0-indexed page number

itemsnumber | stringdefault: 20

Number of items returned by page

namestring

Filter by name

searchstring

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

campaignIdstring

Filter opportunities linked to a given on-chain campaign ID (32-byte hex hash, e.g. 0x93cf385c2a446a7596820601caf25e63bfc4939efa9a89a6f21563b58ee54eb1). This is Campaign.campaignId in responses, NOT the internal Campaign.id (numeric hash). Returns [] if no campaign matches. See ID types.

creatorSlugstring

Filter by creator slug

chainIdstring

A comma separated list of chain ids. Example: ?chainId=1,42161
You can get the list of all supported chains by calling GET /v4/chains

actionstring

A comma seprated list actions. Legal values are: POOL, HOLD, DROP, LEND, BORROW, LONG, SHORT, SWAP, INVALID, STAKE

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

Include opportunities with point campaigns

typestring

A comma separated list of Opportunity type

creatorAddressstring

Filter by creator address

tagsstring

Filter by tag

testbooleandefault: false

Include opportunities with test campaigns

minimumTvlnumber

Minimum TVL threshold in USD

maximumTvlnumber

Maximum TVL threshold in USD

minimumAprnumber

Minimum APR threshold

maximumAprnumber

Maximum APR threshold

minimumDailyRewardsnumber

Minimum daily rewards threshold in USD

maximumDailyRewardsnumber

Maximum daily rewards threshold in USD

minimumCreatedAtnumber

Filter opportunities whose last campaign was created at or after this Unix timestamp (seconds)

maximumCreatedAtnumber

Filter opportunities whose last campaign was created at or before this Unix timestamp (seconds)

statusstring

A comma separeted list of status. Legal values are: LIVE, PAST, SOON

identifierstring

Filter by opportunity identifier (a.k.a. mainParameter). Free-form string, often a pool/vault/market address (e.g. 0x35Cbe8542E70fa2f7F9cDF129F19e593F4b4f560) or an arbitrary on-chain hash for non-address opportunities. NOT a campaign ID. See ID types.

idstring

A comma-separated list of internal opportunity IDs (Opportunity.id, numeric hash). Example: ?id=5877322385708089533,1234567890. NOT campaign IDs. See ID types.

campaignsboolean

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

tokensstring

A comma separated list of token symbol. Use to filter by token

stablecoinbooleandefault: false

Filter opportunities that include at least one stablecoin token

rewardTokenSymbolstring

Filter by opportunity that have at least 1 campaigns where the reward token has this symbol

sortstring

Sort by apr, tvl, rewards, maxDailyRewards, last campaign creation date, campaign start times, or campaign end times

orderstringdefault: desc

asc to sort in ascending order or desc to sort in descending order.

distributionTypesenum[]
FIX_REWARDMAX_REWARDDUTCH_AUCTIONTOTAL_APR
mainProtocolIdstring

A comma-separated list of protocol slugs (e.g. aave,morpho,uniswap). NOT numeric IDs. List slugs at GET /v4/protocols. See ID types.

programSlugsstring

A comma separated list of program ids or slugs. You can get the list of all supported programs by calling GET /v4/programs

chainNamestring

A comma separated list of chain names. Example: ?chainName=ethereum,arbitrum

excludeSubCampaignsbooleandefault: false

Exclude sub-campaigns from the results. Default: false

explorerAddressstring

Filter by on-chain pool/vault/market address (20-byte EVM address, e.g. 0x35Cbe8542E70fa2f7F9cDF129F19e593F4b4f560). Often the most reliable way to look up an opportunity if you only know the underlying contract. See ID types.

withInvalidsbooleandefault: false

Include opportunities that have been marked as invalid

campaignTypesstring

A comma separated list of CampaignType enum numeric values. Example: ?campaignTypes=18,19

Responses

200
Response for status 200
Schema
object | null[]
idstring
typestring
identifierstring
chainIdnumber
namestring
descriptionstring
howToStepsstring[]
statusenumNONEPASTLIVESOON
actionenumPOOLHOLDDROPLENDBORROWLONGSHORTSWAPINVALIDSTAKE
tagsstring[]
mainProtocolstring
depositUrlstring
depositUrlsobject[]
idstring
titlestring
urlstring
subtitlestring
iconstring
prioritynumber
explorerAddressstring
hiddenboolean
tvlnumber
aprnumber
dailyRewardsnumber
maxDailyRewardsnumber | null
liveCampaignsnumber
lastCampaignCreatedAtnumber
earliestCampaignStartbigint | string
latestCampaignStartbigint | string
earliestCampaignEndbigint | string
latestCampaignEndbigint | string
nativeAprnumber
totalAprnumber
maxAprnumber | null
liveCampaignsForCreatornumber
soonCampaignsForCreatornumber
pastCampaignsForCreatornumber
distributionTypestring
tokensobject[]
idstringUnique identifier for the token
namestring | nullFull name of the token
chainIdintegerChain Id
addressstringAddress
decimalsnumberNumber of decimals for the token
symbolstringSymbol of the token
iconstringURL to the token icon image
verifiedbooleanWhether the token is verified
isNativebooleanWhether this is a native blockchain token
isTestbooleanWhether this is a test token
typeenumType 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
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
activeProgramsobject[]
idstring
namestring
slugstring | null
descriptionstring
iconstring
protocolobject | null
idstring
namestring
iconstring
tagsstring[]
descriptionstring
urlstring
dailyRewardsnumber
numberOfLiveCampaignsnumber
opportunityLiveTagsstring[]
bannerstring | null
opportunityBannerLightstring | null
opportunityBannerDarkstring | null
trustDataobject | null
slugstring
categorystring | null
auditsstring | null
audit_linksstring[]
audit_notestring | null
githubstring[]
twitterstring | null
listedAtnumber | null
parentProtocolstring | null
tvlnumber | null
hacksobject[]
datenumber
namestring | null
amountUSDnumber | null
techniquestring | null
sourcestring | null
syncedAtnumber
aprRecordobject
cumulatednumber
required
timestampbigint | string
required
breakdownsobject[]
required
identifierstring
typeenumCAMPAIGNTOKENPROTOCOL
valuenumber
timestampbigint | 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
nativeAprRecordobject
titlestring
required
descriptionstring
valuenumber
required
timestampbigint | string
required
amountbigint
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
breakdownsobject[]
titlestring
descriptionstring
valuenumber
amountbigint
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
tvlRecordobject
totalnumber
required
timestampbigint | string
required
breakdownsobject[]
required
identifierstring
typeenumTOKENPROTOCOL
valuenumber
rewardsRecordobject
totalnumber
required
timestampbigint | string
required
breakdownsobject[]
required
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
Example
[
  {}
]