API Reference

Merkl API

214 endpoints · v1.0.1

https://api.merkl.xyz/View as Markdown

The 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

/v4/opportunities/{id}Get a unique opportunity by ID (hash) or composite identifier (chainId-type-identifier). Use quer…

/v4/opportunities/{id}/storing-idsGet the storingId(s) backing an opportunity, grouped by root campaign. Returns one tree per root …

/v4/opportunities/{id}/campaignsGet a unique opportunity by ID (hash) or composite identifier (chainId-type-identifier), includin…

/v4/opportunities/{id}/apr-recordsGet historical APR records for an opportunity.

/v4/opportunities/{id}/tvl-recordsGet historical TVL records for an opportunity.

/v4/opportunities/{id}/native-apr-recordsGet historical native APR records for an opportunity.

/v4/opportunities/Retrieve Multiple Opportunities

/v4/opportunities/countGet the count of opportunities corresponding to the query.

/v4/opportunities/bins/aprGet the APR distribution of opportunities matching the query, grouped into bins.

/v4/opportunities/bins/tvlGet the TVL distribution of opportunities matching the query, grouped into bins.

/v4/opportunities/bins/daily-rewardsGet the daily rewards distribution of opportunities matching the query, grouped into bins.

/v4/opportunities/aggregate/{field}Aggregate opportunities by a specific field (chainId, protocolId, tags, etc.).

/v4/opportunities/aggregate/max/{field}Get the maximum value for a specific field across filtered opportunities.

/v4/opportunities/aggregate/min/{field}Get the minimum value for a specific field across filtered opportunities.

Campaigns

Core

9

/v4/campaigns/{id}Retrieve a campaign by its unique identifier (hash or distributionChain-campaignId format) in the…

/v4/campaigns/generate-payloadGenerate an on-chain transaction payload for creating one or more campaigns from the provided data.

/v4/campaigns/{id}/metricsGet historical metrics (TVL, APR, daily rewards) for a campaign, with pagination options.

/v4/campaigns/{id}/storing-idsGet the storingId(s) backing a campaign as a tree. The root node's storingIds belong to the campa…

/v4/campaigns/{id}/linkedGet every opportunity linked to a campaign — its full chain of parent campaigns up to the root, p…

/v4/campaigns/txGet campaign IDs from a creation transaction hash

/v4/campaigns/Search for campaigns matching the criteria provided through query parameters.

/v4/campaigns/countCount the campaigns matching the filters provided through query parameters.

/v4/campaigns/aggregateAggregate all campaigns matching the provided filters and return a per-token breakdown of total a…

Users

Core

11

/v4/users/{address}/rewardsGet the rewards associated to a user on a given chain.

/v4/users/{address}/protocols/{protocolId}/rewardsRetrieve claimable rewards for a user scoped to a single protocol. Breakdowns and amounts reflect…

/v4/users/{address}/termsCheck if a user address has signed Merkl's terms for a specific chain. Provide the user's wallet …

/v4/users/{address}/recipient/{token}Get the recipient address for a given user address and specific token.

/v4/users/{address}/operator/{operatorAddress}Check if an address is an operator for a given user address.

/v4/users/{address}/wrappedGet a summary of a user's claimed rewards, including their most-used protocol and most-claimed to…

/v4/users/{address}/rewards/statsLightweight USD totals for a user — total earned, currently claimable, and pending. Supports opti…

/v4/users/{address}/rewards/summaryPer-chain rewards rollup with USD totals and per-token raw amounts. A lightweight alternative to …

/v4/users/{address}/rewards/active-opportunitiesActive opportunities for a user — LIVE status with rewards still claimable or pending. Aggregated…

/v4/users/{address}/rewards/chains/{chainId}/breakdownsPer-chain opportunity breakdown for a user. Aggregated by opportunity with one row per token carr…

/v4/users/{address}/rewards/breakdownsPer-chain rewards with full opportunity breakdowns and proofs. Returns the same shape as /v4/user…

Chains

Core

2

/v4/chains/List chains supported and integrated by Merkl. Use query parameters to filter by test chains or o…

/v4/chains/{chainId}Get a specific chain by its chainId path parameter

Protocols

Core

3

