Get Stream Wallets

List the wallets participating in a stream, including each wallet’s latest snapshot and pagination metadata

Overview

GET /v2/streams/{id}/wallets returns the wallets that currently have snapshot data for a specific stream. This is a public endpoint — no API key is required.

Each returned wallet includes only its latest available snapshot for that stream. This makes the endpoint suitable for leaderboard views, partner dashboards, stream monitoring UIs, CSV exports, and paginated reporting workflows where you need a compact wallet-level summary instead of the full historical timeline.

Results are ordered by lastSnapshot.rewardsAccumulated in descending order, so the first wallets in the response are the ones with the highest accumulated rewards.

Endpoint

curl

curl -X GET "https://earn.turtle.xyz/v2/streams/550e8400-e29b-41d4-a716-446655440000/wallets?page=1&limit=20"

const streamId = '550e8400-e29b-41d4-a716-446655440000';
const page = 1;
const limit = 20;

const response = await fetch(
  `https://earn.turtle.xyz/v2/streams/${streamId}/wallets?page=${page}&limit=${limit}`
);

const data = await response.json();

Parameters

Path Parameters

id · uuid · required

Stream identifier. This is the unique UUID of the stream whose participant wallets you want to inspect.

Query Parameters

page · integer · default: 1

Page number for the paginated result set. Use this to move through the wallet list in stable chunks. Values lower than 1 are normalized by the backend to 1.

limit · integer · default: 20

Number of wallets to return per page. This is useful when building dashboards, tables, or exports. Values lower than 1 are normalized to 20, and values above 100 are capped to 100 by the backend.

Response Example

{
  "data": [
    {
      "userAddress": "0x1111111111111111111111111111111111111111",
      "lastSnapshot": {
        "timestamp": "2026-03-21T00:00:00Z",
        "rewardsAccumulated": "8345000000000000000",
        "rewardsAccumulatedBase": "8345000000000000000",
        "createdAt": "2026-03-21T00:05:00Z",
        "updatedAt": "2026-03-21T00:05:00Z",
        "tvl": "152340.12",
        "baseTvl": "152340.12",
        "baseApr": "0.105",
        "apr": "0.12",
        "customMetrics": {
          "source": "vault-balance",
          "weight": "1.00"
        }
      }
    },
    {
      "userAddress": "0x2222222222222222222222222222222222222222",
      "lastSnapshot": {
        "timestamp": "2026-03-21T00:00:00Z",
        "rewardsAccumulated": "4123000000000000000",
        "rewardsAccumulatedBase": "4123000000000000000",
        "createdAt": "2026-03-21T00:05:00Z",
        "updatedAt": "2026-03-21T00:05:00Z",
        "tvl": "97340.55",
        "baseTvl": "97340.55",
        "baseApr": "0.105",
        "apr": "0.12",
        "customMetrics": {}
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 42,
    "totalPages": 3,
    "hasNext": true,
    "hasPrevious": false
  }
}

Response Semantics

Each row contains the latest snapshot only

This endpoint does not return full wallet history. Instead, each wallet entry contains a lastSnapshot object representing the most recent snapshot currently available for that wallet in the stream.

An empty page is a valid response

If the stream exists but there are no wallet snapshots yet, or if you request a page beyond the available data, the endpoint returns data: [] together with pagination metadata instead of failing.

Response Fields

data: WalletWithLastSnapshot[]
pagination: PaginationResponse

data · WalletWithLastSnapshot[] · required

Paginated list of wallets that have snapshot data for the requested stream.

pagination · PaginationResponse · required

Pagination metadata describing the current page and the total size of the result set.

WalletWithLastSnapshot

userAddress · string

Wallet address that participated in the stream. This is the address whose balances or positions were tracked during snapshot computation. It is returned as an EVM address string.

lastSnapshot · WalletSnapshot

Most recent snapshot recorded for that wallet in this stream. This object summarizes the wallet’s latest reward accumulation and TVL metrics.

WalletSnapshot

APR-related wallet snapshot fields are only populated for token-based streams. For point-based streams, baseApr and apr are omitted from the snapshot.

timestamp · datetime

Effective timestamp of the snapshot. This is the time bucket the metrics correspond to, not necessarily the exact database write time.

rewardsAccumulated · string

Total rewards accumulated by the wallet at this snapshot, expressed in base units. For token streams, that means token wei-like units according to the reward asset decimals. For point streams, this is the accumulated point amount in the point’s base precision. This field represents the reward amount after adapters have been applied (post-adapter).

rewardsAccumulatedBase · string

Base accumulation value used by Turtle’s internal reward accounting. This value reflects the accumulated rewards before adapters are applied (pre-adapter).

createdAt · datetime

Timestamp when this wallet snapshot row was first created in Turtle’s backend.

updatedAt · datetime

Timestamp of the latest update applied to this wallet snapshot row.

tvl · decimal | null

Time-weighted-average (TWA) USD Total Value Locked (TVL) for the wallet after adapters have been applied.

baseTvl · decimal | null

TWA USD TVL for the wallet before adapters are applied.

baseApr · decimal | null

Base APR computed for the wallet snapshot before adapter adjustments, expressed as a decimal fraction — multiply by 100 for the percentage (for example, 0.05 means 5%). This is only populated for token-based streams.

apr · decimal | null

Effective APR computed for the wallet snapshot after adapter adjustments, expressed as a decimal fraction — multiply by 100 for the percentage (for example, 0.05 means 5%). This is only populated for token-based streams.

customMetrics · object | null

Strategy-specific metrics captured for the wallet snapshot. Treat this field as extensible JSON. Currently, it contains the wallet’s TWA token balance for the snapshot.

PaginationResponse

page · integer

Current page returned by the backend after normalization.

limit · integer

Number of items returned per page after normalization or capping.

total · integer

Total number of records available for the stream across all pages.

totalPages · integer

Total number of available pages for the current limit.

hasNext · boolean | null

Whether a page after the current one exists.

hasPrevious · boolean | null

Whether a page before the current one exists.

Integration Notes

Use this endpoint for tables and leaderboards

Because this endpoint returns one row per wallet with only the latest snapshot, it is the best choice for ranking views, summary widgets, CSV exports, and admin pages where full historical data would be too heavy.

Amounts are returned as strings on purpose

Reward amounts are serialized as strings to avoid precision loss in JavaScript and other environments that cannot safely represent very large integers. Keep them as strings in transit and convert them with a big-number library only when you need arithmetic.

Use the single-wallet endpoint for history

If you need the full timeline of snapshots for one wallet, call Get Wallet Data instead of this paginated summary endpoint.

Error Handling

Stream not found

Status Code: 404 Not Found

This happens when the id path parameter does not correspond to any known stream.

Unexpected internal error

Status Code: 500 Internal Server Error

Solution: Retry the request and contact Turtle if the issue persists.