API Conventions

Identifiers

Chains, protocols, campaigns, opportunities, and tokens each have their own ID format. See ID types. Chain IDs and contract addresses are in Chains & Contracts, protocol IDs in Protocols.

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 full set of types (campaign types, distribution methods, scoring methods, hooks, and more), along with what each value corresponds to, is laid out in the schema explorer.

The Merkl API also provides conversion endpoints to decode these enum values programmatically 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.