--- title: "GET /v4/users/{address}/rewards/active-opportunities" method: GET path: "/v4/users/{address}/rewards/active-opportunities" tags: ["Users"] --- # GET /v4/users/{address}/rewards/active-opportunities `GET /v4/users/{address}/rewards/active-opportunities` ## Request - Base URL: `https://api.merkl.xyz` (the document declares no server; this is the origin it was published from) - URL: `https://api.merkl.xyz/v4/users/{address}/rewards/active-opportunities` - Auth: `apiKey` (a scheme the document does not define) Active opportunities for a user — LIVE status with rewards still claimable or pending. Aggregated by opportunity and sorted by APR descending. Settled amounts reflect recent distribution state and may be up to 30 minutes behind; pending amounts are computed live. `withStoringIds=true` additionally returns the storingIds backing each opportunity, for mapping the caller's on-chain positions (analytics positions route). ## Path parameters - `address` string, required: User address ## Query parameters - `chainId` string[]: Filter by chain IDs - `tokens` string[]: Filter by reward token addresses - `protocols` string[]: Filter by main protocol IDs - `tags` string[]: Filter by opportunity tags (whitelabel scoping) - `isTest` boolean: Include test token rewards - `isPreTGE` boolean: When true, restrict to preTGE (PRETGE) token rewards - `withStoringIds` boolean: Also return the storingIds backing each opportunity (LIVE root campaigns' full sub-campaign trees), so callers can fetch and map their on-chain positions through the analytics positions route. Off by default so existing consumers keep the endpoint's original latency. ## Response `200` Response for status 200 - object[] - `opportunity` object, required - `id` string, required - `type` string, required - `identifier` string, required - `chainId` number, required - `name` string, required - `description` string, required - `howToSteps` string[], required - `status` union, required - string - string - string - string - `action` union, required - string - string - string - string - string - string - string - string - string - string - `tags` string[], required - `mainProtocol` string - `depositUrl` string - `depositUrls` object[] - `id` string, required - `title` string, required - `url` string, required - `subtitle` string - `icon` string - `priority` number, required - `explorerAddress` string - `hidden` boolean - `tvl` number, required - `apr` number, required - `dailyRewards` number, required - `maxDailyRewards` number - `liveCampaigns` number, required - `lastCampaignCreatedAt` number, required - `earliestCampaignStart` string - `latestCampaignStart` string - `earliestCampaignEnd` string - `latestCampaignEnd` string - `nativeApr` number - `totalApr` number - `maxApr` number - `liveCampaignsForCreator` number - `soonCampaignsForCreator` number - `pastCampaignsForCreator` number - `distributionType` string - `tokens` object[], required - `id` string, required: Unique identifier for the token - `name` string, required: Full name of the token - `chainId` integer, required: Chain Id - `address` string, required: Address - `decimals` number, required: Number of decimals for the token - `symbol` string, required: Symbol of the token - `icon` string, required: URL to the token icon image - `verified` boolean, required: Whether the token is verified - `isNative` boolean, required: Whether this is a native blockchain token - `isTest` boolean, required: Whether this is a test token - `type` union, required: Type of the token (TOKEN, PRETGE, POINT) - string - string - string - `price` number: Current price of the token in USD - `updatedAt` number: Unix timestamp of last price update - `priceSource` string: Source of the price information - `displaySymbol` string: Custom display symbol override - `underlyingTokenId` string: If this token is a wrapper, the ID of the underlying token - `priceAlertDismissedAt` number - `priceAlertCount` number - `chain` object, required: Chain - `id` integer, required: Chain Id - `name` string, required: Legible name of the chain - `icon` string, required: URL to the icon of the chain - `liveCampaigns` number, required: Number of campaigns currently live on this chain - `endOfDisputePeriod` number, required - `explorers` object[] - `type` union, required - string - string - string - `url` string, required - `chainId` number, required - `lastClaimsOnchainFetchTimestamp` string, required: Timestamp of the last claims onchain fetch - `activePrograms` object[], required - `id` string, required - `name` string, required - `slug` string - `description` string - `icon` string - `protocol` object: Protocol - `id` string, required - `name` string, required - `icon` string, required - `tags` string[], required - `description` string, required - `url` string, required - `dailyRewards` number - `numberOfLiveCampaigns` number - `opportunityLiveTags` string[] - `banner` string, required - `opportunityBannerLight` string, required - `opportunityBannerDark` string, required - `trustData` object, required - `slug` string, required - `category` string, required - `audits` string, required - `audit_links` string[], required - `audit_note` string, required - `github` string[], required - `twitter` string, required - `listedAt` number, required - `parentProtocol` string, required - `tvl` number - `hacks` object[] - `date` number, required - `name` string, required - `amountUSD` number, required - `technique` string, required - `source` string, required - `syncedAt` number, required - `aprRecord` object - `cumulated` number, required - `timestamp` string, required - `breakdowns` object[], required - `identifier` string, required - `type` union, required - string - string - string - `value` number, required - `timestamp` string, required - `distributionType` union - string - string - string - string - string - string - string - string - string - string - string - string - string - string - string - string - string - string - string - string - string - string - `nativeAprRecord` object - `title` string, required - `description` string - `value` number, required - `timestamp` string, required - `amount` unknown - `rewardToken` object: Token - `id` string, required: Unique identifier for the token - `name` string, required: Full name of the token - `chainId` integer, required: Chain Id - `address` string, required: Address - `decimals` number, required: Number of decimals for the token - `symbol` string, required: Symbol of the token - `icon` string, required: URL to the token icon image - `verified` boolean, required: Whether the token is verified - `isNative` boolean, required: Whether this is a native blockchain token - `isTest` boolean, required: Whether this is a test token - `type` union, required: Type of the token (TOKEN, PRETGE, POINT) - string - string - string - `price` number: Current price of the token in USD - `updatedAt` number: Unix timestamp of last price update - `priceSource` string: Source of the price information - `displaySymbol` string: Custom display symbol override - `underlyingTokenId` string: If this token is a wrapper, the ID of the underlying token - `priceAlertDismissedAt` number - `priceAlertCount` number - `breakdowns` object[] - `title` string, required - `description` string - `value` number, required - `amount` unknown - `rewardToken` object: Token - `id` string, required: Unique identifier for the token - `name` string, required: Full name of the token - `chainId` integer, required: Chain Id - `address` string, required: Address - `decimals` number, required: Number of decimals for the token - `symbol` string, required: Symbol of the token - `icon` string, required: URL to the token icon image - `verified` boolean, required: Whether the token is verified - `isNative` boolean, required: Whether this is a native blockchain token - `isTest` boolean, required: Whether this is a test token - `type` union, required: Type of the token (TOKEN, PRETGE, POINT) - string - string - string - `price` number: Current price of the token in USD - `updatedAt` number: Unix timestamp of last price update - `priceSource` string: Source of the price information - `displaySymbol` string: Custom display symbol override - `underlyingTokenId` string: If this token is a wrapper, the ID of the underlying token - `priceAlertDismissedAt` number - `priceAlertCount` number - `tvlRecord` object - `total` number, required - `timestamp` string, required - `breakdowns` object[], required - `identifier` string, required - `type` union, required - string - string - `value` number, required - `rewardsRecord` object - `total` number, required - `timestamp` string, required - `breakdowns` object[], required - `campaignId` string, required - `value` number, required - `maxValue` number - `timestamp` string, required - `token` object, required: Token - `id` string, required: Unique identifier for the token - `name` string, required: Full name of the token - `chainId` integer, required: Chain Id - `address` string, required: Address - `decimals` number, required: Number of decimals for the token - `symbol` string, required: Symbol of the token - `icon` string, required: URL to the token icon image - `verified` boolean, required: Whether the token is verified - `isNative` boolean, required: Whether this is a native blockchain token - `isTest` boolean, required: Whether this is a test token - `type` union, required: Type of the token (TOKEN, PRETGE, POINT) - string - string - string - `price` number: Current price of the token in USD - `updatedAt` number: Unix timestamp of last price update - `priceSource` string: Source of the price information - `displaySymbol` string: Custom display symbol override - `underlyingTokenId` string: If this token is a wrapper, the ID of the underlying token - `priceAlertDismissedAt` number - `priceAlertCount` number - `amount` string, required - `distributionType` union - string - string - string - string - string - string - string - string - string - string - string - string - string - string - string - string - string - string - string - string - string - string - `onChainCampaignId` string - `campaigns` object[] - `id` string, required: Unique campaign id - `computeChainId` number, required: Chain ID where campaign data is computed - `distributionChainId` number, required: Chain ID where rewards are distributed - `campaignId` string, required: A hash of the campaign, unique per chain. Can be used to identify campaigns across chains - `type` string, required: Campaign type identifier - `subType` number: Campaign subtype for protocols like Silo, Radiant, Morpho, Dolomite, Compound, Ajna and Euler - `amount` string, required: Amount of reward token units being distributed by the campaign - `startTimestamp` union, required: Unix timestamp when the campaign starts - string - string, numeric - number - `endTimestamp` union, required: Unix timestamp when the campaign ends - string - string, numeric - number - `creatorAddress` string, required: Ethereum address of the campaign creator - `apr` number: Annual Percentage Rate for this campaign - `dailyRewards` number: Total daily rewards distributed in USD - `creator` object: Campaign creator information - `address` string, required: Creator's Ethereum address - `tags` string[]: Tag associated with the creator - `creatorId` string, nullable: Merkl creator ID if registered - `params` unknown, required - `description` string: Campaign description - `chain` object, required: Chain - `id` integer, required: Chain Id - `name` string, required: Legible name of the chain - `icon` string, required: URL to the icon of the chain - `liveCampaigns` number, required: Number of campaigns currently live on this chain - `endOfDisputePeriod` number, required - `explorers` object[] - `type` union, required - string - string - string - `url` string, required - `chainId` number, required - `lastClaimsOnchainFetchTimestamp` string, required: Timestamp of the last claims onchain fetch - `rewardTokenId` string: Internal ID of the reward token - `rewardToken` object, required: Token - `id` string, required: Unique identifier for the token - `name` string, required: Full name of the token - `chainId` integer, required: Chain Id - `address` string, required: Address - `decimals` number, required: Number of decimals for the token - `symbol` string, required: Symbol of the token - `icon` string, required: URL to the token icon image - `verified` boolean, required: Whether the token is verified - `isNative` boolean, required: Whether this is a native blockchain token - `isTest` boolean, required: Whether this is a test token - `type` union, required: Type of the token (TOKEN, PRETGE, POINT) - string - string - string - `price` number: Current price of the token in USD - `updatedAt` number: Unix timestamp of last price update - `priceSource` string: Source of the price information - `displaySymbol` string: Custom display symbol override - `underlyingTokenId` string: If this token is a wrapper, the ID of the underlying token - `priceAlertDismissedAt` number - `priceAlertCount` number - `opportunityId` string: ID of the associated opportunity - `distributionChain` object: Chain - `id` integer, required: Chain Id - `name` string, required: Legible name of the chain - `icon` string, required: URL to the icon of the chain - `liveCampaigns` number, required: Number of campaigns currently live on this chain - `endOfDisputePeriod` number, required - `explorers` object[] - `type` union, required - string - string - string - `url` string, required - `chainId` number, required - `lastClaimsOnchainFetchTimestamp` string, required: Timestamp of the last claims onchain fetch - `distributionType` union: Type of reward distribution mechanism - string - string - string - string - string - string - string - string - string - string - string - string - string - string - string - string - string - string - string - string - string - string - `campaignStatus` object, required - `campaignId` string, required - `computedUntil` union, required - string - string, numeric - number - `processingStarted` union, required - string - string, numeric - number - `status` string, required - `preComputeProcessingStarted` union, required - string - string, numeric - number - `preComputeStatus` string, required - `delay` union - string, numeric - number - `error` string - `details` unknown - `createdAt` string, date, required: ISO date when the campaign was created - `rootCampaignId` string: ID of the root campaign for hierarchical campaigns - `parentCampaignId` string: ID of the parent campaign for sub-campaigns - `childCampaignIds` string[]: List of child campaign IDs - `dailyRewardsBreakdown` object[]: Daily breakdown of rewards - `campaignId` string, required - `value` number, required - `maxValue` number - `timestamp` string, required - `token` object, required: Token - `id` string, required: Unique identifier for the token - `name` string, required: Full name of the token - `chainId` integer, required: Chain Id - `address` string, required: Address - `decimals` number, required: Number of decimals for the token - `symbol` string, required: Symbol of the token - `icon` string, required: URL to the token icon image - `verified` boolean, required: Whether the token is verified - `isNative` boolean, required: Whether this is a native blockchain token - `isTest` boolean, required: Whether this is a test token - `type` union, required: Type of the token (TOKEN, PRETGE, POINT) - string - string - string - `price` number: Current price of the token in USD - `updatedAt` number: Unix timestamp of last price update - `priceSource` string: Source of the price information - `displaySymbol` string: Custom display symbol override - `underlyingTokenId` string: If this token is a wrapper, the ID of the underlying token - `priceAlertDismissedAt` number - `priceAlertCount` number - `amount` string, required - `distributionType` union - string - string - string - string - string - string - string - string - string - string - string - string - string - string - string - string - string - string - string - string - string - string - `onChainCampaignId` string - `pauseCompute` string: ISO timestamp when computation was paused - `pausePrecompute` string: Reason for pausing precomputation, or null if not paused - `hasOverrides` boolean: Whether this campaign has previous config overrides - `isPrivate` boolean, required: Indicates if the campaign is private - `hidden` boolean: Whether the campaign is hidden from non-test API results - `hideLeaderboard` boolean: Whether leaderboard, ranks and reward breakdowns are hidden for this campaign - `campaignEncodingHash` string: Hash of the campaign configuration encoding - `earnedTokens` object[], required - `token` object, required: Token - `id` string, required: Unique identifier for the token - `name` string, required: Full name of the token - `chainId` integer, required: Chain Id - `address` string, required: Address - `decimals` number, required: Number of decimals for the token - `symbol` string, required: Symbol of the token - `icon` string, required: URL to the token icon image - `verified` boolean, required: Whether the token is verified - `isNative` boolean, required: Whether this is a native blockchain token - `isTest` boolean, required: Whether this is a test token - `type` union, required: Type of the token (TOKEN, PRETGE, POINT) - string - string - string - `price` number: Current price of the token in USD - `updatedAt` number: Unix timestamp of last price update - `priceSource` string: Source of the price information - `displaySymbol` string: Custom display symbol override - `underlyingTokenId` string: If this token is a wrapper, the ID of the underlying token - `priceAlertDismissedAt` number - `priceAlertCount` number - `amount` string, required: Total earned (live tree + pending) in token wei - `chain` object, required: Chain - `id` integer, required: Chain Id - `name` string, required: Legible name of the chain - `icon` string, required: URL to the icon of the chain - `liveCampaigns` number, required: Number of campaigns currently live on this chain - `endOfDisputePeriod` number, required - `explorers` object[] - `type` union, required - string - string - string - `url` string, required - `chainId` number, required - `lastClaimsOnchainFetchTimestamp` string, required: Timestamp of the last claims onchain fetch - `storingIds` object[]: Only when `withStoringIds=true`: every storingId of the LIVE root campaigns' full sub-campaign trees. Use them to fetch and map the caller's on-chain positions via `GET /v4/analytics/positions/{address}?indexingIds=...` (that route names the same value `indexingId`). Empty array = resolved, nothing backs this opportunity; field absent = resolution failed for this opportunity (the rest of the response is unaffected). - `id` string, required: Indexing/storingId under which positions backing this opportunity are tracked - `viaSubCampaign` boolean: True when this storingId belongs to a sub-campaign only (forwarded/wrapper position, e.g. held via a vault) rather than a root campaign ## Changes - **2026-09-02** `b7784c9a78b9`: 3 info - added `subschema #1, subschema #2` to the `items/opportunity` response property `allOf` list for the response status `200` - removed `subschema #1, subschema #2` from the `items/opportunity` response property `allOf` list for the response status `200` - the `items/earnedTokens/items/token/address` response's property pattern was changed from `^(0x[a-fA-F0-9]{40}|[1-9A-HJ-NP-Za-km-z]{32,44}|[CG][A-Z0-9]{55})$` to `^(0x[a-fA-F0-9]{40}|[1-9A-HJ-NP-Za-km-z]{32,44}|[CG][A-Z0-9]{55}|0x[a-fA-F0-9]{64})$` for the status `200` [Operation history](https://skmtc.dev/merkl/apis/merkl-api/changes/v4/users/:address/rewards/active-opportunities/get.md) --- [API](https://skmtc.dev/merkl/apis/merkl-api.md) - [All operations](https://skmtc.dev/merkl/apis/merkl-api/llms.txt) - [OpenAPI document](https://skmtc.dev/merkl/apis/merkl-api/revisions/60ffe2c7d887?raw)