Sign in
Opportunities

Retrieve Multiple Opportunities

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

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.

get/v4/opportunities/

Query parameters

string numeric
OR
number

0-indexed page number

string numeric
OR
number

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

{"stackTrail":"paths:/v4/opportunities/:get:parameters:6:schema","oasType":"schema","type":"unknown","description":"A comma separated list of chain ids. Example: ?chainId=1,42161<br>You can get the list of all supported chains by calling [GET /v4/chains](#tag/chains/GET/v4/chains/)"}
actionstring

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

pointboolean

Include opportunities with point campaigns

typestring

A comma separated list of Opportunity type

creatorAddressstring

Filter by creator address

tagsstring

Filter by tag

testboolean

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)

{"stackTrail":"paths:/v4/opportunities/:get:parameters:22:schema","oasType":"schema","type":"unknown","description":"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

stablecoinboolean

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

{"stackTrail":"paths:/v4/opportunities/:get:parameters:29:schema","oasType":"schema","type":"unknown","description":"Sort by `apr`, `tvl`, `rewards`, `maxDailyRewards`, last campaign creation date, campaign start times, or campaign end times"}
orderstring

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

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

{"stackTrail":"paths:/v4/opportunities/:get:parameters:34:schema","oasType":"schema","type":"unknown","description":"A comma separated list of chain names. Example: ?chainName=ethereum,arbitrum"}
excludeSubCampaignsboolean

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.

withInvalidsboolean

Include opportunities that have been marked as invalid

{"stackTrail":"paths:/v4/opportunities/:get:parameters:38:schema","oasType":"schema","type":"unknown","description":"A comma separated list of CampaignType enum numeric values. Example: ?campaignTypes=18,19"}

Response

Response for status 200

Changes

Changed in 1 of the 2 revisions of this API.2

  • b7784c9a78b92See the full diff
    • ○

      added subschema #1 subschema #2 to the response property anyOf list for the response status

      response-property-any-of-added

    • ○

      removed subschema #1 subschema #2 from the response property anyOf list for the response status

      response-property-any-of-removed