Merkl Docs
  • πŸ₯¨Merkl Documentation Portal
  • Merkl mechanisms
    • πŸ”Technical Overview
    • πŸͺ·Incentive Mechanisms
    • πŸ•οΈCampaign Types
      • πŸ¦„Concentrated Liquidity Campaigns
      • 🏹Airdrop Campaigns
      • πŸ§‘β€πŸŒΎERC20 Campaigns and Applications
      • 🏦Custom Lending and Borrowing Campaigns
      • [NEW] 🎣 UniswapV4 Liquidity Campaigns
      • [NEW] 🌐 Encompassing Campaigns
    • πŸ’ΈDistribution Types
    • πŸͺCustomazibility Hooks
    • πŸͺΆAdditional Features
  • Distribute with Merkl
    • 😽Create a Merkl campaign
    • πŸ§‘β€πŸ”¬Deploy a campaign from a multisig or Gnosis Safe
    • πŸ—³οΈDeploy your campaign from a DAO
    • πŸ’³Fee Model
  • Earn with Merkl
    • πŸ’°Earn with Merkl
    • πŸ“Merkl User FAQ
  • Integrate Merkl
    • πŸ‘©β€πŸ’»Integrate Merkl to your App - Merkl API V4 Docs
    • πŸ‘©β€πŸ’»Merkl API V4 NPM Package
    • 3️⃣ Merkl API V3 Docs
    • πŸ§‘β€πŸŽ¨Branding and Integration
Powered by GitBook
On this page
  • Understanding the difference between Opportunities and Campaigns
  • Integrating APRs Data into your frontend
  • Retrieving Campaign data
  • Retrieving Opportunity Data
  • Integrating User Rewards
  • Claiming user rewards
  • Benefit from Typescript typings when using the Merkl API
  1. Integrate Merkl

Integrate Merkl to your App - Merkl API V4 Docs

Integrate Merkl in your app using Merkl API V4

PreviousMerkl User FAQNextMerkl API V4 NPM Package

Last updated 3 months ago

While the offers a comprehensive interface that provides users and Liquidity Providers with everything they need to take advantage of Merkl opportunities, Merkl is also designed so anyone can integrate Merkl data into its own application and use it as a white-label solution.

This guide aims at walking you through the integration of Merkl in your app via the Merkl API.

If you use Merkl as a white-label solution in your frontend, you must integrate with a clickable link that redirects to our app.

Merkl provides an API, available that contains all the information you need to track campaigns and selectively display the ones you want on your frontend. All the data from the Merkl app is served by this API.

The documentation for can be found . We encourage you to use this documentation for reference after having read the paragraphs below.

As you browse through the documentation, you'll notice that some API parameters are optional. Keep in mind though that specifying more parameters can speed up the result of your API queries.

Understanding the difference between Opportunities and Campaigns

To show Merkl data in your front-end, you have 2 types of data you can use:

  • Campaigns: these are programs running on a given pool, ERC20 token, etc, over a period of time

  • Opportunities: these are groups of campaigns targeting the same user base (the same pool, ERC20 token, ...). Typically, multiple campaigns can run in parallel for liquidity providers on a pool, and these all make up an opportunity.

Integrating APRs Data into your frontend

  1. Retrieve the Opportunity ID:

    • If you're a DeFi protocol integrating APRs for your own opportunities, query this API route with your protocol name:

      https://api.merkl.xyz/v4/opportunities?name={protocol_name}

      For example, for Izumi:

      https://api.merkl.xyz/v4/opportunities?name=Izumi

      Just below the tags of an opportunity, you’ll find the opportunity ID. Copy it for later.

    • If your opportunities are across multiple protocols, we recommend using this route:

      https://api.merkl.xyz/v4/opportunities?tags={tag}

      Example: Display all campaigns associated with the Ignite Program on zkSync:

      https://api.merkl.xyz/v4/opportunities?tags=zksync

      If you want a tag added to an opportunity, feel free to reach out, and we will assign the campaign to your protocol’s tag. Similarly, below tags, you’ll find the opportunity ID. Copy it for later.

  2. Retrieve APR Data:

    • Once you have the opportunity ID, call the following route, replacing {id} with your opportunity ID:

      https://api.merkl.xyz/v4/opportunities/{id}

      Example for SyncswapV3 USDC-wUSDM 0.3%:

      https://api.merkl.xyz/v4/opportunities/17697067541467596262

      This route provides details such as APR, TVL, and daily rewards.