/v4/protocols/List protocols supported and integrated by Merkl. Use query parameters to filter by chain ID, tag…

/v4/protocols/countGet the number of protocols corresponding to the query. Use query parameters to filter the count.

/v4/protocols/{id}Get a protocol by its ID or name using id path parameter. This endpoint searches by protocol ID f…

Tokens

Core

7

/v4/tokens/prices/historyGet historical price snapshots for a token, newest first. Resolve by symbol (optionally scoped to…

/v4/tokens/wrappersList every Merkl token wrapper a creator distributes, one entry per wrapper and distribution chai…

/v4/tokens/{id}Get a token by its canonical id, or by the {chainId}-{address} shorthand. The shorthand reads an …

/v4/tokens/rewardGet all tokens that are accepted as reward tokens across all chains.

/v4/tokens/reward/{chainId}Get the list of tokens that are accepted as reward tokens on a given chain.

/v4/tokens/Search tokens, or resolve several ids at once with ?id= (canonical numeric ids only). An address …

/v4/tokens/whitelistSubmit a token whitelist request for review.

Rewards

Rewards

13

/v4/rewards/Returns all the addresses that received rewards for a given campaign, sorted by descending amount…

/v4/rewards/totalReturns the total amount distributed for a given campaign. Use query parameters to specify campai…

/v4/rewards/countReturns the number of recipients that earned rewards in a given campaign. Use query parameters to…

/v4/rewards/rankReturns the rank of a user in a campaign leaderboard, based on reward amount. Returns an empty ar…

/v4/rewards/campaign/{campaignId}/listGet rewards for a specific campaign by campaignId path parameter and list of addresses

/v4/rewards/campaign/{campaignId}/mineReturns your own rewards for one campaign — settled, claimed, still-claimable and pending —

/v4/rewards/token/Returns all the addresses that received rewards of a given token, sorted by descending amounts. U…

/v4/rewards/token/totalReturns the total amount distributed for a given token. Use query parameters to specify token add…

/v4/rewards/token/countReturns the number of recipients that earned rewards in a given token. Use query parameters to sp…

/v4/rewards/token/unclaimedReturns the total unclaimed amount (distributed minus claimed) for a given token. Use query param…

/v4/rewards/unclaim/Returns the total of unclaimed rewards for given campaigns. Use query parameters to specify chain…

/v4/rewards/unclaim/batchReturns unclaimed rewards for campaigns across multiple chains in a single call. Pass an array of…

/v4/confidential-rewards/zamaReturns a campaign's leaderboard with every reward amount FHE-encrypted for Zama's confidential

Claims

Rewards

5

/v4/claims/Fetch claims filtered by chainId(s), recipient, campaignId, token, root, exact reason, and an inc…

/v4/claims/history/{address}Fetch a recipient's historical claims, grouped per claim transaction with amounts aggregated by t…

/v4/claims/earnings/{address}Aggregate a recipient's claimed rewards into time buckets broken down by token, in USD. Supports …

/v4/claims/countReturns the total number of unique claimers on a specific chain.

/v4/claims/count/totalReturns the total number of unique claimers across all chains.

Credits

Rewards

9

/v4/credits/pricingGet points-campaign billing pricing constants (USD)

/v4/credits/estimateEstimate the credit cost of a points campaign's next run, mirroring the engine pre-check. Returns…

/v4/credits/estimate/totalEstimate the total credit cost of a points campaign over its full duration (endTimestamp − startT…

/v4/credits/{creatorId}Get credit balance for a creator

/v4/credits/{creatorId}/operationsList credit operations for a creator

/v4/credits/{creatorId}/operations/countGet the number of credit operations for a creator, optionally filtered by type

/v4/credits/{creatorId}/operations/aggregateGet the signed sum of credit operations for a creator. SUBTRACT amounts count as negative, ADD as…

/v4/credits/{creatorId}/operations/breakdownsGet credit operations grouped by category with signed totals. All Auto-claim labels are bucketed …

/v4/credits/{creatorId}/paused-campaignsCount campaigns paused due to insufficient credits for a creator

Creator

Rewards

9

/v4/creators/Retrieves all creators matching the provided query filters

/v4/creators/{creator}Retrieves a specific creator by their ID or slug

/v4/creators/{creator}/dashboardReturns dashboard metrics and overview for a specific creator

/v4/creators/{creator}/opportunities/countReturns the total count of opportunities for a specific creator

/v4/creators/{creator}/opportunitiesReturns paginated opportunities for a specific creator. Use page, items, and other query paramete…

/v4/creators/{creator}/campaignsReturns all campaigns for a specific creator. Filter by status query parameter.

/v4/creators/campaigns/{campaignId}Returns campaign metrics for a specific campaign. Use campaignId path parameter and pagination qu…

/v4/creators/{creator}/opportunity/{opportunityId}/metricsReturns opportunity metrics for a specific creator and opportunity combination

/v4/creators/{creator}/distributed/over-timeToken distribution over time for a creator, bucketed and broken down per reward token (token amou…

Programs

Rewards

3

/v4/programs/Retrieve Multiple Programs

/v4/programs/{idOrSlug}Retrieve a Program by id or slug

/v4/programs/countGet the total count of all programs.

Campaign Lists

Rewards

6

/v4/campaign-lists/{owner}List every named campaign list owned by an address, with its size and last-updated timestamp.

/v4/campaign-lists/{owner}/{name}Get the campaign IDs in a single named list. Returns 404 if the list does not exist.

/v4/campaign-lists/{owner}/{name}Replace the campaign IDs in a named list (an empty array deletes the list). Requires the owner's …

/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.

/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 …

/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

/v4/campaigns/{id}/access/grantGrant access to a private campaign for a specific address.

/v4/campaigns/{id}/access/revokeRevoke access to a private campaign for a specific address.

/v4/campaigns/{id}/access/listList all addresses currently granted access to a private campaign.

Referral

Rewards

2

/v4/referral/codeReturns the transaction to register user as a referrer on-chain and some additional state using c…

/v4/referral/redeemReturns the transaction to redeem a referral code on-chain and some additional state using chainI…

Reallocations

Rewards

4

/v4/reallocations/breakdownRetrieve Reallocation Breakdown

/v4/reallocations/report/{campaignId}Retrace a campaign's reallocations (BETA)

/v4/reallocations/report/{campaignId}/walkStart a reallocation walk job (BETA)

/v4/reallocations/jobs/{jobId}Poll a reallocation walk job (BETA)

Templates

Rewards

3

/v4/templates/Get all templates filtered by query parameters

/v4/templates/countCount templates matching the query filters

/v4/templates/{id}Find one template by ID (UUID), slug or name

Overrides

Rewards

2

/v4/overrides/checkValidate if an override is allowed. Checks: (1) rewardToken cannot change, (2) amount cannot chan…

/v4/overrides/{id}/previous-configsGet previous campaign configs

Historical

Rewards

3

/v4/historical/campaign/{campaignId}Campaign reward diff between two trees (BETA)

/v4/historical/recipient/{recipient}Recipient reward diff between two trees (BETA)

/v4/historical/treeReward breakdowns of a single tree (BETA)

SOFR Spread Ratchet

Rewards

2

/v4/sofr-ratchet/campaign/{campaignId}Current SOFR-spread-ratchet rate for a campaign, resolved from its own stored distribution settin…

/v4/sofr-ratchet/opportunity/{id}Current SOFR-spread-ratchet rate for an opportunity at an explicit anchor: frozen 14-day-mean TVL…

Block Timestamp

Rewards

3

/v4/block-timestamp/blockGet the closest block number to a given timestamp on a specific chain

/v4/block-timestamp/timestampGet the closest timestamp to a given block number on a specific chain

/v4/block-timestamp/boundsGet the closest lower and upper bound blocks for a given timestamp from BlockTimestampMapping

Developer API Keys

Developer

7

/v4/developer/keys/Create a new API key. The raw key is returned only once.

/v4/developer/keys/List all API keys for the authenticated user.

/v4/developer/keys/usageGet usage summary across all API keys for the authenticated user.

/v4/developer/keys/{id}/usageGet detailed daily usage for a specific API key.

/v4/developer/keys/{id}Update description for an API key.

/v4/developer/keys/{id}Revoke an API key.

/v4/api-keys/validateValidate a developer API key. Returns { ok: true } on success, 401 otherwise.

Authentication

Developer

7

/v4/auth/nonce/{address}Generate a unique nonce and message for wallet authentication.

/v4/auth/loginAuthenticate a user and set a JWT cookie for session management.

/v4/auth/google/startStart the Google OAuth flow for signing in with a Google account.

/v4/auth/google/callbackComplete the Google OAuth flow and create or refresh the user session.

/v4/auth/link/walletLink a wallet to the current (Google) session — collapses both into one wallet identity.

/v4/auth/meGet authenticated user information including address, profile, and authentication status.

/v4/auth/revokeRevoke the current user's JWT token and clear the session cookie.

Config

Developer

19

/v4/config/{id}Beta feature (not production ready yet) - Fetch the configuration for a specific campaign by its …

/v4/config/diffCompute the diff between two config schemas. Returns an array of edit operations (insert/update/d…

/v4/config/diff/{id}Compute the diff between the current config of a campaign and a new one. Returns an array of edit…

/v4/config/extendBeta feature (not production ready yet) - Extends a campaign configuration with the values resolv…

/v4/config/opportunityBeta feature (not production ready yet) - Computes an opportunity from a campaign configuration

/v4/config/tvlBeta feature (not production ready yet) - Computes a TVL from a campaign configuration. Requires …

/v4/config/encodeBeta feature (not production ready yet) - Encodes campaign parameters into the transaction payloa…

/v4/config/encode/overrideBeta feature (not production ready yet) - Builds the transaction payload used to override (or can…

/v4/config/encode/reallocateBeta feature (not production ready yet) - Builds the transaction payload used to reallocate an ex…

/v4/config/encode/safeBeta feature (not production ready yet) - Encodes campaign config to Safe transaction payload. Us…

/v4/config/encode/batchBeta feature (not production ready yet) - Encodes a batch of campaign parameters into transaction…

/v4/config/encode/batch/safeBeta feature (not production ready yet) - Encodes batch campaign configs to Safe transaction payl…

/v4/config/decode/onchain/{distributionChainId}/{campaignId}Decodes an on-chain campaign configuration. Use distributionChainId and campaignId path parameters.

/v4/config/decode/{distributionChainId}Decodes campaign data from the Distribution contract. Use distributionChainId path parameter and …

/v4/config/decode/{distributionChainId}/{payload}Decodes campaign from a raw payload. Use distributionChainId and payload (hex string) path parame…

/v4/config/decode/safeDecodes a Safe transaction payload back to the original campaign configurations. Returns an array…

/v4/config/decode/args/createCampaignDecodes arguments of the create campaign function back to the original campaign configuration.

/v4/config/storeStores campaign configurations keyed by their hash. Provide the campaign configuration payload in…

/v4/config/hash/{hash}Gets a campaign configuration by its hash. If campaignId and distributionChainId are provided, as…

Key Value Store

Developer

9

/v4/key-value-stores/{key}/entriesUpsert a single entry. Authenticate with a JWT for user access, or an X-API-Key header for servic…

/v4/key-value-stores/{key}/entriesList entries. Public for stores configured as publicly readable; otherwise requires authentication.

/v4/key-value-stores/{key}/entries/batchBatch upsert entries. Requires X-API-Key authentication.

/v4/key-value-stores/{key}/entries/{address}Get a single entry by address

/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…

/v4/key-value-stores/selfCreate a key-value store you own (allowlisted users, X-API-Key). key is a suffix; the response re…

/v4/key-value-stores/selfList the key-value stores your creator owns (X-API-Key)

/v4/key-value-stores/self/{key}Update a key-value store your creator owns, by its canonical key (X-API-Key)

/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

/v4/nodeCheck if an address was already labelled as specific by the Merkl Engine.

/v4/node/protocolsGet the list of protocols that have indexed node sources available.

/v4/node/protocol/{protocol}/chainsGet the chains configured for a specific protocol.

/v4/node/last-blockGet the most recent indexed block. If a protocol is provided, returns it for that protocol on the…

/v4/node/oldest-blockGet the oldest indexed block. If a protocol is provided, returns it for that protocol on the give…

/v4/node/block-differenceGet the block difference (oldest to current). If a protocol is provided, returns it for that prot…

Leaves

Developer

2

/v4/leaves/{recipient}/breakdownsReturns paginated leaf breakdowns for a recipient, token, and chain, including both distributed a…

/v4/leaves/{recipient}/debtReturns the outstanding overdistribution clawback debt for an address, per (chain, token): owed, …

Roots

Developer

2

/v4/roots/Returns the last merkl roots recorded before the provided timestamps. Use chainId and timestamps …

/v4/roots/liveReturns all current live Merkl root hashes across all chains.

Enums

Developer

4

/v4/enums/List all available enums in the system. Returns enum names, types (string/number), and metadata a…

/v4/enums/{enumName}Get detailed information about a specific enum including all entries with their values, names, an…

/v4/enums/{enumName}/convert/{value}Convert an enum value bidirectionally. For number enums: provide a number to get its string name.…

/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

/v4/schemas/List schema groups (BETA)

/v4/schemas/{groupName}List schemas in a group (BETA)

/v4/schemas/{groupName}/{typeId}Get raw JSON Schema for a typed input (BETA)

Health

Developer

8

/v4/bucket/health/proofsCheck for stale proof ingestion files

/v4/bucket/health/diffCheck for stale diff / diff-breakdown ingestion files

/v4/bucket/health/transactionsCheck for stale transaction and autoclaim ingestion files

/v4/redis/healthCheck monitored Redis caches for staleness

/v4/claims/healthCheck claim indexing sync across all chains

/v4/dynamic-data/healthCheck the update-dynamic-data job is running across chains

/v4/health/liveLiveness probe — pod runtime snapshot

/v4/health/readyReadiness probe — pod runtime snapshot

GraphQL

Developer

5

/graphql/v1GraphQL endpoint. POST a query to execute it, or open the URL in a browser to load GraphiQL for i…

/graphql/v1GraphQL endpoint. POST a query to execute it, or open the URL in a browser to load GraphiQL for i…

/graphql/v1GraphQL endpoint. POST a query to execute it, or open the URL in a browser to load GraphiQL for i…

/graphql/v1GraphQL endpoint. POST a query to execute it, or open the URL in a browser to load GraphiQL for i…

/graphql/v1GraphQL endpoint. POST a query to execute it, or open the URL in a browser to load GraphiQL for i…

OffchainBilling

Developer

3

/v4/offchain-billing/self/owedYour creator's off-chain owed position (X-API-Key): credit balance, pending accrual, owed, and a …

/v4/offchain-billing/self/pendingJust your creator's pending offchain accrual (X-API-Key) — the USD not yet debited.

/v4/offchain-billing/self/operationsYour creator's offchain accrual debits (X-API-Key), newest first.

Organizations

Developer

22

/v4/organizations

/v4/organizations

/v4/organizations/bootstrap

/v4/organizations/permissions

/v4/organizations/invitations/pending

/v4/organizations/invitations/{invitationId}/accept

/v4/organizations/{organizationId}

/v4/organizations/{organizationId}

/v4/organizations/{organizationId}/dissolve

/v4/organizations/{organizationId}/members

/v4/organizations/{organizationId}/members/{userId}

/v4/organizations/{organizationId}/members/{userId}

/v4/organizations/{organizationId}/leave

/v4/organizations/{organizationId}/invitations

/v4/organizations/{organizationId}/invitations

/v4/organizations/{organizationId}/invitations/{invitationId}

/v4/organizations/{organizationId}/user-groups

/v4/organizations/{organizationId}/user-groups

/v4/organizations/{organizationId}/user-groups/{userGroupId}/permissions

/v4/organizations/{organizationId}/user-groups/{userGroupId}

/v4/organizations/{organizationId}/user-groups/{userGroupId}/members

/v4/organizations/{organizationId}/user-groups/{userGroupId}/members/{userId}

Volume

Developer

4

/v4/volume/entriesList volume entries, filterable by program, clientId, chainId and a timestamp range (all optional…

/v4/volume/userAggregated volume for a single user (recipient), filterable by program, clientId, chainId and a t…

/v4/volume/boostCompute a boost per address: an address with at least one VolumeEntry in a config matching the op…

/v4/volume/facetsList the available programs and client ids to filter volume entries by.