Distributor Metrics

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

Send your API key via the X-API-Key header. See Authentication.

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

curl

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"

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

{
  "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

curl

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

{
  "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.