> ## 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 Streams for Wallet

> Retrieve all streams a wallet has participated in, with snapshot data per stream

## Overview

`GET /v2/streams/wallets/{address}` returns all streams a given wallet address has snapshot data in, together with the wallet's snapshot history for each stream. This is a public endpoint — no API key is required.

By default the endpoint returns only the latest snapshot per stream, which is efficient for summary views. Pass `withSnapshots=true` to include the full historical timeline for every stream.

<Info>
  Use `withSnapshots=false` (the default) for portfolio overviews and summary widgets. Use `withSnapshots=true` when you need the full reward history across all streams for a wallet, such as for charts or reconciliation workflows.
</Info>

## Endpoint

<CodeGroup>
  ```bash curl theme={null}
  # Latest snapshot per stream (default)
  curl -X GET "https://earn.turtle.xyz/v2/streams/wallets/0x1111111111111111111111111111111111111111"

  # Full snapshot history per stream
  curl -X GET "https://earn.turtle.xyz/v2/streams/wallets/0x1111111111111111111111111111111111111111?withSnapshots=true"
  ```

  ```typescript TypeScript theme={null}
  const walletAddress = '0x1111111111111111111111111111111111111111';

  // Latest snapshot per stream (default)
  const response = await fetch(
    `https://earn.turtle.xyz/v2/streams/wallets/${walletAddress}`
  );

  // Full snapshot history per stream
  const responseWithHistory = await fetch(
    `https://earn.turtle.xyz/v2/streams/wallets/${walletAddress}?withSnapshots=true`
  );

  const data = await response.json();
  ```
</CodeGroup>

## Parameters

**Path Parameters**

<ParamField path="address" type="string" required>
  EVM wallet address to look up, such as `0x1111111111111111111111111111111111111111`. The backend resolves the address against stored wallet snapshot records across all streams.
</ParamField>

**Query Parameters**

<ParamField query="withSnapshots" type="boolean" default={false}>
  Controls how much snapshot history is returned per stream.

  * `false` (default) — each stream entry contains a single-element `snapshots` array with the most recent snapshot only. Use this for summary tables and portfolio cards.
  * `true` — each stream entry contains the full `snapshots` array with every recorded snapshot. Use this for historical charts, cumulative reward plots, and reconciliation.
</ParamField>

## Response Example

<CodeGroup>
  ```json withSnapshots=false (default) theme={null}
  {
    "streams": [
      {
        "streamId": "550e8400-e29b-41d4-a716-446655440000",
        "userAddress": "0x1111111111111111111111111111111111111111",
        "snapshots": [
          {
            "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" }
          }
        ],
        "stream": {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "chainId": 1,
          "strategy": "Fixed APR",
          "totalAmount": "2500000000000000000000",
          "rewardToken": {
            "symbol": "USDC",
            "decimals": 6
          }
        }
      }
    ]
  }
  ```

  ```json withSnapshots=true theme={null}
  {
    "streams": [
      {
        "streamId": "550e8400-e29b-41d4-a716-446655440000",
        "userAddress": "0x1111111111111111111111111111111111111111",
        "snapshots": [
          {
            "timestamp": "2026-03-19T00:00:00Z",
            "rewardsAccumulated": "1000000000000000000",
            "rewardsAccumulatedBase": "1000000000000000000",
            "createdAt": "2026-03-19T00:05:00Z",
            "updatedAt": "2026-03-19T00:05:00Z",
            "tvl": "80000.12",
            "baseTvl": "80000.12",
            "baseApr": "0.105",
            "apr": "0.12",
            "customMetrics": { "source": "vault-balance" }
          },
          {
            "timestamp": "2026-03-20T00:00:00Z",
            "rewardsAccumulated": "4500000000000000000",
            "rewardsAccumulatedBase": "4500000000000000000",
            "createdAt": "2026-03-20T00:05:00Z",
            "updatedAt": "2026-03-20T00:05:00Z",
            "tvl": "120340.66",
            "baseTvl": "120340.66",
            "baseApr": "0.105",
            "apr": "0.12",
            "customMetrics": { "source": "vault-balance" }
          },
          {
            "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" }
          }
        ],
        "stream": {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "chainId": 1,
          "strategy": "Fixed APR",
          "totalAmount": "2500000000000000000000",
          "rewardToken": {
            "symbol": "USDC",
            "decimals": 6
          }
        }
      }
    ]
  }
  ```
</CodeGroup>

## Response Semantics

<AccordionGroup>
  <Accordion title="snapshots contains one item by default">
    When `withSnapshots=false`, each stream entry's `snapshots` array always contains exactly one element — the most recent snapshot recorded for that wallet in that stream. This is equivalent to the `lastSnapshot` field returned by [Get Stream Wallets](/sdk/streams/get-wallets), but embedded in an array for a consistent shape regardless of the flag.
  </Accordion>

  <Accordion title="withSnapshots=true returns the full timeline">
    When `withSnapshots=true`, the `snapshots` array contains every recorded snapshot for the wallet in that stream, ordered by timestamp descending. The first element is always the most recent. This is the same data returned by [Get Wallet Data](/sdk/streams/get-wallet) but across all streams in a single response.
  </Accordion>

  <Accordion title="An empty array is a valid response">
    If the wallet address has no snapshot data in any stream, the endpoint returns `streams: []` rather than failing. This means the wallet has not participated in any confirmed stream yet.
  </Accordion>

  <Accordion title="Only confirmed, non-deleted streams are included">
    The response only includes streams whose on-chain creation has been confirmed. Streams in a pending creation state are not returned even if internal records already exist.

    Additionally, soft-deleted streams are always excluded — even if the wallet accumulated snapshot data in them before deletion. This means a wallet's historical snapshots for a deleted stream will never appear in this response.
  </Accordion>
</AccordionGroup>

## Response Fields

```typescript theme={null}
streams: WalletData[]
```

<ResponseField name="streams" type="WalletData[]" required>
  List of streams the wallet has participated in, one entry per stream.
</ResponseField>

### `WalletData`

<ResponseField name="streamId" type="uuid">
  Identifier of the stream. This duplicates the `stream.id` field for convenience.
</ResponseField>

<ResponseField name="userAddress" type="string">
  The wallet address whose data is being returned. Mirrors the `address` path parameter.
</ResponseField>

<ResponseField name="snapshots" type="WalletSnapshot[]">
  Snapshot history for this wallet in the stream. Contains one element when `withSnapshots=false` (the latest only), or the full timeline when `withSnapshots=true`. Ordered by timestamp descending. For the canonical `WalletSnapshot` field definitions, see the `WalletSnapshot` section on the [Get Stream Wallets](/sdk/streams/get-wallets) page.
</ResponseField>

<ResponseField name="stream" type="Stream">
  Full stream object. Uses the same `Stream` schema returned by [Get Streams](/sdk/streams/get-streams), including `id`, `chainId`, `contractAddress`, `customArgs`, `lastSnapshot`, `committedSnapshot`, `point`, and `rewardToken`.
</ResponseField>

### `WalletSnapshot`

APR-related fields are only populated for token-based streams. For point-based streams, `baseApr` and `apr` are omitted.

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

<ResponseField name="rewardsAccumulated" type="string">
  Total rewards accumulated by the wallet at this snapshot, in base units (wei for token streams, point precision for point streams). Reflects post-adapter values.
</ResponseField>

<ResponseField name="rewardsAccumulatedBase" type="string">
  Accumulated rewards before adapter adjustments are applied.
</ResponseField>

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

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

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

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

<ResponseField name="baseApr" type="decimal | null">
  Base APR before adapter adjustments, expressed as a decimal fraction — multiply by 100 for the percentage (for example, `0.05` means 5%). Only populated for token-based streams.
</ResponseField>

<ResponseField name="apr" type="decimal | null">
  Effective APR after adapter adjustments, expressed as a decimal fraction — multiply by 100 for the percentage (for example, `0.05` means 5%). Only populated for token-based streams.
</ResponseField>

<ResponseField name="customMetrics" type="object | null">
  Strategy-specific metrics for the snapshot. Treat as extensible JSON.
</ResponseField>

### `Stream`

The `stream` field uses the same `Stream` schema returned by [Get Streams](/sdk/streams/get-streams). See that page for the complete field reference, including `lastSnapshot`, `committedSnapshot`, `rewardToken`, `point`, and `customArgs`.

## Integration Notes

<AccordionGroup>
  <Accordion title="Choose withSnapshots based on your use case">
    Use `withSnapshots=false` (the default) for any view that only needs the current state: portfolio cards, leaderboards, summary widgets. Use `withSnapshots=true` only when you need to chart or reconcile the full reward history — it returns significantly more data per stream.
  </Accordion>

  <Accordion title="Amounts are returned as strings on purpose">
    Reward amounts are serialized as strings to avoid precision loss in JavaScript environments. Keep them as strings in transit and use a big-number library only when arithmetic or unit conversion is needed.
  </Accordion>

  <Accordion title="Use single-stream endpoints for stream-scoped queries">
    If you need snapshot data for one wallet within a specific stream, use [Get Wallet Data](/sdk/streams/get-wallet). If you need a paginated list of all wallets for one stream, use [Get Stream Wallets](/sdk/streams/get-wallets).
  </Accordion>
</AccordionGroup>

## Error Handling

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

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