Creating the payloads

Once you've assembled a configuration (see Understanding campaign configs), the Merkl API turns it into the two payloads you actually use:

1. A minimal opportunity payload to preview the metadata Merkl will display for the opportunity.
2. A full campaign payload — the encoded createCampaign call you broadcast onchain.

1. Opportunity metadata payload

You don't need a full configuration to preview an opportunity — a minimal subset of fields is enough (the example below is for an ERC20 campaign type; other types expect different fields). The metadata is what Merkl shows for the opportunity (title, target asset, APR, etc.) before the campaign is even live.

{
    "campaignType": 60,
    "targetToken": "0xBdb9300b7CDE636d9cD4AFF00f6F009fFBBc8EE6",
    "computeChainId": 8453,
    "distributionChainId": 8453,
    "distributionMethodParameters": {
        "distributionMethod": "MAX_APR",
        "distributionSettings": {
            "apr": "0.08",
            "rewardTokenPricing": true,
            "targetTokenPricing": true
        }
    }
}

Submit it to:

POST https://api.merkl.xyz/v4/config/opportunity

The response contains the opportunity metadata Merkl will compute for this configuration. Use this endpoint to preview the opportunity, surface its details in your own UI, or validate the inputs before encoding the campaign. Full reference: POST /v4/config/opportunity.

2. Full campaign payload

The body of this endpoint is simply your complete configuration — the one assembled in Understanding campaign configs — wrapped in an array, so you can encode several campaigns in a single batch:

[
    { /* a complete campaign configuration */ },
    { /* …another configuration to batch (optional) */ }
]

Submit it to:

POST https://api.merkl.xyz/v4/config/encode/batch

The response contains the encoded calldata you can hand to a wallet for signing. Full reference: POST /v4/config/encode/batch.

Once you have the encoded payload, head over to Transactions to sign to learn what to broadcast onchain.

Encoding and Decoding Configurations

The Merkl API also provides a variety of endpoints to convert between campaign configurations and the encoded format used onchain.

Encoding configurations for onchain campaign creation:

These endpoints convert campaign configurations into transaction data for calling the Merkl Distribution Creator contract:

• Encode single campaign from config - Generate transaction data for one campaign
• Encode multiple campaigns from their respective configs - Generate transaction data for multiple campaigns

If you're deploying campaigns from a Gnosis Safe, use these endpoints instead to get Safe-compatible transaction payloads:

• Get Safe payload from a single campaign config - Generate Safe transaction payload for one campaign
• Get Safe payload from multiple campaigns config - Generate Safe transaction payload for multiple campaigns

Decoding onchain data into configurations:

These endpoints convert various types of onchain and encoded data back into readable configuration objects:

• Decode from onchain campaign ID - Retrieve configuration for an existing campaign
• Get config from database ID - Retrieve the configuration of an existing campaign from its database ID
• Decode from raw onchain campaign data - Parse encoded campaign data
• Decode from Gnosis Safe payload - Extract configuration from Safe transaction payload
• Decode from transaction data - Parse campaign creation transaction data

Previewing campaigns before deployment:

These endpoints allow you to simulate how your campaign will appear and estimate its metrics before deploying it onchain:

• Preview opportunity details - See how your campaign will be categorized and displayed (opportunity name, grouping, etc.)
• Estimate TVL - Calculate the expected Total Value Locked for your campaign configuration