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

# PnL V2 Overview

> How Solana Tracker PnL V2 works — endpoint groups, key concepts, pagination, identity tags, excluded assets, and live wallet PnL updates.

<Info>
  **Base URL:** `https://data.solanatracker.io`\
  **Auth:** Pass your API key in the `x-api-key` header.\
  **Values:** All monetary amounts are USD. Timestamps are Unix milliseconds unless noted.
</Info>

## Essentials

### What PnL V2 Includes

* **Scale.** PnL is tracked for around **300–400 million wallets** with billions of token positions, updated close to real time.
* **Token coverage.** Every SPL token is supported **except stablecoins and SOL**.
* **Wallet endpoints.** Use wallet endpoints for any wallet, even if it is not on a leaderboard.
* **Identity tags.** Wallets can include an `identity` object with labels such as KOL, bot, exchange, pool, developer, trading platform, or SNS primary `.sol` domain.

### What PnL V2 Excludes

Stablecoins and SOL are intentionally excluded from PnL positions because they are quote assets. A quote asset is the token used to price a trade, not the position being measured.

Arbitrage wallets are excluded by default with `excludeArbitrage=true`. Arbitrage PnL can be noisy because those wallets often trade for tiny differences across pools. Pass `excludeArbitrage=false` to include them.

The top-traders leaderboard covers the **top 500k wallets** per period. If a wallet is outside that ranked set, query it directly with the wallet endpoints.

### Identity Tags

Every wallet can carry a structured `identity`. Supported today:

* **Bots and MEV** — `potential_bot` (heuristic), `bot` (curated named bots like Mayhem Bot), and `arbitrage` (confirmed MEV).
* **Platforms** — `axiom`, `bloom`, and `photon`. The API also accepts `axiom-flash` as an `axiom` alias.
* **Safety / infrastructure tags** — curated `hacker`, `spam_dusting`, and `exchange` labels when known.
* **Pool and developer** roles are automatically resolved on token-scoped endpoints.
* **SNS:** primary `.sol` domain via Ridge (`identity.sns`, `sns` tag). See [SNS Primary Domain](/guides/pnl-v2/sns-identity).

### PnL Modes

Wallet-summary, positions, single-position, top-trader leaderboard, and position batch endpoints accept `?pnlMode=`.

| Mode               | Behavior                                                                                                                                         |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `strict` (default) | Safest view. Excludes positions where the sell amount is larger than the buy amount, which usually means the PnL is invalid or misleading.       |
| `adjusted`         | Keeps those positions but recalculates realized PnL with an adjusted cost basis. Useful when strict mode hides positions you still want to show. |
| `raw`              | No filtering. Realized PnL is returned exactly as calculated. Use this when you need the unfiltered numbers.                                     |

Endpoints that support `pnlMode` echo it back in the response. Position rows include both `pnl.realized` (mode-aware) and `pnl.realizedRaw` (unfiltered) so your UI can toggle without re-querying.

The KOL leaderboards, history, chart, performance, highlights, risk, token-traders, first-buyers, and wallet-summary batch endpoints do not take `pnlMode`; they return the API's fixed server-side view for that dataset.

***

## What is PnL V2?

PnL V2 tracks profit and loss for every Solana wallet. Give it a wallet address and it returns:

* A **summary** with total PnL, win rate, and token counts
* **Per-token positions** with cost basis, current value, and realized/unrealized PnL
* **Daily history** and chart data for equity curves
* **Leaderboards** for KOLs and top traders
* **Risk analysis** with concentration and exposure metrics
* **Batch lookups** for hundreds of wallet-token pairs at once

<CardGroup cols={2}>
  <Card title="Wallet Analytics" href="/data-api/pnl-v2/get-wallet-summary">
    PnL summaries, positions, daily history, performance, and risk for any wallet.
  </Card>

  <Card title="Token Intelligence" href="/data-api/pnl-v2/get-token-traders">
    Every trader on a token — who's profitable, who's underwater, who bought first.
  </Card>

  <Card title="Leaderboards" href="/data-api/pnl-v2/get-kol-leaderboard">
    KOL and top trader rankings with rolling windows and calendar views.
  </Card>

  <Card title="Batch Operations" href="/data-api/pnl-v2/get-position-batch-lookup">
    Positions for hundreds of wallet+token pairs in one request.
  </Card>
</CardGroup>

***

## Endpoint Groups

