Merkl API
245 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
15
get
/v4/opportunities/tvl-recordsGet compact historical TVL series for several opportunities at once. Repeat ids once per opportun…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/chains/{chainId}/earnedRewards an address earned on one chain since 00:00 UTC 30 days ago, per token and campaign, optio…get
/v4/users/{address}/rewards/earned/timelineRewards an address earned per UTC day over the last 7 or 30 days (today included), in USD at the …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/campaign/{campaignId}One address's rewards for one campaign: amount, claimed, claimable, pending and per-reason breakd…get
/v4/users/{address}/rewards/breakdownsPer-chain rewards with full opportunity breakdowns and proofs. Returns the same shape as /v4/user…Chains
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
6
get
/v4/tokens/prices/historyGet historical price snapshots for a token, newest first. Resolve by symbol (optionally scoped to…get
/v4/tokens/wrappersList every Merkl token wrapper a creator distributes, one entry per wrapper and distribution chai…get
/v4/tokens/{id}Get a token by its canonical id, or by the {chainId}-{address} shorthand. The shorthand reads an …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.get
/v4/tokens/Search tokens, or resolve several ids at once with ?id= (canonical numeric ids only). An address …Rewards
Rewards
15
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 leaderboard rows (one per recipient and reason) in a given campaign. Use it…get
/v4/rewards/recipients/countReturns the number of distinct recipients that earned rewards in a given campaign. A recipient ea…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 addresses. campaignI…get
/v4/rewards/campaign/{campaignId}/mineReturns your own rewards for one campaign — settled, claimed, still-claimable and pending —get
/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…post
/v4/confidential-rewards/zamaStart a Zama encryption jobget
/v4/confidential-rewards/zama/jobs/{jobId}Poll a Zama encryption jobClaims
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
4
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
Developer
7
post
/v4/developer/keys/Create a new API key. The raw key is returned only once. The first call of a new wallet creates i…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
Developer
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
Developer
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 configuration. Requires …post
/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 and…Key Value Store
Developer
9
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 your creator owns (X-API-Key)patch
/v4/key-value-stores/self/{key}Update a key-value store your creator owns, by its canonical key (X-API-Key)delete
/v4/key-value-stores/self/{key}Delete a key-value store your creator owns (by canonical key) and all its entries (X-API-Key)Node
Developer
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
Developer
2
Roots
Developer
2
Enums
Developer
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
Developer
3
Health
Developer
9
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 chainsget
/v4/materialized-views/healthCheck every materialized view was refreshed recentlyget
/v4/health/liveLiveness probe — pod runtime snapshotget
/v4/health/readyReadiness probe — pod runtime snapshotGraphQL
Developer
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…OffchainBilling
Developer
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 offchain accrual (X-API-Key) — the USD not yet debited.get
/v4/offchain-billing/self/operationsYour creator's offchain accrual debits (X-API-Key), newest first.Merkl Encompassing
Developer
1
Workspaces
Developer
29
get
/v4/workspacespost
/v4/workspacespost
/v4/workspaces/bootstrapget
/v4/workspaces/permissionsget
/v4/workspaces/{workspaceId}/roles/grantableget
/v4/workspaces/invitations/pendingpost
/v4/workspaces/invitations/{invitationId}/acceptget
/v4/workspaces/{workspaceId}patch
/v4/workspaces/{workspaceId}post
/v4/workspaces/{workspaceId}/dissolveget
/v4/workspaces/{workspaceId}/memberspatch
/v4/workspaces/{workspaceId}/members/{userId}delete
/v4/workspaces/{workspaceId}/members/{userId}post
/v4/workspaces/{workspaceId}/leaveget
/v4/workspaces/{workspaceId}/invitationspost
/v4/workspaces/{workspaceId}/invitationsdelete
/v4/workspaces/{workspaceId}/invitations/{invitationId}get
/v4/workspaces/{workspaceId}/user-groupspost
/v4/workspaces/{workspaceId}/user-groupsput
/v4/workspaces/{workspaceId}/user-groups/{userGroupId}/rolesdelete
/v4/workspaces/{workspaceId}/user-groups/{userGroupId}post
/v4/workspaces/{workspaceId}/user-groups/{userGroupId}/membersdelete
/v4/workspaces/{workspaceId}/user-groups/{userGroupId}/members/{userId}get
/v4/workspaces/{workspaceId}/campaign-groupspost
/v4/workspaces/{workspaceId}/campaign-groupsdelete
/v4/workspaces/{workspaceId}/campaign-groups/{campaignGroupId}put
/v4/workspaces/{workspaceId}/campaign-groups/{campaignGroupId}/campaigns/{campaignId}delete
/v4/workspaces/{workspaceId}/campaign-groups/{campaignGroupId}/campaigns/{campaignId}post
/v4/workspaces/{workspaceId}/campaigns/{campaignId}/shareWorkspace API Keys
Developer
7
get
/v4/workspaces/{workspaceId}/api-keysList the caller's own keys and those of identities the caller manages. Workspace-wide api_key.man…post
/v4/workspaces/{workspaceId}/api-keysCreate a key for the caller, or for a service account with serviceAccountId. Needs api_key.create…get
/v4/workspaces/{workspaceId}/api-keys/usageUsage totals across the keys the caller may see.get
/v4/workspaces/{workspaceId}/api-keys/{id}Describe one key the caller owns or manages.patch
/v4/workspaces/{workspaceId}/api-keys/{id}Change the description of a key the caller owns or manages.delete
/v4/workspaces/{workspaceId}/api-keys/{id}Revoke a key the caller owns or manages. Takes effect within seconds.get
/v4/workspaces/{workspaceId}/api-keys/{id}/usageDaily usage of one key the caller owns or manages.Workspace Identities
Developer
3
get
/v4/workspaces/{workspaceId}/service-accountsList the service accounts the caller may see. Managing the credentials of a service account lets …post
/v4/workspaces/{workspaceId}/service-accountsCreate a service account without any operational right. Needs service_account.create. Grant it ri…patch
/v4/workspaces/{workspaceId}/service-accounts/{id}Rename, disable or re-enable a service account. Needs service_account.manage on it. Managing the …Ledger
Developer
6
get
/v4/ledger/balances/{address}Real-time offchain (ledger) reward balances for a recipientget
/v4/ledger/nonce/{address}The nonce a recipient's next claim on a chain must signget
/v4/ledger/campaignsPaginated per-campaign ledger accounting with leaf counts (Studio monitoring)get
/v4/ledger/campaigns/{campaignId}Per-campaign ledger accounting (deposited / transferred / claimed / outstanding) with a page of reward entriespost
/v4/ledger/claimsSubmit a recipient-signed claim intent to the coordinatorget
/v4/ledger/claims/{id}Poll a claim intent's FSM stateProofs
Developer
1
Volume
Developer
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: an address with at least one VolumeEntry in a config matching the op…get
/v4/volume/facetsList the available programs and client ids to filter volume entries by.