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

# 概览

> Solana Tracker PnL V2 的工作原理——端点分组、关键概念、分页方式、身份标签、排除资产以及实时钱包 PnL 更新机制。

<Info>
  **基础 URL:** `https://data.solanatracker.io`\
  **认证:** 在 `x-api-key` 请求头中传递您的 API 密钥。\
  **数值:** 所有货币金额均为美元。除非另行说明,时间戳均为 Unix 毫秒。
</Info>

## 要点

### PnL V2 涵盖的内容

* **规模。** PnL 为约 **3–4 亿个钱包**追踪,包含数十亿代币持仓,接近实时更新。
* **代币覆盖。** 支持每个 SPL 代币,**稳定币和 SOL 除外**。
* **钱包端点。** 钱包端点可用于任何钱包,即使该钱包不在排行榜上。
* **身份标签。** 钱包可以包含 `identity` 对象,带有 KOL、机器人、交易所、池、开发者或交易平台等标签。

### PnL V2 排除的内容

稳定币和 SOL 故意从 PnL 持仓中排除,因为它们是报价资产。报价资产是用于为交易定价的代币,而不是被测量的持仓。

默认情况下,使用 `excludeArbitrage=true` 排除套利钱包。套利 PnL 可能噪声很大,因为这些钱包通常为了池之间的微小差异交易。传入 `excludeArbitrage=false` 以包含它们。

顶级交易者排行榜覆盖每个时段的**前 50 万个钱包**。如果某个钱包在排名集之外,请直接使用钱包端点查询。

### 身份标签

每个钱包都可以携带结构化的 `identity`。当前支持:

* **机器人和 MEV** — `potential_bot`(启发式)、`bot`(策划的具名机器人,如 Mayhem Bot)、`arbitrage`(已确认的 MEV)。
* **平台** — `axiom`、`bloom` 和 `photon`。API 也接受 `axiom-flash` 作为 `axiom` 的别名。
* **安全 / 基础设施标签** — 已知时使用策划的 `hacker`、`spam_dusting` 和 `exchange` 标签。
* **池和开发者** 角色在代币范围的端点上自动解析。

### PnL 模式

钱包摘要、持仓、单一持仓、顶级交易者排行榜和持仓批量端点接受 `?pnlMode=`。

| 模式           | 行为                                                        |
| ------------ | --------------------------------------------------------- |
| `strict`(默认) | 最安全的视图。排除卖出数量大于买入数量的持仓,这通常意味着 PnL 无效或具有误导性。               |
| `adjusted`   | 保留这些持仓,但使用调整后的成本基础重新计算已实现 PnL。当 strict 模式隐藏了您仍想显示的持仓时很有用。 |
| `raw`        | 不过滤。已实现 PnL 按计算值原样返回。需要未过滤数据时使用。                          |

支持 `pnlMode` 的端点会在响应中回显该参数。持仓行同时包含 `pnl.realized`(感知模式)和 `pnl.realizedRaw`(未过滤),以便您的 UI 无需重新查询即可切换。

KOL 排行榜、历史、图表、表现、亮点、风险、代币交易者、首批买家以及钱包摘要批量端点不接受 `pnlMode`;它们返回该数据集 API 固定的服务器端视图。

***

## 什么是 PnL V2?

PnL V2 追踪每个 Solana 钱包的盈亏。给它一个钱包地址,它会返回:

* 带有总 PnL、胜率和代币数量的**摘要**
* 带有成本基础、当前价值以及已实现/未实现 PnL 的**每个代币持仓**
* 用于权益曲线的**每日历史**和图表数据
* KOL 和顶级交易者的**排行榜**
* 带有集中度和敞口指标的**风险分析**
* 一次性查询数百个钱包-代币对的**批量查询**

<CardGroup cols={2}>
  <Card title="钱包分析" href="/cn/data-api/pnl-v2/get-wallet-summary">
    任意钱包的 PnL 摘要、持仓、每日历史、表现和风险。
  </Card>

  <Card title="代币情报" href="/cn/data-api/pnl-v2/get-token-traders">
    某个代币上的每位交易者——谁赚了钱、谁被套住、谁先买入。
  </Card>

  <Card title="排行榜" href="/cn/data-api/pnl-v2/get-kol-leaderboard">
    带有滚动窗口和日历视图的 KOL 和顶级交易者排名。
  </Card>

  <Card title="批量操作" href="/cn/data-api/pnl-v2/get-position-batch-lookup">
    在一次请求中获取数百个 wallet+token 对的持仓。
  </Card>
