Merkl Developer Portal logo
get

/v4/users/{address}/rewards/earned/timeline

Rewards an address earned per UTC day over the last 7 or 30 days (today included), in USD at the current price, per token across every chain. Built from merged roots only. Rows of private or hidden-leaderboard campaigns appear only to a caller allowed to read them. Chains the address earned on in the range whose history is not backfilled yet are not charted and are listed in unavailableChainIds.

Path parameters

addressstring
required

User address

Query parameters

rangeenum

Days to chart, today (UTC) included

chainIdsstring (integer) | integer[]

Distribution chain IDs. Omit them to get every chain.

isTestboolean

Include test tokens

Responses

200
Response for status 200
Schema
object
bucket"day"
required
rangeenum
required
Days to chart, today (UTC) included7d30d
tokensobject[]
required
Token series across all buckets (chart legend)
idstringStable chart series id (`chainId:tokenAddress`, or `__other__` for folded tokens)
symbolstringToken symbol displayed in the chart legend
chainIdnumberChain ID of the token; absent for synthetic series like `Other`
addressstringToken address; absent for synthetic series like `Other`
iconstringToken icon URL; absent for synthetic series like `Other`
pricenumberCurrent token price in USD; absent when unpriced or for synthetic series
bucketsobject[]
required
One bucket per UTC day of the range, ascending. A value is signed: a recomputation can make a day negative
startnumberUnix timestamp (seconds) of the bucket start, UTC-aligned
endnumberUnix timestamp (seconds) of the bucket end (exclusive)
breakdownobject[]Per-token USD value, descending
tokenIdstringStable token series id matching an entry in `tokens`
valuenumberUSD value earned in the bucket
unavailableChainIdsnumber[]
required
Chains the address earned on in the range that the route cannot chart yet: history not backfilled
Example
{
  "bucket": "day",
  "range": "7d",
  "tokens": [
    {
      "id": "string",
      "symbol": "string",
      "chainId": 0,
      "address": "string",
      "icon": "string",
      "price": 0
    }
  ],
  "buckets": [
    {
      "start": 0,
      "end": 0,
      "breakdown": [
        {
          "tokenId": "string",
          "value": 0
        }
      ]
    }
  ],
  "unavailableChainIds": [
    0
  ]
}