Retrieving Campaign data

Here, you will find data related to this campaign start and end date, the amount of PYTH streamed, its ID, etc.

Each campaign on Merkl is identified on the Merkl API by a unique ID.

Retrieving Opportunity Data

Now, you may want to display data about all the campaigns targeting this pool.

This will enable you to display aggregated data about all these campaigns.

The two routes we recommending using are:

  • https://api.merkl.xyz/v4/opportunities?name={protocol_name}

  • https://api.merkl.xyz/v4/opportunities?tags={tag}

This will give you aggregated data related to the opportunity like daily rewards, APRs, TVLs, etc.

Integrating User Rewards

For protocols integrating user rewards, they need to call the following API route to display the rewards earned by users:

https://api.merkl.xyz/v4/users/{address}/rewards?chainId={chain_id}

Example: Checking a user’s rewards on zkSync:

https://api.merkl.xyz/v4/users/0x4F2BF7469Bc38d1aE779b1F4affC588f35E60973/rewards?chainId=324

This route provides:

  • Amount : the total amount of tokens to have been credited to the user onchain.

  • Pending : the pending rewards that will be credited onchain on the next update.

  • Claimed : the number of already claimed tokens.

  • Proofs that will assist in integrating the claiming of rewards (details in the next section).

Claiming user rewards

Rewards on Merkl are claimable per token: meaning that if a user has accumulated rewards of several tokens, they may choose to only claim their rewards of one token type, just like they can choose to claim all their token rewards at once.

There are different options with which you can help your users claim their rewards:

  • Rely on the data provided by the Rewards API route mentioned above (recommended): In this case the Merkl API builds entirely the claim transaction payload and the associated proof. All you need to do is call the Merkl API. This is the example shown below.

  • Build the proof yourself: In this setting, once the proof is built on your end, you may join it to the transaction data from the Merkl API. You can find a Github repository below showing how to do that. If you need further help, please reach out to us on Discord or Telegram.

In any case, if a call is made to the correct Distributor contract and the token or amount do not match the proof, the transaction will revert.

Here is a script you may use to claim all the token rewards for a user on a chain.

import type { JsonRpcSigner } from '@ethersproject/providers'
import { MerklApi } from '@merkl/api'
import { Distributor__factory } from '@sdk' // ABI can be fetched on etherscan

const DISTRIBUTOR_ADDRESS = '0x3Ef3D8bA38EBe18DB133cEc108f4D14CE00Dd9Ae'

export const claim = async (chainId: number, signer: JsonRpcSigner) => {
  const { status, data } = await MerklApi('https://api.merkl.xyz')
    .v4.users({ address: signer._address })
    .rewards.get({ query: { chainId: [chainId] } })
  if (status !== 200) throw 'Failed to fetch rewards'

  const users = []
  const tokens = []
  const amounts = []
  const proofs = []

  for (const rewards of data) {
    if (rewards.chain.id !== chainId) continue
    for (const reward of rewards.rewards) {
      users.push(signer._address)
      tokens.push(reward.token.address)
      amounts.push(reward.amount)
      proofs.push(reward.proofs)
    }
  }

  if (tokens.length === 0) throw 'No tokens to claim'

  const contract = Distributor__factory.connect(DISTRIBUTOR_ADDRESS, signer)
  await (await contract.claim(users, tokens, amounts, proofs)).wait()
}

Benefit from Typescript typings when using the Merkl API

Assuming you've created a campaign using $PYTH as a reward token targeting the Euler Vault 0x82D2CE1f71cbe391c05E21132811e5172d51A6EE, you can find this campaign's data using the following endpoint: .

There are different filters available to find your campaigns. You may browse the available filters .

Taking the example from above, you may get the opportunity corresponding to the Euler vault by using: .

Once again, there are different filters available to find the opportunities of your choice. You may browse the different filters for opportunities .

The contract on which rewards should be claimed is the Distributor contract, which address across different chains can be found on this .

Interacting safely with Merkl API is possible using our NPM package. See our guide .

πŸ‘©β€πŸ’»
Merkl App
our logo
here
here
https://api.merkl.xyz/v4/campaigns?tokenSymbol=PYTH
here
https://api.merkl.xyz/v4/opportunities?name=Euler
here
page
here