</CardGroup>

***

## 端点分组

<Columns cols={2}>
  <Card title="已知道端点?" href="/cn/data-api/pnl-v2/get-wallet-summary">
    直接前往 API 参考查看 schema 和参数。
  </Card>

  <Card title="正在构建工作流?" href="/cn/guides/pnl-v2/wallet-analysis">
    继续阅读下方的分步指南。
  </Card>
</Columns>

### 钱包端点

| 端点                                                                                             | 返回内容           |
| ---------------------------------------------------------------------------------------------- | -------------- |
| [GET /v2/pnl/wallets/\{wallet}](/cn/data-api/pnl-v2/get-wallet-summary)                        | PnL 摘要、胜率、代币数量 |
| [GET /v2/pnl/wallets/\{wallet}/positions](/cn/data-api/pnl-v2/get-wallet-positions)            | 所有持仓,可排序和过滤    |
| [GET /v2/pnl/wallets/\{wallet}/tokens/\{token}](/cn/data-api/pnl-v2/get-wallet-token-position) | 单个持仓详情         |
| [GET /v2/pnl/wallets/\{wallet}/history](/cn/data-api/pnl-v2/get-wallet-daily-history)          | 每日 PnL 快照      |
| [GET /v2/pnl/wallets/\{wallet}/chart](/cn/data-api/pnl-v2/get-wallet-chart)                    | 图表数据点          |
| [GET /v2/pnl/wallets/\{wallet}/performance](/cn/data-api/pnl-v2/get-wallet-performance)        | 连胜、回撤、最佳/最差日   |
| [GET /v2/pnl/wallets/\{wallet}/highlights](/cn/data-api/pnl-v2/get-wallet-highlights)          | 最大赢家、输家、反转     |
| [GET /v2/pnl/wallets/\{wallet}/risk](/cn/data-api/pnl-v2/get-wallet-risk)                      | 集中度和未结敞口       |

### 代币端点

| 端点                                                                                     | 返回内容                                      |
| -------------------------------------------------------------------------------------- | ----------------------------------------- |
| [GET /v2/pnl/tokens/\{token}/traders](/cn/data-api/pnl-v2/get-token-traders)           | 交易过此代币的每个钱包                               |
| [GET /v2/pnl/tokens/\{token}/first-buyers](/cn/data-api/pnl-v2/get-token-first-buyers) | 仅最早买家(`sort=first_trade`、`direction=asc`) |

### 排行榜端点

| 端点                                                                                          | 返回内容                |
| ------------------------------------------------------------------------------------------- | ------------------- |
| [GET /v2/pnl/leaderboard/kols](/cn/data-api/pnl-v2/get-kol-leaderboard)                     | KOL 排名(全时段)         |
| [GET /v2/pnl/leaderboard/kols/period](/cn/data-api/pnl-v2/get-kol-leaderboard-for-a-period) | 某时间窗口内的 KOL 排名      |
| [GET /v2/pnl/leaderboard/kols/calendar](/cn/data-api/pnl-v2/get-kol-calendar)               | 某月每日的 KOL 表现        |
| [GET /v2/pnl/leaderboard/kols/date](/cn/data-api/pnl-v2/get-kol-daily-breakdown)            | 某一天每个 KOL 的细分       |
| [GET /v2/pnl/leaderboard/top](/cn/data-api/pnl-v2/get-top-traders)                          | 滚动窗口的 Solana 交易者排行榜 |

### 批量端点

| 端点                                                                                               | 返回内容               |
| ------------------------------------------------------------------------------------------------ | ------------------ |
| [POST /v2/pnl/wallets/\{wallet}/positions/batch](/cn/data-api/pnl-v2/get-wallet-batch-positions) | 一个钱包 → 多个代币        |
| [POST /v2/pnl/tokens/\{token}/positions/batch](/cn/data-api/pnl-v2/get-token-batch-positions)    | 一个代币 → 多个钱包        |
| [POST /v2/pnl/positions/batch](/cn/data-api/pnl-v2/get-position-batch-lookup)                    | 任意 wallet-token 对  |
| POST /v2/pnl/wallets/batch                                                                       | 最多 100 个钱包的摘要 + 标签 |

***

## 关键概念

### 已实现 PnL 与未实现 PnL

