> ## Documentation Index
> Fetch the complete documentation index at: https://docs.turtle.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Distributor Metrics

> TVL and LP-count time-series attributed to a distributor (builder code).

> [!NOTE]
>
> Send your API key via the `X-API-Key` header. See [Authentication](https://docs.turtle.xyz/sdk/authentication/api-keys.md).

## Overview

Track the TVL and liquidity-provider counts attributed to a distributor over time. The `distributorId` is your builder code. Deposits routed through it are attributed on-chain by Lumon, and Turtle's own attributed volume is just another distributor ID, so the same endpoints work for any distributor you query.

| Endpoint | Returns |
| - | - |
| `GET /v2/metrics/distributor/{distributorId}` | TVL time-series, per-opportunity TVL as-of latest, optional top wallets |
| `GET /v2/metrics/distributor/{distributorId}/lps` | Active and cumulative LP counts over time |

## Distributor TVL

```bash curl theme={null}
curl -X GET "https://earn.turtle.xyz/v2/metrics/distributor/your-distributor-id?startDate=2026-05-01T00:00:00Z&endDate=2026-05-31T00:00:00Z&step=86400" \
  -H "X-API-Key: pk_live_xxxxx"
```

```typescript TypeScript theme={null}
const res = await fetch(
  'https://earn.turtle.xyz/v2/metrics/distributor/your-distributor-id?' +
  new URLSearchParams({ startDate: '2026-05-01T00:00:00Z', endDate: '2026-05-31T00:00:00Z', step: '86400' }),
  { headers: { 'X-API-Key': 'pk_live_xxxxx' } }
);
const { timeseries, asOf } = await res.json();
```

**Path Parameters**

**distributorId** `string` *required*

The distributor ID (builder code) to report on.

**Query Parameters**

**startDate** `string` *required*

Start of range, RFC 3339 (e.g. `2026-05-01T00:00:00Z`).

**endDate** `string` *required*

End of range, RFC 3339.

**step** `integer` (default: 900)

Bucket size in seconds. Defaults to `900` (15 minutes). Use `86400` for daily.

**opportunityIds** `array`

Optional. Restrict to specific opportunity UUIDs.

**productIds** `array`

Optional. Restrict to specific product UUIDs.

**includeTopWallets** `boolean` (default: false)

When `true`, include the top 50 wallets by attributed TVL.

**Response**

```json theme={null}
{
  "timeseries": [
    { "timestamp": "2026-05-30T00:00:00Z", "tvl": "2400000.0000" }
  ],
  "asOf": [
    { "opportunityId": "550e8400-e29b-41d4-a716-446655440000", "asOf": "2026-05-30T00:00:00Z" }
  ],
  "topWallets": [
    { "walletAddress": "0xe84ef330b7b5c02fb3fbe05f2a31cb331c2b874c", "totalTvl": "300000.0000", "asOf": "2026-05-30T00:00:00Z" }
  ]
}
```

**timeseries** `array`

TVL bucketed by `step`. Each point has a `timestamp` and a decimal `tvl`.

**asOf** `array`

Per-opportunity latest data timestamp within the range (`opportunityId`, `asOf`).

**topWallets** `array`

Present only when `includeTopWallets=true`. Top 50 wallets by attributed TVL, with `walletAddress`, `totalTvl`, and `asOf`.

## LP counts

```bash curl theme={null}
curl -X GET "https://earn.turtle.xyz/v2/metrics/distributor/your-distributor-id/lps?startDate=2026-05-01T00:00:00Z&endDate=2026-05-31T00:00:00Z&step=86400" \
  -H "X-API-Key: pk_live_xxxxx"
```

Takes the same `startDate` / `endDate` / `step` / `opportunityIds` / `productIds` parameters as the TVL endpoint.

**Response**

```json theme={null}
{
  "timeseries": [
    { "timestamp": "2026-05-30T00:00:00Z", "activeLps": 274, "participatedLps": 318 }
  ]
}
```

**timeseries\[].activeLps** `integer`

Distinct wallets with TVL greater than 0 in the bucket.

**timeseries\[].participatedLps** `integer`

All-time cumulative wallets that have ever had TVL attributed to this distributor.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.