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

<Note>
  All requests require an API key via the `X-API-Key` header. Reads accept a publishable key (`pk_live_`) from browser code or a secret key (`sk_live_`) from your backend. See [Authentication](/sdk/authentication/api-keys) for details.
</Note>

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

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" \
    -H "X-API-Key: sk_live_xxxxx"

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

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

  // Latest snapshot per stream (default)
  const response = await fetch(
    `https://earn.turtle.xyz/v2/streams/wallets/${walletAddress}`,
    { headers: { 'X-API-Key': process.env.TURTLE_API_KEY! } }
  );

  // Full snapshot history per stream
  const responseWithHistory = await fetch(
    `https://earn.turtle.xyz/v2/streams/wallets/${walletAddress}?withSnapshots=true`,
    { headers: { 'X-API-Key': process.env.TURTLE_API_KEY! } }
  );

  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
          },
          "estimatedLiveApr": "0.12"
        }
      }
    ]
  }
  ```

  ```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
          },
          "estimatedLiveApr": "0.12"
        }
      }
    ]
  }
  ```
</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`, `rewardToken`, and `estimatedLiveApr`.
</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`, `customArgs`, and `estimatedLiveApr`.

To show the rate the wallet's stream is currently paying, read `stream.estimatedLiveApr` rather than `stream.lastSnapshot.apr` or the wallet's own snapshot `apr` — those are historical values tied to their snapshot timestamps. See [Live APR vs snapshot APR](/sdk/streams/get-streams#live-apr-vs-snapshot-apr).

## 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="Missing or invalid API key">
    **Status Code:** 401 Unauthorized

    ```json theme={null}
    {
      "error": "API key required. Pass it via the X-API-Key header."
    }
    ```

    A key that is present but invalid, inactive, or expired also returns `401`, with `"Invalid API key"`, `"API key is inactive"`, or `"API key has expired"`.

    **Solution:** Send a valid key on the `X-API-Key` header.
  </Accordion>

  <Accordion title="Origin not allowed">
    **Status Code:** 403 Forbidden

    ```json theme={null}
    {
      "error": "Origin not allowed for this API key"
    }
    ```

    Publishable keys (`pk_live_`) are checked against the origin allowlist configured on the key. A request from an origin that is not on the list — including a server-side call that sends no `Origin` or `Referer` header — is rejected.

    **Solution:** Call from an allowlisted browser origin, or use a secret key (`sk_live_`) from your backend.
  </Accordion>

  <Accordion title="Rate limit exceeded">
    **Status Code:** 429 Too Many Requests

    ```json theme={null}
    {
      "error": "Rate limit exceeded"
    }
    ```

    Usage is metered per key, hourly and monthly. Every response carries the hourly budget in the `X-RateLimit-*` headers; keys with a monthly limit also get `X-Monthly-*` headers. A monthly overrun returns `"Monthly usage limit exceeded"` instead.

    **Solution:** Back off until the window resets — hourly limits also return `Retry-After` — or ask the Turtle team for a higher limit. See [Rate limits](/sdk/authentication/api-keys#rate-limits).
  </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>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.