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

> Retrieve all snapshots accumulated by one wallet in a specific stream, together with the parent stream object

<Note>
  All requests require an API key via the `X-API-Key` header.
  See [Authentication](/sdk/authentication/api-keys) for details.
</Note>

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

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

## Endpoint

<CodeGroup>
  ```bash curl theme={null}
  curl -X GET "https://earn.turtle.xyz/v1/streams/550e8400-e29b-41d4-a716-446655440000/wallets/0x1111111111111111111111111111111111111111" \
    -H "X-API-Key: pk_live_xxxxx"
  ```

  ```typescript TypeScript theme={null}
  const streamId = '550e8400-e29b-41d4-a716-446655440000';
  const walletAddress = '0x1111111111111111111111111111111111111111';

  const response = await fetch(
    `https://earn.turtle.xyz/v1/streams/${streamId}/wallets/${walletAddress}`,
    {
      headers: { 'X-API-Key': process.env.TURTLE_SECRET_KEY! },
    }
  );

  const data = await response.json();
  ```
</CodeGroup>

## Parameters

**Path Parameters**

<ParamField path="id" type="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.
</ParamField>

<ParamField path="address" type="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.
</ParamField>

## Response Example

```json theme={null}
{
  "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",
        "baseApr": "0.105",
        "apr": "0.12",
        "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",
        "baseApr": "0.105",
        "apr": "0.12",
        "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",
        "baseApr": "0.105",
        "apr": "0.12",
        "rewardTokenPrice": "1.00",
        "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

<AccordionGroup>
  <Accordion title="This endpoint returns full wallet history">
    Unlike the list-wallets endpoint, this response includes the full `snapshots` array available for the requested wallet in the selected stream.
  </Accordion>

  <Accordion title="A wallet must have snapshot records to be returned">
    If the stream exists but the requested address has no stored snapshots in that stream, the endpoint returns `404 Not Found`.
  </Accordion>

  <Accordion title="The nested stream object is the same schema used elsewhere">
    The `wallet.stream` object follows the same `Stream` schema documented in [Get Streams](/sdk/streams/get-streams), so you can reuse the same client-side types for both endpoints.
  </Accordion>
</AccordionGroup>

## Response Fields

```typescript theme={null}
wallet: WalletData
```

<ResponseField name="wallet" type="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.
</ResponseField>

### `WalletData`

<ResponseField name="streamId" type="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.
</ResponseField>

<ResponseField name="userAddress" type="string">
  Wallet address whose history is being returned.
</ResponseField>

<ResponseField name="snapshots" type="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. APR-related fields inside each `WalletSnapshot` are only populated for token-based streams. 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">
  Parent stream object associated with the wallet snapshots. This uses the same schema documented in [Get Streams](/sdk/streams/get-streams).
</ResponseField>

### `Stream`

The nested `stream` field uses the same `Stream` schema returned by [Get Streams](/sdk/streams/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

<AccordionGroup>
  <Accordion title="Use this endpoint for charts and wallet drilldowns">
    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.
  </Accordion>

  <Accordion title="Large integers must be handled with big-number tooling">
    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.
  </Accordion>

  <Accordion title="Use the list endpoint for performance-sensitive overviews">
    If you only need one row per wallet for a summary table, use [Get Stream Wallets](/sdk/streams/get-wallets) instead. It is more compact because it returns only the latest snapshot per wallet.
  </Accordion>
</AccordionGroup>

## Error Handling

<AccordionGroup>
  <Accordion title="Missing or invalid API key">
    **Status Code:** 401 Unauthorized

    ```json theme={null}
    {
      "error": "Invalid API key"
    }
    ```

    **Solution:** Pass a valid `X-API-Key` header belonging to an organization-scoped API key.
  </Accordion>

  <Accordion title="Stream not found or wallet has no snapshots">
    **Status Code:** 404 Not Found

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