Merkl Developer Portal logo
get

/v4/users/{address}/protocols/{protocolId}/rewards

Retrieve claimable rewards for a user scoped to a single protocol. Breakdowns and amounts reflect only campaigns attributed to the requested protocol. The returned proofs and root still claim the full per-token leaf on-chain.

Path parameters

addressstring
required

User wallet address

protocolIdstring
required

Main protocol ID to filter rewards by

Query parameters

chainIdstring[]
required

List of chain IDs to query rewards for

reloadChainIdnumber | string

An optional chainId to bypass the cache and check if there was very recently a claim on this chain

testboolean

Include test token rewards

claimableOnlyboolean

Include only claimable rewards (to avoid transferring zero amounts)

breakdownPagenumber | stringdefault: 0

0-indexed pagination for rewards[number].breakdowns. 1000 items per page.

typeenum

Filter rewards by token type

showPrivateboolean

When true, decode private campaign IDs instead of returning the zero hash. Requires the caller's identity (JWT or API key owner) to match the queried address — otherwise returns 403. Also bypasses CDN cache.

Responses

200
Response for status 200
Schema
object[]
chainobjectChain
idinteger
required
Chain Id
namestring
required
Legible name of the chain
iconstring
required
URL to the icon of the chain
liveCampaignsnumber
required
Number of campaigns currently live on this chain
endOfDisputePeriodnumber
required
explorersobject[]
typeenumETHERSCANBLOCKSCOUTSOLSCAN
urlstring
chainIdnumber
lastClaimsOnchainFetchTimestampstring | null
required
Timestamp of the last claims onchain fetch
rewardsobject[]List of rewards for each token
rootstringMerkle tree root hash for the reward claim
recipientstringAddress of the reward recipient
proofsstring[]Merkle proofs for reward verification
tokenobjectToken information
addressstring
required
Token contract address
chainIdnumber
required
Chain ID where the token exists
symbolstring
required
Token symbol
decimalsnumber
required
Token decimals
underlyingTokenIdstringFor a wrapper, the `Token.id` of the token it pays out on claim.
breakdownsobject[]Detailed breakdowns of rewards by reason and campaign
reasonstringReason identifier for the reward
amountstringTotal reward amount for this reason
claimedstringAmount already claimed
pendingstringAmount pending claim
campaignIdstringID of the campaign that generated this reward
opportunityIdstringID of the opportunity this breakdown is attributed to
campaignStatusobject
campaignIdstring
required
computedUntilstring | number | string
required
processingStartedstring | number | string
required
statusstring
required
preComputeProcessingStartedstring | number | string
required
preComputeStatusstring
required
delaynumber | string
errorstring
detailsany
claimedbigint | stringTotal amount claimed by the user
amountbigint | stringTotal reward amount
pendingbigint | stringTotal pending reward amount
Example
[
  {
    "chain": {
      "id": 0,
      "name": "string",
      "icon": "string",
      "liveCampaigns": 0,
      "endOfDisputePeriod": 0,
      "explorers": [
        {
          "type": null,
          "url": "string",
          "chainId": 0
        }
      ],
      "lastClaimsOnchainFetchTimestamp": "string"
    },
    "rewards": [
      {
        "root": "string",
        "recipient": "string",
        "proofs": [
          "string"
        ],
        "token": {
          "address": "string",
          "chainId": 0,
          "symbol": "string",
          "decimals": 0,
          "underlyingTokenId": "string"
        },
        "breakdowns": [
          {
            "reason": null,
            "amount": null,
            "claimed": null,
            "pending": null,
            "campaignId": null,
            "opportunityId": null,
            "campaignStatus": null
          }
        ],
        "claimed": null,
        "amount": null,
        "pending": null
      }
    ]
  }
]