> ## 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](/sdk/authentication/api-keys).
</Note>

## 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 /v1/metrics/distributor/{distributorId}`     | TVL time-series, per-opportunity TVL as-of latest, optional top wallets |
| `GET /v1/metrics/distributor/{distributorId}/lps` | Active and cumulative LP counts over time                               |

## Distributor TVL

<CodeGroup>
  ```bash curl theme={null}
  curl -X GET "https://earn.turtle.xyz/v1/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/v1/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();
  ```
</CodeGroup>

**Path Parameters**

<ParamField path="distributorId" type="string" required>
  The distributor ID (builder code) to report on.
</ParamField>

**Query Parameters**

<ParamField query="startDate" type="string" required>
  Start of range, RFC 3339 (e.g. `2026-05-01T00:00:00Z`).
</ParamField>

<ParamField query="endDate" type="string" required>
  End of range, RFC 3339.
</ParamField>

<ParamField query="step" type="integer" default="900">
  Bucket size in seconds. Defaults to `900` (15 minutes). Use `86400` for daily.
</ParamField>

<ParamField query="opportunityIds" type="array">
  Optional. Restrict to specific opportunity UUIDs.
</ParamField>

<ParamField query="productIds" type="array">
  Optional. Restrict to specific product UUIDs.
</ParamField>

<ParamField query="includeTopWallets" type="boolean" default="false">
  When `true`, include the top 50 wallets by attributed TVL.
</ParamField>

**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" }
  ]
}
```

<ResponseField name="timeseries" type="array">
  TVL bucketed by `step`. Each point has a `timestamp` and a decimal `tvl`.
</ResponseField>

<ResponseField name="asOf" type="array">
  Per-opportunity latest data timestamp within the range (`opportunityId`, `asOf`).
</ResponseField>

<ResponseField name="topWallets" type="array">
  Present only when `includeTopWallets=true`. Top 50 wallets by attributed TVL, with `walletAddress`, `totalTvl`, and `asOf`.
</ResponseField>

## LP counts

```bash curl theme={null}
curl -X GET "https://earn.turtle.xyz/v1/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 }
  ]
}
```

<ResponseField name="timeseries[].activeLps" type="integer">
  Distinct wallets with TVL greater than 0 in the bucket.
</ResponseField>

<ResponseField name="timeseries[].participatedLps" type="integer">
  All-time cumulative wallets that have ever had TVL attributed to this distributor.
</ResponseField>