<Columns cols={2}>
  <Card title="Know the endpoint?" href="/data-api/pnl-v2/get-wallet-summary">
    Go straight to the API reference for schemas and parameters.
  </Card>

  <Card title="Building a workflow?" href="/guides/pnl-v2/wallet-analysis">
    Continue with the step-by-step guides below.
  </Card>
</Columns>

### Wallet Endpoints

| Endpoint                                                                                    | What it returns                        |
| ------------------------------------------------------------------------------------------- | -------------------------------------- |
| [GET /v2/pnl/wallets/\{wallet}](/data-api/pnl-v2/get-wallet-summary)                        | PnL summary, win rate, token counts    |
| [GET /v2/pnl/wallets/\{wallet}/positions](/data-api/pnl-v2/get-wallet-positions)            | All positions with sorting and filters |
| [GET /v2/pnl/wallets/\{wallet}/tokens/\{token}](/data-api/pnl-v2/get-wallet-token-position) | Single position detail                 |
| [GET /v2/pnl/wallets/\{wallet}/history](/data-api/pnl-v2/get-wallet-daily-history)          | Daily PnL snapshots                    |
| [GET /v2/pnl/wallets/\{wallet}/chart](/data-api/pnl-v2/get-wallet-chart)                    | Chart data points                      |
| [GET /v2/pnl/wallets/\{wallet}/performance](/data-api/pnl-v2/get-wallet-performance)        | Streaks, drawdown, best/worst days     |
| [GET /v2/pnl/wallets/\{wallet}/highlights](/data-api/pnl-v2/get-wallet-highlights)          | Biggest winners, losers, flips         |
| [GET /v2/pnl/wallets/\{wallet}/risk](/data-api/pnl-v2/get-wallet-risk)                      | Concentration and open exposure        |

### Token Endpoints

| Endpoint                                                                            | What it returns                                            |
| ----------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| [GET /v2/pnl/tokens/\{token}/traders](/data-api/pnl-v2/get-token-traders)           | Every wallet that traded this token                        |
| [GET /v2/pnl/tokens/\{token}/first-buyers](/data-api/pnl-v2/get-token-first-buyers) | Earliest buyers only (`sort=first_trade`, `direction=asc`) |

### Leaderboard Endpoints

| Endpoint                                                                                 | What it returns                                  |
| ---------------------------------------------------------------------------------------- | ------------------------------------------------ |
| [GET /v2/pnl/leaderboard/kols](/data-api/pnl-v2/get-kol-leaderboard)                     | KOL rankings (all-time)                          |
| [GET /v2/pnl/leaderboard/kols/period](/data-api/pnl-v2/get-kol-leaderboard-for-a-period) | KOL rankings for a time window                   |
| [GET /v2/pnl/leaderboard/kols/calendar](/data-api/pnl-v2/get-kol-calendar)               | Daily KOL performance for a month                |
| [GET /v2/pnl/leaderboard/kols/date](/data-api/pnl-v2/get-kol-daily-breakdown)            | Per-KOL breakdown for one day                    |
| [GET /v2/pnl/leaderboard/top](/data-api/pnl-v2/get-top-traders)                          | Solana Traders Leaderboard over a rolling window |

### Batch Endpoints

| Endpoint                                                                                      | What it returns                               |
| --------------------------------------------------------------------------------------------- | --------------------------------------------- |
| [POST /v2/pnl/wallets/\{wallet}/positions/batch](/data-api/pnl-v2/get-wallet-batch-positions) | One wallet → many tokens                      |
| [POST /v2/pnl/tokens/\{token}/positions/batch](/data-api/pnl-v2/get-token-batch-positions)    | One token → many wallets                      |
| [POST /v2/pnl/positions/batch](/data-api/pnl-v2/get-position-batch-lookup)                    | Any wallet-token pairs                        |
| POST /v2/pnl/wallets/batch                                                                    | Wallet summaries + tags for up to 100 wallets |

***

## Key Concepts

### Realized vs Unrealized PnL

<AccordionGroup>
  <Accordion title="Realized PnL">
    Profit or loss from tokens you've **sold**. This is locked in — it doesn't change.
  </Accordion>

  <Accordion title="Unrealized PnL">
    Paper profit or loss on tokens you **still hold**. Changes with every price tick.
  </Accordion>

  <Accordion title="Total PnL">
    `realized + unrealized`. The full picture.
  </Accordion>
