# Get Claimed Fees \[beta]

### Endpoint

```
GET /api/get-claimed-fees/{tokenAddress}/{feeRecipient}
```

### Authentication

Requires a valid partner API key passed via the `x-api-key` header.

| Header      | Required | Description     |
| ----------- | -------- | --------------- |
| `x-api-key` | Yes      | Partner API key |

### Path Parameters

| Parameter      | Type     | Required | Description                           |
| -------------- | -------- | -------- | ------------------------------------- |
| `tokenAddress` | `string` | Yes      | The Clanker token contract address    |
| `feeRecipient` | `string` | Yes      | The fee recipient (fee owner) address |

Both addresses must be valid Ethereum addresses (checksummed or lowercase).

### Query Parameters

| Parameter | Type     | Required | Default | Description                              |
| --------- | -------- | -------- | ------- | ---------------------------------------- |
| `chainId` | `number` | No       | `8453`  | Chain ID (defaults to Base mainnet)      |
| `limit`   | `number` | No       | `50`    | Number of tx hashes to return (max 100)  |
| `offset`  | `number` | No       | `0`     | Number of records to skip for pagination |

#### Supported Chains

| Chain         | Chain ID |
| ------------- | -------- |
| Base          | `8453`   |
| Base Sepolia  | `84532`  |
| Arbitrum      | `42161`  |
| Monad Testnet | `10143`  |

### Response

#### 200 OK

```json
{
  "tokenAddress": "0x9f86dB9fc6f7c9408e8Fda3Ff8ce4e78ac7a6b07",
  "feeRecipient": "0xF60633D02690e2A15A54AB919925F3d038Df163e",
  "chainId": 8453,
  "totalClaimed": "1789486765760743877",
  "claimCount": 15274,
  "txHashes": [
    "0x43a117b1a5345d6ac56a4b7fb2a6d11654ce1835ba12b78acefb9d5cf38799c7",
    "0x1de665b41ef55e3cd966163e40c55a6a0bc0be33a17d07eb69cc978b240f611d",
    "0xf18645b103e71a952c38888e8af7bd9a7c295b63c35f75b3c1a3f3cfc4ca05c9"
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "hasMore": true
  }
}
```

| Field          | Type       | Description                                                |
| -------------- | ---------- | ---------------------------------------------------------- |
| `tokenAddress` | `string`   | Checksummed token contract address                         |
| `feeRecipient` | `string`   | Checksummed fee recipient address                          |
| `chainId`      | `number`   | Chain ID used for the query                                |
| `totalClaimed` | `string`   | Total claimed amount in wei (sum of **all** claims)        |
| `claimCount`   | `number`   | Total number of claim events (across all pages)            |
| `txHashes`     | `string[]` | Transaction hashes for the current page, most recent first |
| `pagination`   | `object`   | Pagination metadata                                        |

**Pagination Object**

| Field     | Type      | Description                                 |
| --------- | --------- | ------------------------------------------- |
| `limit`   | `number`  | Number of results per page                  |
| `offset`  | `number`  | Current offset                              |
| `hasMore` | `boolean` | Whether more results exist beyond this page |

#### 400 Bad Request

```json
{ "error": "Invalid token address" }
```

```json
{ "error": "Invalid fee recipient address" }
```

```json
{ "error": "Unsupported chain" }
```

#### 401 Unauthorized

```json
{ "error": "API key is required" }
```

```json
{ "error": "Unauthorized" }
```

#### 500 Internal Server Error

```json
{ "error": "Failed to fetch claimed fees" }
```

### Caching

Responses are cached for 60 seconds with a 120-second stale-while-revalidate window.

### Example

```bash
# First page (default limit=50, offset=0)
curl -H "x-api-key: YOUR_API_KEY" \
  "https://clanker.world/api/get-claimed-fees/0x9f86dB9fc6f7c9408e8Fda3Ff8ce4e78ac7a6b07/0xF60633D02690e2A15A54AB919925F3d038Df163e?chainId=8453"

# Paginated request
curl -H "x-api-key: YOUR_API_KEY" \
  "https://clanker.world/api/get-claimed-fees/0x9f86dB9fc6f7c9408e8Fda3Ff8ce4e78ac7a6b07/0xF60633D02690e2A15A54AB919925F3d038Df163e?chainId=8453&limit=20&offset=40"
```