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
  • Installation 🚀
  • Usage Example 🛠ïļ
  • Import the Merkl API Package ðŸ“Ķ
  • Instantiate the Merkl API Object 🌐
  • Making API Calls ðŸ“Ą
  • Notes 📝
  1. Integrate Merkl

Merkl API V4 NPM Package

Easily interact with the Merkl API using the dedicated NPM package

PreviousIntegrate Merkl to your App - Merkl API V4 DocsNext3ïļâƒĢ Merkl API V3 Docs

Last updated 2 months ago

Merkl API V4 comes with a dedicated NPM package to help you interact with it.

This quickstart guide will help you get started with interacting with the Eden Treaty app object using the Merkl API package.

Installation 🚀

To begin, install the @merkl/api package into your project:

npm install @merkl/api

Usage Example 🛠ïļ

Here's a step-by-step guide to instantiating the Merkl API object and making API calls.

Import the Merkl API Package ðŸ“Ķ

import { MerklApi } from '@merkl/api'

Instantiate the Merkl API Object 🌐

Initialize the Merkl API object by providing the base URL. Developers can leverage autocomplete features in their IDEs since all methods are strongly typed, ensuring a seamless development experience:

const merkl = MerklApi('https://api.merkl.xyz').v4

Making API Calls ðŸ“Ą

Below are examples of common API calls you can make. When making API calls, you can pass query parameters as an object under the query property and path parameters directly in the method arguments, as shown in the examples below:

Get Opportunities 💞

Retrieve a list of opportunities filtered by a specific chainId:

const opportunities = await merkl.opportunities.index.get({
  query: { chainId: '1' },
})

console.log(opportunities.data)

Get Rewards for a Specific Address 🏆

Retrieve rewards for a specific user address. Note that all methods are strongly typed for better developer experience: this ensures reduced debugging time, as incorrect parameter usage is flagged early, and improved code completion in supported IDEs for faster development.

const rewards = await merkl
  .users({
    address: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045',
  })
  .rewards.get({ query: { chainId: 1 } })

console.log(rewards.data)

For perfomance issue, most responses are cached in our API. To bypass the cache, and get the latest value that the user would be able to claim (for instance directly after a claim transaction), you can ask for a reload. If the reload is done before the transaction can be indexed, the reload will not properly update the expected balance.

This will increase latency on the response.

const rewards = await merkl
  .users({
    address: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045',
  })
  .rewards.get({ query: { chainId: 1 ,reloadChainId : 1} })

console.log(rewards.data)

Get Campaigns Rewarding USDC

Retrieve campaigns filtered by token symbol, such as USDC:

const campaignsUSDC = await merkl.campaigns.index.get({
  query: { tokenSymbol: 'USDC' },
})

console.log(campaignsUSDC.data)

Notes 📝

  • All API responses are wrapped within a data attribute. This consistency across all API calls ensures that developers can reliably access the actual response payload. Access this attribute to get the actual response payload.

  • The Merkl API object methods are strongly typed, making it easier to catch errors during development.


You're now ready to interact with the Merkl API! 🎉

For additional documentation and advanced usage, refer to the .

ðŸ‘Đ‍ðŸ’ŧ
Merkl API swagger