---
title: "GET /v4/users/{address}/rewards/chains/{chainId}/earned"
method: GET
path: "/v4/users/{address}/rewards/chains/{chainId}/earned"
tags: ["Users"]
---

# GET /v4/users/{address}/rewards/chains/{chainId}/earned

`GET /v4/users/{address}/rewards/chains/{chainId}/earned`

## Request

- Base URL: `https://api.merkl.xyz` (the document declares no server; this is the origin it was published from)
- URL: `https://api.merkl.xyz/v4/users/{address}/rewards/chains/{chainId}/earned`
- Auth: `apiKey` (a scheme the document does not define)

Rewards an address earned on one chain since 00:00 UTC 30 days ago, per token and campaign, optionally for one reward `token`. Rows of private or hidden-leaderboard campaigns appear only to a caller allowed to read them. When the route cannot answer for the chain yet, it is listed in `unavailableChainIds`. Requires an API key.

## Path parameters

- `address` string, required: User address
- `chainId` union, required: Chain ID
  - string, integer
  - integer: Chain ID

## Query parameters

- `isTest` boolean: Include test tokens
- `token` string: Reward token address. Omit it to get every token.

## Response `200`

Response for status 200

- object
  - `address` string, required
  - `windowSeconds` number, required: Seconds since 00:00 UTC, 30 days ago: between 30 and 31 days
  - `totalUSD` number, required
  - `chains` object[], required
    - `chainId` number, required
    - `startRoot` string, nullable, required: Always null: the window opens at 00:00 UTC, not at a root
    - `startTimestamp` number, nullable, required
    - `endRoot` string, required: Live root the current amounts belong to
    - `endTimestamp` number, required
    - `tokens` object[], required
      - `address` string, required
      - `symbol` string, required
      - `decimals` number, required
      - `icon` string, required
      - `price` number, nullable, required
      - `amount` string, required: Amount earned in the window, in token base units
      - `amountUSD` number, required
      - `campaigns` object[], required
        - `campaignId` string, required
        - `amount` string, required
  - `unavailableChainIds` number[], required: The chain, when the route cannot answer for it: no live root, not backfilled yet, or no API row

## Changes

- **2026-10-14** `7bcc71910715`: 1 info
  - added the new optional `query` request parameter `token`
- **2026-10-13** `4207c9b739f0`: 1 breaking, 2 warning
  - `path` request parameter `chainId` list-of-types was narrowed by removing types `number`
  - for the `path` request parameter `chainId`, the max was set to `2147483647.00`
  - for the `path` request parameter `chainId`, the min was set to `1.00`
- **2026-10-13** `1f0c51042b36`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/merkl/apis/merkl-api/changes/v4/users/:address/rewards/chains/:chainId/earned/get.md)

---

[API](https://skmtc.dev/merkl/apis/merkl-api.md) - [All operations](https://skmtc.dev/merkl/apis/merkl-api/llms.txt) - [OpenAPI document](https://skmtc.dev/merkl/apis/merkl-api/revisions/60ffe2c7d887?raw)