</AccordionGroup>

### Wallet Coverage

PnL V2 covers all Solana wallets from **December 2023 onward**. Wallets are not indexed on request.

### Pagination

List endpoints use **cursor-based pagination**. Grab `pagination.nextCursor` from the response and pass it as the `cursor` query parameter to get the next page.

```bash theme={null}
# First page
curl "https://data.solanatracker.io/v2/pnl/wallets/{wallet}/positions?limit=50" \
  -H "x-api-key: YOUR_API_KEY"

# Next page (use cursor from previous response)
curl "https://data.solanatracker.io/v2/pnl/wallets/{wallet}/positions?limit=50&cursor=eyJ..." \
  -H "x-api-key: YOUR_API_KEY"
```

### Wallet Identity

Every wallet-scoped response includes a structured `identity` object. It merges multiple sources so a wallet can carry several labels at once (e.g. `["kol", "developer", "axiom"]`). Only populated fields are returned:

| Tag             | Meaning                                                                                                          |
| --------------- | ---------------------------------------------------------------------------------------------------------------- |
| `kol`           | Tracked KOL wallet. Includes `name`, `twitter`, `avatar`.                                                        |
| `bot`           | Curated named bot (e.g. Mayhem Bot).                                                                             |
| `potential_bot` | Heuristically detected bot — softer signal.                                                                      |
| `arbitrage`     | Confirmed MEV / arbitrage operator.                                                                              |
| `hacker`        | Curated exploit / scam wallet label. Includes `hacker.label`.                                                    |
| `spam_dusting`  | Curated spam-dusting wallet label. Includes `spamDusting.label`.                                                 |
| `exchange`      | Known centralized exchange hot wallet. Includes `exchange.name`.                                                 |
| `pool`          | Wallet is a pool vault, authority, LP mint, or bonding curve account. Includes `program` and `poolAddress`.      |
| `developer`     | Wallet is a token creator, pool deployer, or mint authority. Includes `via`, `pools`, `creationTx`, `createdAt`. |
| Platform tags   | `axiom`, `bloom`, `photon`. `axiom-flash` is accepted as a query alias and surfaces as `axiom`.                  |
| `sns`           | Primary `.sol` domain for the wallet (Solana Name Service). Includes `sns.domain`.                               |

On token-scoped endpoints (`/tokens/:token/traders`, `/first-buyers`, `/tokens/:token/positions/batch`) the `pool` and `developer` roles are resolved for the exact token in the path, so you can spot devs, LPs, and snipers inline without extra requests. See the [Solana Wallet Tags guide](/guides/pnl-v2/wallet-tags) for the full supported tag list.

### Enrichment on `/tokens/:tokenAddress/holders`

The classic holders endpoint accepts an optional `?enrich=` parameter:

* `?enrich=identity` — adds pool / developer / platform identity per holder.
* `?enrich=walletPnl` — adds lifetime wallet PnL plus per-token PnL per holder.
* `?enrich=all` — both.

When omitted, the endpoint behaves exactly as before with no extra work.

### Real-Time via Datastream

Pair these REST endpoints with the Datastream PnL V2 WebSocket rooms for live updates. Available on Premium, Business, and Enterprise plans:

| Room                   | Emits                          | Scope                                                                               |
| ---------------------- | ------------------------------ | ----------------------------------------------------------------------------------- |
| `pnl:{wallet}:{token}` | `tradeUpdate`, `balanceUpdate` | One token position                                                                  |
| `pnl:{wallet}`         | `tradeUpdate`, `balanceUpdate` | Every token the wallet trades                                                       |
| `pnl:{wallet}:summary` | Total wallet PnL summary       | Aggregated realized/unrealized PnL, ROI, counts, averages, and open-position totals |

Typical pattern: call `GET /v2/pnl/wallets/:wallet` once to seed state, then subscribe to `pnl:{wallet}:summary` to keep it in sync.

For the **fastest unrealized PnL ticks**, combine a PnL room with a price stream — `price:aggregated:{token}` (cross-pool, recommended) or `price-by-token:{token}` (primary pool). PnL rooms emit `tradeUpdate` and `balanceUpdate` on every fill plus an occasional throttled `priceUpdate`; the price rooms tick on every market move. Walkthrough in the [PnL V2 Datastream guide](/guides/datastream-pnl#fastest-live-unrealized-pnl-combining-rooms).