> ## 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.

# 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.

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

## Endpoint

<CodeGroup>
  ```bash curl theme={null}
  curl -X GET "https://earn.turtle.xyz/v2/streams/550e8400-e29b-41d4-a716-446655440000/wallets?page=1&limit=20"
  ```

  ```typescript TypeScript theme={null}
  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();
  ```
</CodeGroup>

## Parameters

**Path Parameters**

<ParamField path="id" type="uuid" required>
  Stream identifier. This is the unique UUID of the stream whose participant wallets you want to inspect.
</ParamField>

**Query Parameters**

<ParamField query="page" type="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`.
</ParamField>

<ParamField query="limit" type="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.
</ParamField>

## Response Example

```json theme={null}
{
  "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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Response Fields

```typescript theme={null}
data: WalletWithLastSnapshot[]
pagination: PaginationResponse
```

<ResponseField name="data" type="WalletWithLastSnapshot[]" required>
  Paginated list of wallets that have snapshot data for the requested stream.
</ResponseField>

<ResponseField name="pagination" type="PaginationResponse" required>
  Pagination metadata describing the current page and the total size of the result set.
</ResponseField>

### `WalletWithLastSnapshot`

<ResponseField name="userAddress" type="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.
</ResponseField>

<ResponseField name="lastSnapshot" type="WalletSnapshot">
  Most recent snapshot recorded for that wallet in this stream. This object summarizes the wallet's latest reward accumulation and TVL metrics.
</ResponseField>

### `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.

<ResponseField name="timestamp" type="datetime">
  Effective timestamp of the snapshot. This is the time bucket the metrics correspond to, not necessarily the exact database write time.
</ResponseField>

<ResponseField name="rewardsAccumulated" type="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).
</ResponseField>

<ResponseField name="rewardsAccumulatedBase" type="string">
  Base accumulation value used by Turtle's internal reward accounting. This value reflects the accumulated rewards before adapters are applied (pre-adapter).
</ResponseField>

<ResponseField name="createdAt" type="datetime">
  Timestamp when this wallet snapshot row was first created in Turtle's backend.
</ResponseField>

<ResponseField name="updatedAt" type="datetime">
  Timestamp of the latest update applied to this wallet snapshot row.
</ResponseField>

<ResponseField name="tvl" type="decimal | null">
  Time-weighted-average (TWA) USD Total Value Locked (TVL) for the wallet after adapters have been applied.
</ResponseField>

<ResponseField name="baseTvl" type="decimal | null">
  TWA USD TVL for the wallet before adapters are applied.
</ResponseField>

<ResponseField name="baseApr" type="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.
</ResponseField>

<ResponseField name="apr" type="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.
</ResponseField>

<ResponseField name="customMetrics" type="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.
</ResponseField>

### `PaginationResponse`

<ResponseField name="page" type="integer">
  Current page returned by the backend after normalization.
</ResponseField>

<ResponseField name="limit" type="integer">
  Number of items returned per page after normalization or capping.
</ResponseField>

<ResponseField name="total" type="integer">
  Total number of records available for the stream across all pages.
</ResponseField>

<ResponseField name="totalPages" type="integer">
  Total number of available pages for the current `limit`.
</ResponseField>

<ResponseField name="hasNext" type="boolean | null">
  Whether a page after the current one exists.
</ResponseField>

<ResponseField name="hasPrevious" type="boolean | null">
  Whether a page before the current one exists.
</ResponseField>

## Integration Notes

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Use the single-wallet endpoint for history">
    If you need the full timeline of snapshots for one wallet, call [Get Wallet Data](/sdk/streams/get-wallet) instead of this paginated summary endpoint.
  </Accordion>
</AccordionGroup>

## Error Handling

<AccordionGroup>
  <Accordion title="Stream not found">
    **Status Code:** 404 Not Found

    This happens when the `id` path parameter does not correspond to any known stream.
  </Accordion>

  <Accordion title="Unexpected internal error">
    **Status Code:** 500 Internal Server Error

    **Solution:** Retry the request and contact Turtle if the issue persists.
  </Accordion>
</AccordionGroup>