Skip to main content
All requests require an API key via the X-API-Key header. See Authentication for details.

​
Overview

GET /v1/streams/{id}/wallets returns the wallets that currently have snapshot data for a specific stream, scoped to the organization that owns the API key. 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.
Results are ordered by lastSnapshot.rewardsAccumulated in descending order, so the first wallets in the response are the ones with the highest accumulated rewards.

​
Endpoint

curl -X GET "https://earn.turtle.xyz/v1/streams/550e8400-e29b-41d4-a716-446655440000/wallets?page=1&limit=20" \
  -H "X-API-Key: pk_live_xxxxx"

​
Parameters

Path Parameters
​
id
uuid
required
Stream identifier. This is the unique UUID of the stream whose participant wallets you want to inspect. The API first verifies that this stream belongs to the organization associated with the API key, so a valid UUID alone is not enough: the stream must also be in your organization scope.
Query Parameters
​
page
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.
​
limit
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.

​
Response Example

{
  "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",
        "netTvl": "149100.20",
        "turtleTvl": "152340.12",
        "turtleNetTvl": "149100.20",
        "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",
        "netTvl": "95110.40",
        "turtleTvl": "97340.55",
        "turtleNetTvl": "95110.40",
        "customMetrics": {}
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 42,
    "totalPages": 3
  }
}

​
Response Semantics

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.
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.
Even if you know a valid stream UUID, the API only returns data when that stream belongs to the organization associated with the API key.

​
Response Fields

data: WalletWithLastSnapshot[]
pagination: PaginationResponse
​
data
WalletWithLastSnapshot[]
required
Paginated list of wallets that have snapshot data for the requested stream.
​
pagination
PaginationResponse
required
Pagination metadata describing the current page and the total size of the result set.

​
WalletWithLastSnapshot

​
userAddress
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.
​
lastSnapshot
WalletSnapshot
Most recent snapshot recorded for that wallet in this stream. This object summarizes the wallet’s latest reward accumulation and TVL metrics.

​
WalletSnapshot

​
timestamp
datetime
Effective timestamp of the snapshot. This is the time bucket the metrics correspond to, not necessarily the exact database write time.
​
rewardsAccumulated
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).
​
rewardsAccumulatedBase
string
Base accumulation value used by Turtle’s internal reward accounting. This value reflects the accumulated rewards before adapters are applied (pre-adapter).
​
createdAt
datetime
Timestamp when this wallet snapshot row was first created in Turtle’s backend.
​
updatedAt
datetime
Timestamp of the latest update applied to this wallet snapshot row.
​
tvl
decimal | null
Time-weighted-average (TWA) USD Total Value Locked (TVL) for the wallet after adapters have been applied.
​
baseTvl
decimal | null
TWA USD TVL for the wallet before adapters are applied.
​
netTvl
decimal | null
TWA USD TVL of the wallet’s net position. Calculated as TWA of min(0, tokenBalance - startBalance) * priceUSD, where startBalance is the user’s token balance at the stream’s startTimestamp. Both priceUSD and tokenBalance are time-weighted averages (TWA).
​
turtleTvl
decimal | null
TWA USD TVL restricted to Turtle users and windowed to each user’s sign-up timestamp. This measures the portion of the wallet’s TVL that should be considered for Turtle-specific user eligibility and reward rules.
​
turtleNetTvl
decimal | null
Turtle-equivalent of netTvl: a TWA net position calculated using the user’s token balance at their sign-up timestamp as the reference instead of the stream startTimestamp.
​
customMetrics
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.

​
PaginationResponse

​
page
integer
Current page returned by the backend after normalization.
​
limit
integer
Number of items returned per page after normalization or capping.
​
total
integer
Total number of records available for the stream across all pages.
​
totalPages
integer
Total number of available pages for the current limit.

​
Integration Notes

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.
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.
If you need the full timeline of snapshots for one wallet, call Get Wallet Data instead of this paginated summary endpoint.

​
Error Handling

Status Code: 401 Unauthorized
{
  "error": "Invalid API key"
}
Solution: Pass a valid X-API-Key header belonging to an organization-scoped API key.
Status Code: 404 Not FoundThis happens when the id path parameter does not correspond to a stream owned by the organization associated with the API key.
Status Code: 500 Internal Server ErrorSolution: Retry the request and contact Turtle if the issue persists.