API Conventions

Identifiers

When integrating with the Merkl API, you'll need to know how chains, protocols, and contracts are referenced.

• Chains are referenced by their chainId. See the full list on the Chains & Contracts page.
• Protocols are referenced by their protocolId. See the full list on the Protocols page.
• Contract addresses — for distributor and other relevant addresses you'll need when integrating, check the Chains & Contracts page.

Understanding enums in the API responses

The API sometimes returns enum values as integers in its responses. For example, a campaign might show campaignType: 18. The Merkl API provides conversion endpoints to decode these enum values and retrieve all possible values for each enum type.

Available endpoints:

• List all enums: https://api.merkl.xyz/v4/enums - Returns all enum types used in the Merkl API
• Get enum values: https://api.merkl.xyz/v4/enums/HookType - Returns all possible values for a specific enum (e.g., HookType)
• Convert enum value: https://api.merkl.xyz/v4/enums/HookType/convert/0 - Converts a numeric enum value to its human-readable label

Additional tips

Pagination - All Merkl API endpoints are paginated. Iterate through pages or increase the page size parameter to retrieve more results (using &page=<NUMBER>)

Query optimization - While many API parameters are optional, specifying additional filters can significantly improve query performance.