Merkl API
206 endpoints · v1.0.1https://api.merkl.xyz/View as MarkdownThe official API to access data related to Merkl campaigns, built and maintained by Merkl SAS. This API is provided as is, without any warranty of any kind.
Opportunities
Core
14
get
/v4/opportunities/{id}Get a unique opportunity by ID (hash) or composite identifier (chainId-type-identifier). Use quer…get
/v4/opportunities/{id}/storing-idsGet the storingId(s) backing an opportunity, grouped by root campaign. Returns one tree per root …get
/v4/opportunities/{id}/campaignsGet a unique opportunity by ID (hash) or composite identifier (chainId-type-identifier), includin…get
/v4/opportunities/{id}/apr-recordsGet historical APR records for an opportunity.get
/v4/opportunities/{id}/tvl-recordsGet historical TVL records for an opportunity.get
/v4/opportunities/{id}/native-apr-recordsGet historical native APR records for an opportunity.get
/v4/opportunities/Retrieve Multiple Opportunitiesget
/v4/opportunities/countGet the count of opportunities corresponding to the query.get
/v4/opportunities/bins/aprGet the APR distribution of opportunities matching the query, grouped into bins.get
/v4/opportunities/bins/tvlGet the TVL distribution of opportunities matching the query, grouped into bins.get
/v4/opportunities/bins/daily-rewardsGet the daily rewards distribution of opportunities matching the query, grouped into bins.get
/v4/opportunities/aggregate/{field}Aggregate opportunities by a specific field (chainId, protocolId, tags, etc.).get
/v4/opportunities/aggregate/max/{field}Get the maximum value for a specific field across filtered opportunities.get
/v4/opportunities/aggregate/min/{field}Get the minimum value for a specific field across filtered opportunities.Campaigns
Core
9
get
/v4/campaigns/{id}Retrieve a campaign by its unique identifier (hash or distributionChain-campaignId format) in the…post
/v4/campaigns/generate-payloadGenerate an on-chain transaction payload for creating one or more campaigns from the provided data.get
/v4/campaigns/{id}/metricsGet historical metrics (TVL, APR, daily rewards) for a campaign, with pagination options.get
/v4/campaigns/{id}/storing-idsGet the storingId(s) backing a campaign as a tree. The root node's storingIds belong to the campa…get
/v4/campaigns/{id}/linkedGet every opportunity linked to a campaign — its full chain of parent campaigns up to the root, p…get
/v4/campaigns/txGet campaign IDs from a creation transaction hashget
/v4/campaigns/Search for campaigns matching the criteria provided through query parameters.get
/v4/campaigns/countCount the campaigns matching the filters provided through query parameters.get
/v4/campaigns/aggregateAggregate all campaigns matching the provided filters and return a per-token breakdown of total a…Users
Core
14
get
/v4/users/{address}/rewardsGet the rewards associated to a user on a given chain.get
/v4/users/{address}/protocols/{protocolId}/rewardsRetrieve claimable rewards for a user scoped to a single protocol. Breakdowns and amounts reflect…get
/v4/users/{address}/termsCheck if a user address has signed Merkl's terms for a specific chain. Provide the user's wallet …get
/v4/users/{address}/recipient/{token}Get the recipient address for a given user address and specific token.get
/v4/users/{address}/operator/{operatorAddress}Check if an address is an operator for a given user address.get
/v4/users/{address}/wrappedGet a summary of a user's claimed rewards, including their most-used protocol and most-claimed to…get
/v4/users/{address}/rewards/statsLightweight USD totals for a user — total earned, currently claimable, and pending. Supports opti…get
/v4/users/{address}/rewards/summaryPer-chain rewards rollup with USD totals and per-token raw amounts. A lightweight alternative to …get
/v4/users/{address}/rewards/active-opportunitiesActive opportunities for a user — LIVE status with rewards still claimable or pending. Aggregated…get
/v4/users/{address}/rewards/chains/{chainId}/breakdownsPer-chain opportunity breakdown for a user. Aggregated by opportunity with one row per token carr…get
/v4/users/{address}/rewards/breakdownsPer-chain rewards with full opportunity breakdowns and proofs. Returns the same shape as /v4/user…post
/v4/internal/users/get
/v4/internal/users/tagspatch
/v4/internal/users/{address}/tagsChains
Core
2
Protocols
Core
3
get
/v4/protocols/List protocols supported and integrated by Merkl. Use query parameters to filter by chain ID, tag…get
/v4/protocols/countGet the number of protocols corresponding to the query. Use query parameters to filter the count.get
/v4/protocols/{id}Get a protocol by its ID or name using id path parameter. This endpoint searches by protocol ID f…Tokens
Core
5
get
/v4/tokens/prices/historyGet historical price snapshots for a token. Resolve by symbol (optionally scoped to a chainId) or…get
/v4/tokens/rewardGet all tokens that are accepted as reward tokens across all chains.get
/v4/tokens/reward/{chainId}Get the list of tokens that are accepted as reward tokens on a given chain.post
/v4/tokens/whitelistSubmit a token whitelist request for review.post
/v4/engine/tokens/syntheticUpsert a synthetic token with engine-provided metadata (no on-chain fetch)Rewards
Rewards
11
get
/v4/rewards/Returns all the addresses that received rewards for a given campaign, sorted by descending amount…get
/v4/rewards/totalReturns the total amount distributed for a given campaign. Use query parameters to specify campai…get
/v4/rewards/countReturns the number of recipients that earned rewards in a given campaign. Use query parameters to…get
/v4/rewards/rankReturns the rank of a user in a campaign leaderboard, based on reward amount. Returns an empty ar…get
/v4/rewards/campaign/{campaignId}/listGet rewards for a specific campaign by campaignId path parameter and list of addressesget
/v4/rewards/token/Returns all the addresses that received rewards of a given token, sorted by descending amounts. U…get
/v4/rewards/token/totalReturns the total amount distributed for a given token. Use query parameters to specify token add…get
/v4/rewards/token/countReturns the number of recipients that earned rewards in a given token. Use query parameters to sp…get
/v4/rewards/token/unclaimedReturns the total unclaimed amount (distributed minus claimed) for a given token. Use query param…get
/v4/rewards/unclaim/Returns the total of unclaimed rewards for given campaigns. Use query parameters to specify chain…post
/v4/rewards/unclaim/batchReturns unclaimed rewards for campaigns across multiple chains in a single call. Pass an array of…Claims
Rewards
5
get
/v4/claims/Fetch claims filtered by chainId(s), recipient, campaignId, token, root, exact reason, and an inc…get
/v4/claims/history/{address}Fetch a recipient's historical claims, grouped per claim transaction with amounts aggregated by t…get
/v4/claims/earnings/{address}Aggregate a recipient's claimed rewards into time buckets broken down by token, in USD. Supports …get
/v4/claims/countReturns the total number of unique claimers on a specific chain.get
/v4/claims/count/totalReturns the total number of unique claimers across all chains.Credits
Rewards
9
get
/v4/credits/pricingGet points-campaign billing pricing constants (USD)post
/v4/credits/estimateEstimate the credit cost of a points campaign's next run, mirroring the engine pre-check. Returns…post
/v4/credits/estimate/totalEstimate the total credit cost of a points campaign over its full duration (endTimestamp − startT…get
/v4/credits/{creatorId}Get credit balance for a creatorget
/v4/credits/{creatorId}/operationsList credit operations for a creatorget
/v4/credits/{creatorId}/operations/countGet the number of credit operations for a creator, optionally filtered by typeget
/v4/credits/{creatorId}/operations/aggregateGet the signed sum of credit operations for a creator. SUBTRACT amounts count as negative, ADD as…get
/v4/credits/{creatorId}/operations/breakdownsGet credit operations grouped by category with signed totals. All Auto-claim labels are bucketed …get
/v4/credits/{creatorId}/paused-campaignsCount campaigns paused due to insufficient credits for a creatorCreator
Rewards
9
get
/v4/creators/Retrieves all creators matching the provided query filtersget
/v4/creators/{creator}Retrieves a specific creator by their ID or slugget
/v4/creators/{creator}/dashboardReturns dashboard metrics and overview for a specific creatorget
/v4/creators/{creator}/opportunities/countReturns the total count of opportunities for a specific creatorget
/v4/creators/{creator}/opportunitiesReturns paginated opportunities for a specific creator. Use page, items, and other query paramete…get
/v4/creators/{creator}/campaignsReturns all campaigns for a specific creator. Filter by status query parameter.get
/v4/creators/campaigns/{campaignId}Returns campaign metrics for a specific campaign. Use campaignId path parameter and pagination qu…get
/v4/creators/{creator}/opportunity/{opportunityId}/metricsReturns opportunity metrics for a specific creator and opportunity combinationget
/v4/creators/{creator}/distributed/over-timeToken distribution over time for a creator, bucketed and broken down per reward token (token amou…Programs
Rewards
3
Campaign Lists
Rewards
6
get
/v4/campaign-lists/{owner}List every named campaign list owned by an address, with its size and last-updated timestamp.get
/v4/campaign-lists/{owner}/{name}Get the campaign IDs in a single named list. Returns 404 if the list does not exist.put
/v4/campaign-lists/{owner}/{name}Replace the campaign IDs in a named list (an empty array deletes the list). Requires the owner's …delete
/v4/campaign-lists/{owner}/{name}Delete a named list entirely. Requires the owner's JWT or API key. No-op if the list does not exist.post
/v4/campaign-lists/{owner}/{name}/addAppend campaign IDs to a list, creating it if it does not exist. Requires the owner's JWT or API …post
/v4/campaign-lists/{owner}/{name}/removeRemove the provided campaign IDs from a list. If the list becomes empty, it is deleted. Requires …Campaign Privacy
Rewards
3
Referral
Rewards
2
Reallocations
Rewards
1
Templates
Rewards
3
Overrides
Rewards
2
Historical
Rewards
3
SOFR Spread Ratchet
Rewards
2
Block Timestamp
Rewards
3
get
/v4/block-timestamp/blockGet the closest block number to a given timestamp on a specific chainget
/v4/block-timestamp/timestampGet the closest timestamp to a given block number on a specific chainget
/v4/block-timestamp/boundsGet the closest lower and upper bound blocks for a given timestamp from BlockTimestampMappingDeveloper API Keys
Internal
7
post
/v4/developer/keys/Create a new API key. The raw key is returned only once.get
/v4/developer/keys/List all API keys for the authenticated user.get
/v4/developer/keys/usageGet usage summary across all API keys for the authenticated user.get
/v4/developer/keys/{id}/usageGet detailed daily usage for a specific API key.patch
/v4/developer/keys/{id}Update description for an API key.delete
/v4/developer/keys/{id}Revoke an API key.get
/v4/api-keys/validateValidate a developer API key. Returns { ok: true } on success, 401 otherwise.Authentication
Internal
7
get
/v4/auth/nonce/{address}Generate a unique nonce and message for wallet authentication.post
/v4/auth/loginAuthenticate a user and set a JWT cookie for session management.get
/v4/auth/google/startStart the Google OAuth flow for signing in with a Google account.get
/v4/auth/google/callbackComplete the Google OAuth flow and create or refresh the user session.post
/v4/auth/link/walletLink a wallet to the current (Google) session — collapses both into one wallet identity.get
/v4/auth/meGet authenticated user information including address, profile, and authentication status.delete
/v4/auth/revokeRevoke the current user's JWT token and clear the session cookie.Config
Internal
19
get
/v4/config/{id}Beta feature (not production ready yet) - Fetch the configuration for a specific campaign by its …post
/v4/config/diffCompute the diff between two config schemas. Returns an array of edit operations (insert/update/d…post
/v4/config/diff/{id}Compute the diff between the current config of a campaign and a new one. Returns an array of edit…post
/v4/config/extendBeta feature (not production ready yet) - Extends a campaign configuration with the values resolv…post
/v4/config/opportunityBeta feature (not production ready yet) - Computes an opportunity from a campaign configurationpost
/v4/config/tvlBeta feature (not production ready yet) - Computes a TVL from a campaign configurationpost
/v4/config/encodeBeta feature (not production ready yet) - Encodes campaign parameters into the transaction payloa…post
/v4/config/encode/overrideBeta feature (not production ready yet) - Builds the transaction payload used to override (or can…post
/v4/config/encode/reallocateBeta feature (not production ready yet) - Builds the transaction payload used to reallocate an ex…post
/v4/config/encode/safeBeta feature (not production ready yet) - Encodes campaign config to Safe transaction payload. Us…post
/v4/config/encode/batchBeta feature (not production ready yet) - Encodes a batch of campaign parameters into transaction…post
/v4/config/encode/batch/safeBeta feature (not production ready yet) - Encodes batch campaign configs to Safe transaction payl…get
/v4/config/decode/onchain/{distributionChainId}/{campaignId}Decodes an on-chain campaign configuration. Use distributionChainId and campaignId path parameters.post
/v4/config/decode/{distributionChainId}Decodes campaign data from the Distribution contract. Use distributionChainId path parameter and …get
/v4/config/decode/{distributionChainId}/{payload}Decodes campaign from a raw payload. Use distributionChainId and payload (hex string) path parame…post
/v4/config/decode/safeDecodes a Safe transaction payload back to the original campaign configurations. Returns an array…post
/v4/config/decode/args/createCampaignDecodes arguments of the create campaign function back to the original campaign configuration.post
/v4/config/storeStores campaign configurations keyed by their hash. Provide the campaign configuration payload in…get
/v4/config/hash/{hash}Gets a campaign configuration by its hash. If campaignId and distributionChainId are provided, as…Key Value Store
Internal
17
put
/v4/key-value-stores/{key}/entriesUpsert a single entry. Authenticate with a JWT for user access, or an X-API-Key header for servic…get
/v4/key-value-stores/{key}/entriesList entries. Public for stores configured as publicly readable; otherwise requires authentication.put
/v4/key-value-stores/{key}/entries/batchBatch upsert entries. Requires X-API-Key authentication.get
/v4/key-value-stores/{key}/entries/{address}Get a single entry by addressdelete
/v4/key-value-stores/{key}/entries/{address}Delete an entry. Users may delete their own entry; the store owner or an X-API-Key holder may del…post
/v4/key-value-stores/selfCreate a key-value store you own (allowlisted users, X-API-Key). key is a suffix; the response re…get
/v4/key-value-stores/selfList the key-value stores you own (X-API-Key)patch
/v4/key-value-stores/self/{key}Update a key-value store you own by its canonical key (X-API-Key)delete
/v4/key-value-stores/self/{key}Delete a key-value store you own (by canonical key) and all its entries (X-API-Key)post
/v4/internal/key-value-storesCreate a new key-value store config (BackOffice only)get
/v4/internal/key-value-storesList all key-value store configs (BackOffice only)patch
/v4/internal/key-value-stores/{key}Update a config (BackOffice only)delete
/v4/internal/key-value-stores/{key}Delete a config and all entries (BackOffice only)post
/v4/internal/key-value-stores/quotasGrant a self-serve creator quota (BackOffice only)get
/v4/internal/key-value-stores/quotasList all self-serve creator quotas (BackOffice only)patch
/v4/internal/key-value-stores/quotas/{address}Update a creator quota (BackOffice only)delete
/v4/internal/key-value-stores/quotas/{address}Revoke a creator quota (BackOffice only)Node
Internal
6
get
/v4/nodeCheck if an address was already labelled as specific by the Merkl Engine.get
/v4/node/protocolsGet the list of protocols that have indexed node sources available.get
/v4/node/protocol/{protocol}/chainsGet the chains configured for a specific protocol.get
/v4/node/last-blockGet the most recent indexed block. If a protocol is provided, returns it for that protocol on the…get
/v4/node/oldest-blockGet the oldest indexed block. If a protocol is provided, returns it for that protocol on the give…get
/v4/node/block-differenceGet the block difference (oldest to current). If a protocol is provided, returns it for that prot…Leaves
Internal
2
Roots
Internal
2
Enums
Internal
4
get
/v4/enums/List all available enums in the system. Returns enum names, types (string/number), and metadata a…get
/v4/enums/{enumName}Get detailed information about a specific enum including all entries with their values, names, an…get
/v4/enums/{enumName}/convert/{value}Convert an enum value bidirectionally. For number enums: provide a number to get its string name.…post
/v4/enums/{enumName}/batch-convertBatch convert multiple enum values at once. Accepts an array of values and returns an array of co…Schemas
Internal
3
Health
Internal
6
get
/v4/bucket/health/proofsCheck for stale proof ingestion filesget
/v4/bucket/health/diffCheck for stale diff / diff-breakdown ingestion filesget
/v4/bucket/health/transactionsCheck for stale transaction and autoclaim ingestion filesget
/v4/redis/healthCheck monitored Redis caches for stalenessget
/v4/claims/healthCheck claim indexing sync across all chainsget
/v4/dynamic-data/healthCheck the update-dynamic-data job is running across chainsGraphQL
Internal
5
get
/graphql/v1GraphQL endpoint. POST a query to execute it, or open the URL in a browser to load GraphiQL for i…post
/graphql/v1GraphQL endpoint. POST a query to execute it, or open the URL in a browser to load GraphiQL for i…put
/graphql/v1GraphQL endpoint. POST a query to execute it, or open the URL in a browser to load GraphiQL for i…delete
/graphql/v1GraphQL endpoint. POST a query to execute it, or open the URL in a browser to load GraphiQL for i…patch
/graphql/v1GraphQL endpoint. POST a query to execute it, or open the URL in a browser to load GraphiQL for i…Diffs
Internal
8
get
/v4/internal/diffs/Returns paginated parent Diff rows, count, and summary for a given chainget
/v4/internal/diffs/leavesReturns paginated parent Leaf rows, count, and summary for a given chainget
/v4/internal/diffs/breakdownsReturns paginated DiffBreakdown rows, count, and summary for a given chain and rootget
/v4/internal/diffs/breakdowns/countReturns count of DiffBreakdown rows matching filtersget
/v4/internal/diffs/tokensReturns distinct tokens present in DiffBreakdown rows for a given chain and rootget
/v4/internal/diffs/rootsReturns recent MerklRoots for a chain (last 7 days)get
/v4/internal/diffs/leaf-breakdownsReturns paginated LeafBreakdown rows, count, and summary for a given chain and tokenget
/v4/internal/diffs/leaf-tokensReturns distinct tokens present in LeafBreakdown rows for a chainPayload
Internal
3
post
/v4/internal/payload/gnosisAnalyse the campaigns created by a future transaction. For large Safe files (>50 campaigns), cons…post
/v4/internal/payload/gnosis/asyncStart async analysis of campaigns from a Safe file. Returns a job ID immediately. Use GET /payloa…get
/v4/internal/payload/jobs/{jobId}Get the status of an async Safe file analysis job. Poll this endpoint to check progress and retri…Transactions
Internal
1
OffchainBilling
Internal
3
get
/v4/offchain-billing/self/owedYour creator's off-chain owed position (X-API-Key): credit balance, pending accrual, owed, and a …get
/v4/offchain-billing/self/pendingJust your creator's pending off-chain accrual (X-API-Key) — the USD not yet debited.get
/v4/offchain-billing/self/operationsYour creator's off-chain accrual debits (X-API-Key), newest first.Volume
Internal
4
get
/v4/volume/entriesList volume entries, filterable by program, clientId, chainId and a timestamp range (all optional…get
/v4/volume/userAggregated volume for a single user (recipient), filterable by program, clientId, chainId and a t…post
/v4/volume/boostCompute a boost per address: the summed VolumeEntry amount over the config matching clientId and …get
/v4/volume/facetsList the available programs and client ids to filter volume entries by.