Skip to main content

​
Overview

GET /v1/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

# Latest snapshot per stream (default)
curl -X GET "https://earn.turtle.xyz/v1/streams/wallets/0x1111111111111111111111111111111111111111"

# Full snapshot history per stream
curl -X GET "https://earn.turtle.xyz/v1/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

{
  "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",
          "netTvl": "149100.20",
          "turtleTvl": "152340.12",
          "turtleNetTvl": "149100.20",
          "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
        }
      }
    }
  ]
}

​
Response Semantics

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.
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.
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.
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, and rewardToken.

​
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.
​
netTvl
decimal | null
TWA USD TVL of the wallet’s net position relative to the stream’s startTimestamp.
​
turtleTvl
decimal | null
TWA USD TVL restricted to Turtle users, windowed to each user’s sign-up timestamp.
​
turtleNetTvl
decimal | null
Turtle-equivalent of netTvl, using the user’s token balance at sign-up as the reference.
​
baseApr
decimal | null
Base APR before adapter adjustments. Only populated for token-based streams.
​
apr
decimal | null
Effective APR after adapter adjustments. 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, and customArgs.

​
Integration Notes

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

Status Code: 500 Internal Server ErrorSolution: Retry the request and contact Turtle if the issue persists.