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.

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.

Endpoint

curl

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

Parameters

Path Parameters

address · string · required

EVM wallet address to look up, such as 0x1111111111111111111111111111111111111111. The backend resolves the address against stored wallet snapshot records across all streams.

Query Parameters

withSnapshots · 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.

Response Example

withSnapshots=false (default)

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

Response Semantics

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, but embedded in an array for a consistent shape regardless of the flag.

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 but across all streams in a single response.

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.

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.

Response Fields

streams: WalletData[]

streams · WalletData[] · required

List of streams the wallet has participated in, one entry per stream.

WalletData

streamId · uuid

Identifier of the stream. This duplicates the stream.id field for convenience.

userAddress · string

The wallet address whose data is being returned. Mirrors the address path parameter.

snapshots · 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 page.

stream · Stream

Full stream object. Uses the same Stream schema returned by Get Streams, including id, chainId, contractAddress, customArgs, lastSnapshot, committedSnapshot, point, rewardToken, and estimatedLiveApr.

WalletSnapshot

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

timestamp · datetime

Effective timestamp of the snapshot — the time bucket the metrics correspond to, not the database write time.

rewardsAccumulated · 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.

rewardsAccumulatedBase · string

Accumulated rewards before adapter adjustments are applied.

createdAt · datetime

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

updatedAt · datetime

Timestamp of the latest update applied to this snapshot row.

tvl · decimal | null

Time-weighted-average (TWA) USD TVL for the wallet after adapters.

baseTvl · decimal | null

TWA USD TVL for the wallet before adapters.

baseApr · 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.

apr · 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.

customMetrics · object | null

Strategy-specific metrics for the snapshot. Treat as extensible JSON.

Stream

The stream field uses the same Stream schema returned by 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.

Integration Notes

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.

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.

Use single-stream endpoints for stream-scoped queries

If you need snapshot data for one wallet within a specific stream, use Get Wallet Data. If you need a paginated list of all wallets for one stream, use Get Stream Wallets.

Error Handling

Unexpected internal error

Status Code: 500 Internal Server Error

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