Display Your Native APR

Display your protocol's native APR on the Merkl frontend

Merkl enables protocols to display their native APR directly on the Merkl frontend alongside Merkl incentive APRs. This integration provides users with a comprehensive view of total returns available on your protocol.

Overview

By integrating your native APR data, you can:

  • Display protocol-specific APRs (e.g., lending yields, staking rewards, pool fees) on Merkl's frontend
  • Help users understand the full return potential when combining native yields with Merkl incentives
  • Increase visibility and transparency for your protocol's offerings

Implementation

Endpoint Requirements

To integrate your native APR data, you must create and host a public API endpoint that returns APR data in the following JSON format:

[
  {
    "title": "Protocol Name APR",       // Required: String - Display name for the APR (e.g., "Aave Supply APR", "Uniswap Fee APR")
    "opportunityId": "12345678901234567",  // Required: String - The Merkl Opportunity ID (numeric string)
    "timestamp": 1716900000,            // Required: Number - Unix timestamp in seconds when the APR was calculated
    "value": 5.5,                       // Required: Number - The APR as a percentage (e.g., 5.5 for 5.5%)
    "description": "Optional details"   // Optional: String - Additional context about the APR calculation
  },
  {
    "title": "Protocol Name APR",
    "opportunityId": "98765432109876543",
    "timestamp": 1716900000,
    "value": 12.4
  }
]

Field Descriptions

  • title: A clear, descriptive name for the APR type (e.g., "Aave Supply APR", "Compound Borrow APR", "Uniswap V3 Fee APR")
  • opportunityId: The unique numeric identifier for the Merkl opportunity. See Finding Relevant Opportunities to learn how to retrieve it via the API.
  • timestamp: When the APR value was last calculated or updated, in Unix timestamp format (seconds)
  • value: The APR value as a percentage. For example, use 5.5 to represent 5.5% APR
  • description (optional): Additional information about how the APR is calculated or what it represents

The opportunityId is the top-level id field of each opportunity object returned by the API. Do not confuse it with other id fields nested inside the response (e.g., inside the tokens array).

Next Steps

Once you have prepared your endpoint:

  1. Test your endpoint to ensure it returns data in the correct format
  2. Verify that all opportunity IDs are accurate
  3. Contact the Merkl team to register your endpoint and complete the integration

Important: All APR data must be accurate and verifiable. Providing misleading, incorrect, or manipulated data will result in immediate removal of your integration from the Merkl frontend.

Ensure that:

  • APR calculations are accurate and reflect actual protocol performance
  • Timestamps are current and updated regularly
  • Values are consistently formatted as percentages

If you have questions or need assistance, please reach out to the Merkl team.