> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chainstream.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Wallets

> Balances, PnL, net-worth curves, transfer history and activity for any on-chain address.

The **Wallets** data product turns any on-chain address into a queryable profile — current holdings, historical PnL, activity patterns, and first-transaction timing — across every chain we support, without you having to stitch multiple RPCs together.

## What's inside

| Field group    | Examples                                                                             |
| :------------- | :----------------------------------------------------------------------------------- |
| Identity       | `chainId`, `address`, `ens`/`sns`, `tags`, `firstSeenAt`                             |
| Holdings       | `holdings[]` with `token`, `balance`, `valueUsd`, `costBasisUsd`, `unrealizedPnlUsd` |
| Net worth      | `netWorthUsd`, `netWorthHistory[]` at hour/day granularity                           |
| Activity       | `txCount24h`, `tradeCount30d`, `avgTradeSizeUsd`, `activeChains[]`                   |
| Classification | `walletType` (EOA / contract / exchange / smart-money), `riskScore`                  |

## Coverage & freshness

* **Cross-chain**: balances and PnL aggregated across every supported chain by default; filter per-chain if needed.
* **Freshness**: holdings refresh within seconds of a matching transfer/trade; net-worth history snapshots hourly.

## Access

<CardGroup cols={2}>
  <Card title="REST" icon="database" href="/en/api-reference/endpoint/data/wallet/v2/wallet-chain-walletaddress-pnl-get">
    `/v2/wallet/{chain}/{walletAddress}/pnl`, `/v2/wallet/{chain}/{walletAddress}/net-worth`, `/v2/wallet/{chain}/{walletAddress}/tokens-balance`, `/v2/wallet/{chain}/{walletAddress}/transfers`.
  </Card>

  <Card title="GraphQL" icon="diagram-project" href="/en/graphql/getting-started/overview">
    Query holdings-joined-trades in a single request.
  </Card>

  <Card title="WebSocket" icon="bolt" href="/en/api-reference/endpoint/websocket/api">
    Per-wallet channels: `dex-wallet-balance:{chain}_{walletAddress}`, `dex-wallet-trade:{chain}_{walletAddress}`, `dex-wallet-token-pnl:` / `dex-wallet-pnl-list:`. SDK: `client.stream.subscribeWalletBalance` / `subscribeWalletTrade` / `subscribeWalletPnl`.
  </Card>

  <Card title="Kafka" icon="tower-broadcast" href="/en/api-reference/kafka-topics/evm">
    Built by consuming `{chain}.v1.transfers.proto` + `{chain}.dex.trades` topics and filtering by address.
  </Card>

  <Card title="SDK" icon="box" href="/en/sdks/overview">
    `client.wallet.getPnl()`, `client.wallet.getNetWorth()`, `client.wallet.getTokensBalance()`.
  </Card>

  <Card title="MCP" icon="robot" href="/en/docs/ai-agents/mcp-server/introduction">
    `wallets_profile`, `wallets_activity` for agents.
  </Card>
</CardGroup>

## Common use cases

* Portfolio dashboards for retail users
* Whale / smart-money follower feeds
* KYC-lite "who is this wallet?" previews
* Per-campaign attribution (airdrops, rewards)
* Compliance-triage input ([see KYA](/en/docs/compliance/kya-concepts))

## Billing

Profile and holdings endpoints are **1 read unit**; time-series PnL and history scale with the returned range.

## Next

<CardGroup cols={2}>
  <Card title="Smart Money" icon="brain" href="/en/docs/data-products/smart-money">
    Curated high-performing wallet cohorts built on top of Wallets.
  </Card>

  <Card title="KYA — Know Your Address" icon="user-shield" href="/en/docs/compliance/kya-concepts">
    Risk-scored profile for any wallet address.
  </Card>
</CardGroup>