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/{address} returns the full snapshot history for one wallet inside one stream, as long as the stream belongs to the organization associated with the API key. Use this endpoint when you need a wallet-level drilldown: detailed reward history, charting, reconciliation, user support tooling, or a per-wallet export that includes every available snapshot instead of just the most recent one.
The response includes both the wallet history and the parent stream object. This lets you render a wallet-detail page without making an extra call to the streams listing endpoint.

​
Endpoint

curl -X GET "https://earn.turtle.xyz/v1/streams/550e8400-e29b-41d4-a716-446655440000/wallets/0x1111111111111111111111111111111111111111" \
  -H "X-API-Key: pk_live_xxxxx"

​
Parameters

Path Parameters
​
id
uuid
required
Stream identifier. This selects the stream whose wallet history you want to inspect. The backend validates both that the UUID is syntactically correct and that the stream belongs to the organization associated with the API key.
​
address
string
required
Wallet address to inspect within the selected stream. This should be the EVM address whose snapshot history you want to retrieve. Use a standard hex address such as 0x1111111111111111111111111111111111111111; checksummed addresses are recommended for readability, although the backend ultimately resolves the address value against stored wallet records.

​
Response Example

{
  "wallet": {
    "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",
        "netTvl": "79250.10",
        "turtleTvl": "80000.12",
        "turtleNetTvl": "79250.10",
        "customMetrics": {
          "source": "vault-balance"
        }
      },
      {
        "timestamp": "2026-03-20T00:00:00Z",
        "rewardsAccumulated": "2150000000000000000",
        "rewardsAccumulatedBase": "2150000000000000000",
        "createdAt": "2026-03-20T00:05:00Z",
        "updatedAt": "2026-03-20T00:05:00Z",
        "tvl": "120340.66",
        "baseTvl": "120340.66",
        "netTvl": "118800.21",
        "turtleTvl": "120340.66",
        "turtleNetTvl": "118800.21",
        "customMetrics": {
          "source": "vault-balance"
        }
      }
    ],
    "stream": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "chainId": 1,
      "contractAddress": "0x4C6F5a1aA2B9985d4A8b9189C2118E7f55E2f701",
      "userId": null,
      "orgId": "9f51b66a-d13a-4b55-8515-ae6e4ef7cf25",
      "admin": "0x1111111111111111111111111111111111111111",
      "type": 2,
      "createdAt": "2026-03-10T12:00:00Z",
      "updatedAt": "2026-03-10T12:15:00Z",
      "startTimestamp": "2026-03-11T00:00:00Z",
      "endTimestamp": "2026-04-11T00:00:00Z",
      "totalAmount": "2500000000000000000000",
      "creationConfirmedAt": "2026-03-10T12:04:32Z",
      "snapshotComputationPaused": false,
      "merkleTreeComputationPaused": false,
      "hashCommitmentPaused": false,
      "claimPaused": false,
      "customArgs": {
        "targetTokenId": "8cc2ed9d-bd59-42fd-9df5-329fa22497b6",
        "apr": "0.12"
      },
      "adapters": [],
      "point": null,
      "strategy": "Fixed APR",
      "lastSnapshot": {
        "timestamp": "2026-03-20T00:00:00Z",
        "amountDistributed": "8123456789012345678",
        "amountBase": "8123456789012345678",
        "rootHash": null,
        "commitTxHash": null,
        "createdAt": "2026-03-20T00:01:00Z",
        "updatedAt": "2026-03-20T00:01:00Z",
        "tvl": "152340.12",
        "baseTvl": "152340.12",
        "netTvl": "149100.20",
        "turtleTvl": "152340.12",
        "turtleNetTvl": "149100.20",
        "customMetrics": {},
        "customArgs": {}
      },
      "committedSnapshot": null,
      "rewardToken": {
        "id": "56b0fab0-5c3e-49f6-a0a7-57e38d5ea999",
        "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
        "name": "USD Coin",
        "symbol": "USDC",
        "decimals": 6,
        "chainId": 1,
        "logoUrl": "https://cdn.example.com/tokens/usdc.png",
        "isAllowedRewardToken": true
      }
    }
  }
}

​
Response Semantics

Unlike the list-wallets endpoint, this response includes the full snapshots array available for the requested wallet in the selected stream.
If the stream exists but the requested address has no stored snapshots in that stream, the endpoint returns 404 Not Found.
The wallet.stream object follows the same Stream schema documented in Get Streams, so you can reuse the same client-side types for both endpoints.

​
Response Fields

wallet: WalletData
​
wallet
WalletData
required
Wallet-specific stream data, including the wallet identity, the complete snapshot history found for that wallet in the stream, and the parent Stream object.

​
WalletData

​
streamId
uuid
Identifier of the stream the wallet data belongs to. This duplicates the id path parameter in the response so downstream systems can store the wallet payload without separately carrying request context.
​
userAddress
string
Wallet address whose history is being returned.
​
snapshots
WalletSnapshot[]
Full list of snapshots found for this wallet in the stream. Each item represents one recorded point-in-time state used for reward accumulation and wallet-level TVL accounting. For the canonical WalletSnapshot field definitions, see the WalletSnapshot section on the Get Stream Wallets page.
​
stream
Stream
Parent stream object associated with the wallet snapshots. This uses the same schema documented in Get Streams.

​
Stream

The nested stream field uses the same Stream schema returned by Get Streams, including fields such as id, chainId, contractAddress, customArgs, lastSnapshot, committedSnapshot, point, and rewardToken. This means:
  • you can reuse the same TypeScript or backend DTO definitions for stream parsing,
  • you do not need a second request to resolve the stream metadata for the wallet detail view,
  • and you can display stream configuration and wallet history together in one screen.

​
Integration Notes

Because the full snapshots array is included, this endpoint is the correct source for historical charts, cumulative reward plots, wallet audits, and customer support views.
Reward fields are returned as strings because they may exceed the safe integer range of JavaScript numbers. Use a big-number library if you need arithmetic or unit conversion.
If you only need one row per wallet for a summary table, use Get Stream Wallets instead. It is more compact because it returns only the latest snapshot per wallet.

​
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 status is returned either when the stream does not belong to your organization scope or when the specified wallet address has no snapshot history in that stream.
Status Code: 500 Internal Server ErrorSolution: Retry the request and contact Turtle if the issue persists.