<AccordionGroup>
  <Accordion title="已实现 PnL">
    您**已卖出**代币的盈亏。这是锁定的——不会变化。
  </Accordion>

  <Accordion title="未实现 PnL">
    您**仍持有**代币的账面盈亏。每次价格跳动都会变化。
  </Accordion>

  <Accordion title="总 PnL">
    `已实现 + 未实现`。完整画面。
  </Accordion>
</AccordionGroup>

### 钱包覆盖

PnL V2 覆盖**2023 年 12 月以后**的所有 Solana 钱包。钱包不会按请求索引。

### 分页

列表端点使用**基于游标的分页**。从响应中获取 `pagination.nextCursor`,并将其作为 `cursor` 查询参数传入以获取下一页。

```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"
```

### 钱包身份

每个钱包范围的响应都包含一个结构化的 `identity` 对象。它合并多个来源,因此钱包可以同时携带多个标签(例如 `["kol", "developer", "axiom"]`)。仅返回已填充的字段:

| 标签              | 含义                                                                       |
| --------------- | ------------------------------------------------------------------------ |
| `kol`           | 受追踪的 KOL 钱包。包含 `name`、`twitter`、`avatar`。                                |
| `bot`           | 策划的具名机器人(例如 Mayhem Bot)。                                                 |
| `potential_bot` | 启发式检测到的机器人——较弱的信号。                                                       |
| `arbitrage`     | 已确认的 MEV / 套利运营商。                                                        |
| `hacker`        | 策划的漏洞利用 / 诈骗钱包标签。包含 `hacker.label`。                                      |
| `spam_dusting`  | 策划的垃圾粉尘攻击钱包标签。包含 `spamDusting.label`。                                    |
| `exchange`      | 已知的中心化交易所热钱包。包含 `exchange.name`。                                         |
| `pool`          | 钱包是池金库、authority、LP mint 或联合曲线账户。包含 `program` 和 `poolAddress`。           |
| `developer`     | 钱包是代币创建者、池部署者或 mint authority。包含 `via`、`pools`、`creationTx`、`createdAt`。 |
| 平台标签            | `axiom`、`bloom`、`photon`。`axiom-flash` 作为查询别名被接受,在响应中显示为 `axiom`。        |

在代币范围的端点(`/tokens/:token/traders`、`/first-buyers`、`/tokens/:token/positions/batch`)上,`pool` 和 `developer` 角色针对路径中的确切代币解析,因此您可以行内发现开发者、LP 和狙击者,而无需额外请求。完整支持的标签列表请参阅 [Solana 钱包标签指南](/cn/guides/pnl-v2/wallet-tags)。

### `/tokens/:tokenAddress/holders` 上的丰富化

经典 holders 端点接受可选的 `?enrich=` 参数:

* `?enrich=identity` — 为每个持有者添加 pool / developer / platform 身份。
* `?enrich=walletPnl` — 为每个持有者添加终身钱包 PnL 加每代币 PnL。
* `?enrich=all` — 两者都加。

省略时,该端点行为与之前完全相同,不增加额外工作。

### 通过 Datastream 实时

将这些 REST 端点与 Datastream PnL V2 WebSocket room 配对以获得实时更新。适用于 Premium、Business 和 Enterprise 方案:

| Room                   | 发出                            | 范围                            |
| ---------------------- | ----------------------------- | ----------------------------- |
| `pnl:{wallet}:{token}` | `tradeUpdate`、`balanceUpdate` | 单个代币持仓                        |
| `pnl:{wallet}`         | `tradeUpdate`、`balanceUpdate` | 钱包交易的每个代币                     |
| `pnl:{wallet}:summary` | 总钱包 PnL 摘要                    | 聚合已实现/未实现 PnL、ROI、计数、平均值和持仓总额 |

典型模式:调用 `GET /v2/pnl/wallets/:wallet` 一次以播种状态,然后订阅 `pnl:{wallet}:summary` 保持同步。

为获得**最快的未实现 PnL 跳动**,将 PnL room 与价格流组合 — `price:aggregated:{token}`(跨池,推荐)或 `price-by-token:{token}`(主池)。PnL room 在每次成交时推送 `tradeUpdate` 和 `balanceUpdate`,以及偶尔受限速的 `priceUpdate`;价格 room 在每次市场变动时跳动。完整流程参见 [PnL V2 Datastream 指南](/cn/guides/datastream-pnl#fastest-live-unrealized-pnl-combining-rooms)。